git_blame

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the return format (line count summary followed by git blame output with commit hashes, authors, line content), a mutual constraint (start_line and end_line must be provided together), and a prerequisite (file must be tracked by git). No contradiction with annotations.

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 well-structured with short labeled sections ('Best for', 'Returns', 'Does NOT'). Each sentence provides distinct, necessary information without redundancy. It is concise enough while covering purpose, usage, output, constraints, and exclusions.

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?

Given the tool has no output schema, the description compensates by explaining the return value in detail. It covers the main use case, key constraints, and alternatives. The schema already documents all parameters, and the description adds the missing behavioral context needed to invoke the tool correctly.

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 100%, so the baseline is 3. The description adds value by specifying that start_line and end_line must be provided together (a mutual requirement not present in the schema) and that the file must be tracked by git. It also clarifies that a line range is optional, but doesn't add formatting details for the parameters themselves.

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 specific action ('Render per-line attribution') and resource ('tracked file'), and explicitly distinguishes itself from siblings by noting it does not show current file content or whole-history log and pointing to git_show and git_log. The 'Best for' line further clarifies the tool's exact 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 includes explicit when-to-use guidance ('investigating who changed a line or when a regression was introduced, to trace how a file evolved') and names alternatives (git_show, git_log) with a clear exclusion ('Does NOT show... use...'). This fully satisfies the when-to-use and when-not-to-use criteria.

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