type_explain

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

No annotations are provided, so the description carries the behavioral burden. 'Explain from graph facts' does clearly signal a read-only, analysis-style operation and gives a reasonable sense of the output content. However, it does not disclose what happens for unknown types, how pagination behaves, or whether the graph must already be loaded, which keeps this from being fully transparent.

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 with a front-loaded verb and target, followed by a compact colon list of the relevant output types. It has no filler or redundant wording, though the role list is terse.

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 simple read-only type explanation, this is minimally usable on its own. But there is no output schema, no annotations, and several pagination-related parameters, and the description does not explain the provenance of the graph facts or the behavior of member_offset. Thus, it is moderately complete but leaves notable gaps for an agent to infer.

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?

Only one of the five properties ('format') has an in-schema description, so schema coverage is only 20%. The tool description does not compensate: it does not explain what string identifier 'type' expects, what 'member_offset' controls, or how 'limit' and 'offset' relate to fields versus method roles.

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 uses the specific verb 'Explain' and names the resource, a type, while also stating what the explanation contains: fields and constructor, mutator, consumer, and destructor method roles. It is clear what the tool does, though it does not explicitly contrast it with siblings such as callers, callees, or field_history.

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?

There is no when-to-use vs. when-not-to-use guidance, no prerequisite stated such as whether the graph must already be loaded, and no alternative tool named. The context implies this is for explaining a type from graph facts, but the large sibling set makes that insufficient for confident selection.

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