git_diff

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

Describes explicit execution timing and on_timeout options (continue_background, kill, return_partial), which adds useful behavioral context beyond the schema. However, does not disclose actual diff behavior, permissions, or side effects.

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?

Description is relatively concise (3 sentences) but poorly structured: it starts with the tool name then immediately jumps to timing details rather than stating purpose. Could be reordered for clarity.

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 10 parameters, 0% schema description, and no annotations, the description is grossly incomplete. It ignores most parameters, doesn't explain what the tool returns (despite having an output schema), and provides no context for the diff operation itself. An agent cannot use this tool correctly without missing essential information.

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 0%, so description must explain parameter meaning. It only explains timing-related parameters (expected_runtime_seconds, timeout_seconds, etc.) and on_timeout. Core diff parameters like ref, path, staged, file_path, context_lines are completely unexplained, leaving agent unable to understand their purpose.

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?

Description fails to state what git_diff does (e.g., compute differences between commits or working tree). Focus is on execution timing, not on the core operation. Does not distinguish from siblings like git_show or git_log.

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?

No guidance on when to use git_diff vs alternative git tools. Only gives advice on selecting timeout parameters, which is orthogonal to use-case context.

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