get_type_hierarchy

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the targeting mechanisms and direction options, but it does not disclose error handling (e.g., what happens if the class/interface doesn't exist), rate limits, or return format. The schema mentions error behavior for ambiguous symbols, but the description itself does not. Thus, transparency is adequate but not fully comprehensive.

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 three short sentences, each earning its place. The first sentence states the purpose, the second explains the direction parameter, and the third covers the two targeting methods. No wasted words, and the most important information is front-loaded.

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?

Given the tool has 5 parameters (one required, one enum, two alternative targeting methods) and no output schema, the description adequately covers the input options. However, it does not describe the output format (e.g., list of names, tree structure) or behavior when the target is not found. For a hierarchy query tool, mentioning the return shape would improve completeness.

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 baseline is 3. The description adds value beyond the schema by explaining the direction enum values in a readable way ('supertypes shows parents, subtypes shows implementations/extensions') and by summarizing the preferred targeting method ('symbol' name preferred, no need to know coordinates). This helps an agent understand the parameter semantics more intuitively.

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 verb ('Get'), resource ('type hierarchy'), and scope ('for a class/interface'). It explains the two directions ('supertypes' shows parents, 'subtypes' shows implementations/extensions). This distinguishes it from siblings like get_implementations (which may only list direct implementations) and get_type_definition (which goes to definition).

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 description mentions that targeting by 'symbol' name is preferred and explains the alternative explicit coordinates, but it does not provide explicit guidance on when to use this tool versus its many siblings (e.g., get_implementations, get_call_hierarchy). The usage context is implicit from the purpose, but no explicit when-to-use or when-not-to-use advice is given.

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