files_read_outline

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

With no annotations provided, the description carries the full burden and does so: it declares read-only behavior, no side effects, no auth requirement, and no rate limits — exactly the behavioral context an agent needs. It also discloses the empty-result edge case and its different meaning (no headings versus no content).

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?

Three sentences, each earning its place: purpose, safety profile, then the decision guidance and fallback. The core capability and return shape are front-loaded before the routing 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?

No output schema exists, but the description compensates by naming the returned fields and explaining the empty-outline case. For a simple single-parameter read tool with a fully covered schema, nothing an agent needs in order to invoke it correctly is missing.

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 single file_id parameter is already documented (albeit thinly as 'File ID'), which sets the baseline at 3. The description adds marginal value by using the parameter in example calls, implicitly flagging that this tool uses file_id while files_read uses id, but it doesn't explain what a file ID is or how to obtain one.

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 ('Return a flat list of markdown headings for one file') and enumerates the exact return fields (level, text, line, byteStart, byteEnd). This clearly distinguishes it from siblings like files_read (full body) and files_regex_search without needing their schemas.

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?

Explicitly positions the tool as a 'cheap probe before files_read({ id, section }) or files_update({ file_id, section, content })', naming the alternatives and the condition (avoid spending tokens on the full body). It also covers the exclusion case: an empty outline means no headings, so fall back to files_read or files_read({ id, lines }).

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