repogrammar_context

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations the description carries the full burden, and it discloses a lot: read-only nature, source-free behavior ('no source-span hydration and no family-query telemetry'), abstention semantics ('never false-selects', 'abstains with candidate handles'), fallback handling (UNKNOWN/FALLBACK/stale), and a setup/policy constraint ('run setup/resync/autosync only when user or project policy permits'). It omits latency/rate-limit or cost characteristics and only sketches the response envelope, but behavioral disclosure is well above average.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a long single block, but front-loaded with purpose and operation routing, and the size is defensible given five operations and ten parameters. Most sentences carry distinct operational content; the only drag is that inspect_readiness detail sits mid-paragraph before the generic defaults, slightly disrupting flow.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a ten-parameter, five-operation tool with no output schema, the description covers operation behavior and several return shapes (family ids as handles, summary token, per-dimension states, one recovery action), which is genuinely useful. But it leaves verbosity, token_budget, include_exceptions, and include_variations unaddressed and gives only partial guidance on how the modes interact with the responses, so it is not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 40%, so the description must compensate. It adds real meaning for mode ('Start with compact mode'), target, and within (scoped queryability report), and echoes the abstention behavior of against. However, token_budget, include_exceptions, include_variations, and verbosity are never explained in the description, leaving several parameters documented only by terse schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence states a specific verb+resource ('Read-only RepoGrammar pattern-family context') and the body enumerates the five operations (find_analogues, show_family, explain_deviation, check_conformance, inspect_readiness) with what each returns. An agent can distinguish the operations, though the dense prose makes the overall scope harder to grasp at a glance than a crisp statement would.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit routing per operation ('For find_analogues, explain_deviation, and check_conformance, pass...', 'Use show_family only with an exact family id', 'Use inspect_readiness (no target) for...'), plus defaults and exclusions ('Start with compact mode', 'do not request include_source_spans by default', 'Do not run repogrammar stats in normal agent loops', 'No silent setup'). When-to-use and when-not are both covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.