treesitter_get_source_for_range

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

With no annotations, the description effectively discloses behavior by detailing both return modes (inline source text or writing to an output file) and the reason for the output_file mode. It also provides the 0-based indexing context for coordinates. However, it does not mention potential errors or edge cases like out-of-bounds ranges, which would be useful but not critical for this read-only operation.

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, starting with a one-sentence purpose, followed by a clear Args list and Returns specification. It is compact without unnecessary fluff. The Args section repeats parameter names from the schema, but it's justified because it adds crucial detail about row/column conventions and output_file semantics.

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 lack of annotations and output schema, the description does a strong job of covering all parameters, both return modes, and the rationale for the output_file option. It stops short of defining range inclusivity (e.g., whether end_row/end_column are exclusive), which could lead to off-by-one errors. Overall, it is sufficiently complete for an experienced user.

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?

The schema parameters are minimally described (e.g., 'End Row'), but the description attaches meaning to every parameter in the Args section, including their 0-based nature and the output_file behavior. This fully compensates for the 0% schema description coverage, making the parameters self-explanatory.

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 function: 'Extract the source code text for a given line/column range.' This specific verb and resource distinguish it from sibling tools like treesitter_get_node_for_range, which extracts AST nodes, and treesitter_run_query, which runs queries. The scope is unambiguous.

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 implies usage when raw source text for a range is needed, but it does not explicitly mention when to use this tool over alternatives like get_node_for_range or cursor_walk. It does provide a specific guideline for the output_file parameter (useful for large outputs to prevent context overload), but lacks broader contextual guidance or exclusions.

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