variant_get

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by explaining that core data is always returned at the top level and that sections request additional data, helping the agent anticipate response structure even without an output schema.

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, front-loads the core action, and wastes no words. The key facts—core data always returned and sections optional—are presented efficiently in the very first sentence.

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 tool has no output schema, so the description bears responsibility for explaining return behavior; it does so partially by mentioning top-level core fields and optional sections. However, it omits limit semantics, section-level output detail, and route selection among siblings, leaving meaningful gaps for an agent deciding how to call the tool and interpret results.

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 67%, with id and sections already documented in the schema. The description mentions 'sections' generically and names core response fields, but it does not clarify the semantics of the limit parameter, whose role remains ambiguous despite having defaults and bounds. Thus the description provides only partial value beyond the schema.

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 a specific verb ('Get') and resource ('detailed variant information'), and it clarifies that core fields are always returned while sections are optional. This distinguishes it from search-like siblings but does not explicitly contrast it with variant_oncokb or variant_trials, so it falls short of full sibling differentiation.

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 explains that sections are optional and that core data is always returned, but it provides no guidance on when to use this tool versus alternatives like variant_search or variant_oncokb. There is no explicit when-to-use, when-not-to-use, or alternative routing, which leaves the agent to infer usage context.

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