Explain feature

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

Annotations are absent, so the description carries the full burden. It does not explicitly state that the tool is read-only or non-destructive, but the nature of an 'explain' tool suggests safety. The description mentions it provides a sequence diagram and various analyses, which are outputs, but does not disclose caching behavior or performance implications. The refresh parameter in the schema indicates caching, but that is not in the description itself. The description adds some behavioral context but misses explicit side-effect disclosure.

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 a single sentence that front-loads the core purpose ('Deep dive on one feature') and then lists the coverage areas. It is concise, though the list of seven items is a bit long. The structure is clear and efficient, with no redundant wording.

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?

For a tool with no output schema, the description covers a wide range of what is returned (purpose, endpoints, use cases, roles, entities, files, findings, sequence diagram). It does not mention the output format (structured object vs text) or prerequisites beyond the feature name coming from scan_project, which is in the schema. The refresh behavior is in the parameter description. Overall, it is fairly complete for an analysis tool, though it could be more explicit about the output structure.

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 100%, so all parameters (root, feature, refresh) have descriptions in the schema. The tool description adds no extra meaning beyond what the schema provides; it does not clarify parameter relationships or usage nuances. Baseline 3 is appropriate because the schema already documents the parameters adequately.

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 states a specific verb ('deep dive') and resource ('one feature'), and enumerates the concrete deliverables: purpose signals, endpoints, use cases, roles, entities, files, findings, and a sequence diagram. This clearly distinguishes it from siblings like scan_project (which presumably scans broadly) and extract_endpoints (which only extracts endpoints). It is not a tautology.

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 'Deep dive on one feature' implies it is for in-depth analysis of a single feature, which suggests when to use it, but it does not explicitly contrast with alternatives or state when not to use it. There is no mention of other tools like extract_data_model or generate_diagram. The guidance is implied rather than explicit.

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