Outline a file (signatures only)

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

The description discloses key behavioral traits: it returns only declarations with line numbers, not the body, and is compact. Since no annotations are provided, this transparency is valuable. It implies a read-only operation and sets expectations for output specificity, though it doesn't discuss edge cases or permissions.

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 two sentences with zero wasted words. It front-loads the key information (what the tool does) and adds a clear secondary usage hint, making it exemplary in brevity.

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?

The description adequately covers the tool's simple purpose: output format (declarations with line numbers) and intended use (orientation before reading). It doesn't elaborate on return formatting, but given the output schema absence and the straightforward nature of the tool, this is sufficient.

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 has low coverage (0%) for the single 'path' parameter, and the description offers only the phrase 'one file' to clarify that path should point to a file rather than a directory. This adds minimal meaning beyond the schema, lacking details about path format or constraints.

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: it creates a compact outline of a single file showing declarations with line numbers, explicitly excluding the body. This is specific and distinguishes it from siblings like read_lines or get_file_skeleton, which serve different purposes.

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 phrase 'Orient before reading' provides clear context for when to use this tool—as a preparatory step to get an overview before reading the full file. However, it does not explicitly mention alternatives or exclusions, so it falls short of a 5.

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