diffchunk

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 effectively describes key behaviors: auto-loading diff files if not loaded, handling large diffs in manageable portions, and the need for absolute paths (with a warning about relative paths failing). It also mentions progress tracking and cleanup recommendations. However, it doesn't cover error conditions, performance characteristics, or authentication needs, leaving some behavioral aspects unspecified.

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 appropriately sized and front-loaded with the core purpose in the first sentence. Subsequent sentences add necessary context, warnings, and usage guidelines. While slightly verbose with multiple recommendations, each sentence earns its place by providing distinct value (e.g., path warning, context window limitation, sibling tool relationships, progress tracking advice).

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's moderate complexity (3 parameters, no annotations, no output schema), the description provides good contextual completeness. It covers purpose, usage guidelines, behavioral aspects, and parameter warnings. However, without an output schema, it doesn't describe return values or formats, and it lacks information about error handling or rate limits. For a read operation with full parameter documentation, this is reasonably complete but has minor gaps.

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 schema already documents all three parameters thoroughly. The description adds some context about 'absolute_file_path' (critical warning about absolute vs. relative paths) and implies chunk numbering (1-indexed through 'specific numbered chunk'), but doesn't provide additional semantic meaning beyond what's in the schema. This meets the baseline expectation when schema coverage is high.

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 clearly states the tool's purpose with specific verbs ('retrieve content', 'auto-loads') and resources ('specific numbered chunk from a diff file'). It distinguishes from siblings by mentioning when to use it ('for systematic analysis chunk-by-chunk' vs. 'list_chunks' or 'find_chunks_for_files' for identification). The description goes beyond the name/title to explain the core functionality.

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 provides explicit guidance on when to use this tool ('for systematic analysis of changes chunk-by-chunk', 'to examine specific chunks identified via list_chunks or find_chunks_for_files') and when not to use alternatives ('DO NOT read diff files directly - they exceed LLM context windows'). It names sibling tools (list_chunks, find_chunks_for_files) and explains their relationship, offering clear context for tool selection.

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