Outline symbols

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description goes further by disclosing the implementation cost model ('fast; single-file regex scan, no external indexer') and the return shape. The regex-scan note usefully implies the outline may miss symbols needing real parsing. Minor weakness: 'Batch-safe: yes' asserts a property without saying how batching is expressed in the inputs.

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?

Labeled, front-loaded, scannable lines (Use when / Avoid when / Speed / Output / Batch-safe) with no filler. The purpose sentence leads and the routing information follows immediately.

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?

With no output schema, the description correctly compensates by spelling out the returned fields (total_symbols, symbols[] with name/kind/line/signature), and it covers use, avoidance, and cost. However it leaves four of five input parameters unexplained, so an agent cannot judge how to scope symbol kinds, language, or result size.

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 only 20% — only relative_path is documented in the schema. The description says nothing about language, max_symbols, include_classes, or include_functions, so four of five parameters carry no semantics anywhere. The listed symbol kinds only loosely hint at the include_* flags and leave language and max_symbols entirely opaque.

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?

Names a specific verb (parse) and resource (source file symbol outline) and enumerates the symbol kinds returned plus line numbers, so the agent knows exactly what comes back. It differentiates from project_symbol_references and project_diff_files, but never mentions the sibling project_file_symbols, which from its name appears to overlap heavily with this tool.

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?

Explicit 'Use when' scoping (need file structure before reading/refactoring) and explicit 'Avoid when' exclusions that route to project_symbol_references for usages and project_diff_files for text diffs. This is the strongest part of the definition: the agent has a clear decision rule and named alternatives.

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