Problem
RPC descriptions are maintained in two places:
- Proto files — comments above RPC definitions (sparse, inconsistent)
- descriptions.yaml — comprehensive natural-language descriptions used by
mcp-openapi to generate agent-facing tool docs
These two sources can drift. When a new RPC is added, the descriptions.yaml entry is written in the same PR (per the file's header comment), but the proto comment may not match — or may not exist at all. Over time this creates confusion about which is canonical.
Proposed solution
Make proto comments the single source of truth:
1. Enrich proto files with structured comments
// Evaluate an agent action against workspace safety rules.
// Returns ALLOW, DENY, or REQUIRE_APPROVAL with risk level and matched rule IDs.
// Must be called before CI modifications, email sends, CRM mutations, and any
// action classified RISK_LEVEL_MEDIUM or above.
rpc EvaluateAction(EvaluateActionRequest) returns (EvaluateActionResponse);
2. Generate descriptions.yaml from proto comments
Add a script or buf plugin that extracts leading comments from each rpc definition and writes them to descriptions.yaml. Run it in CI; fail if the generated file differs from the committed one (same pattern as buf generate staleness checks).
3. Migrate existing descriptions into proto comments
The 120+ descriptions in descriptions.yaml are already written and high quality. This is a one-time migration: copy each description into the corresponding proto file as a leading comment, then verify the generator reproduces the original YAML.
Why this matters
descriptions.yaml is the bridge between your proto definitions and agent behavior. When an agent reads "Must be called before CI modifications, email sends, CRM mutations," it follows that instruction. Keeping those descriptions in the proto file — right next to the RPC they describe — means they get reviewed in the same PR as schema changes, show up in buf documentation, and can't drift.
Problem
RPC descriptions are maintained in two places:
mcp-openapito generate agent-facing tool docsThese two sources can drift. When a new RPC is added, the
descriptions.yamlentry is written in the same PR (per the file's header comment), but the proto comment may not match — or may not exist at all. Over time this creates confusion about which is canonical.Proposed solution
Make proto comments the single source of truth:
1. Enrich proto files with structured comments
2. Generate descriptions.yaml from proto comments
Add a script or buf plugin that extracts leading comments from each
rpcdefinition and writes them todescriptions.yaml. Run it in CI; fail if the generated file differs from the committed one (same pattern asbuf generatestaleness checks).3. Migrate existing descriptions into proto comments
The 120+ descriptions in
descriptions.yamlare already written and high quality. This is a one-time migration: copy each description into the corresponding proto file as a leading comment, then verify the generator reproduces the original YAML.Why this matters
descriptions.yamlis the bridge between your proto definitions and agent behavior. When an agent reads "Must be called before CI modifications, email sends, CRM mutations," it follows that instruction. Keeping those descriptions in the proto file — right next to the RPC they describe — means they get reviewed in the same PR as schema changes, show up inbufdocumentation, and can't drift.