get_file_summary

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

With no annotations, the description carries the full burden and does disclose a key trait: no index needed, so it works on unindexed files. It also bounds the payload ('lightweight', first N lines). It omits error behavior for missing files and whether language support is limited, keeping it short of a 5.

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 core purpose is front-loaded in the first sentence, and the Args/Returns blocks are terse and scannable. No filler sentences.

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?

An output schema exists, so return values need only a headline, which is provided. Combined with per-parameter docs and the indexing caveat, the description is sufficient to call the tool correctly; only edge-case behavior is absent.

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 the description must compensate, and it does: path is defined as relative to project root, and max_lines is explained as content lines to include with the default 50 restated. Only missing detail is units/validation semantics for max_lines.

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?

States a specific verb and resource ('Returns a lightweight summary of a file') and enumerates exactly what the summary contains: size, imports, top-level definitions, and first N lines. The 'Does NOT require indexing' clause distinguishes it from indexed siblings like search_codebase, though no sibling is named explicitly.

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?

Usage is implied by the 'lightweight' and 'does NOT require indexing' framing — an agent can infer this is a cheap peek before or instead of indexing — but there is no explicit when-to-use/when-not statement and no named alternative such as get_file_relations or search_codebase.

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