rms_file_history

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating 'no shell', lazy catch-up on query, default omission of commit messages, and commit-count budgets on catch-up/reindex. It does not detail side effects of reindex or exact budget behavior, but the disclosed behaviors are materially useful and not contradicted by any annotation.

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?

The description is compact and front-loaded: it opens with the core purposeable, then gives preference guidance, action context, defaults, and constraints. Every sentence adds distinct information without fluff or repetition, making it well-structured for quick agent scanning.

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?

The tool has no output schema)Skip the description explains the key operation, actions, defaults, and constraints, so an agent can select and invoke it correctly. The main gap is that return shape beyond commit messages is not described, such as which commit fields are included, but the schema and description are otherwise adequate for safe use.

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 description coverage is 100%, so the parameter semantics baseline is 3. The description reinforces action semantics such as 'use action=reindex' and 'requires explicit project', but it does not add meaning beyond what the schema already documents. The schema itself carries the parameter documentation load.

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 description states a precise operation and resource: 'Query the derived code_path git file→commit history cache (no shell).' This clearly identifies what the tool does and sets it apart from generic shell-based git commands or other search-style read tools. The phrase 'file→commit history cache' leaves no ambiguity about the purpose.

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?

The description gives explicit when-to-use guidance: 'Prefer this over `git log` for when a source file changed.' It also provides conditional action guidance, saying to use reindex after a force-push/rebase and that it requires an explicit `project`. This is strong routing and selection guidance.

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