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

Annotations declare readOnlyHint=false, idempotentHint=true and destructiveHint=false. The description adds useful constraints: no silent gate substitution, explicit gate mapping, source/artifact digests, and 65536 source byte limit. But it does not explain what the digest is for, what happens on partial translation failure, or whether the target format must be a supported toolchain. Moderate value beyond annotations.

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?

Uses a tight Problem/Input/Result/Limits structure that is front-loaded and easy to scan. Each sentence earns a place, though the labels are terse and the input line is misleading relative to the schema.

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?

Output schema exists, so return-value detail is not required, and the description covers the core translation contract plus limits. However, for a 4-required-param tool with nested request object and 0% schema coverage, the definition omits critical parameter meaning, and the 'Input' line contradicts the actual required fields.

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 0% and the 4 top-level params (schema_version, request, idempotency_key, max_total_price) are entirely undocumented in the schema. The description says 'Input: JSON with source, target format' but the schema's required fields are different and nested, so it does not actually explain the required 'request' object or the pricing/idempotency fields. Fails to compensate for the coverage gap.

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?

States a specific verb+resource: translate OpenQASM 3 circuit to target toolchain format with explicit gate mapping. Distinguishes from siblings like translate_quantum_circuit by emphasizing 'without silent gate substitution' and the local toolchain target. Clear enough, though the hyphenated 'v1' naming is redundant with the title.

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?

Frames the task as 'Problem:' which implies when to use it, and mentions the input format. But it never says when NOT to use it or names an alternative such as translate_quantum_circuit or quantum_provider_target_compile, which appears to be the closest sibling. Usage is only implied.

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