QMetry: Fetch Test Case Steps

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds useful behavioral context on top: the output structure (array of steps with description, expected result, order), pagination defaults, and the numeric-ID vs entityKey distinction.

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 well-organized with clear sections: What it does, Parameters, Output, Use Cases, Examples, and Hints. It is somewhat lengthy but every section earns its place, especially the concise hints that highlight critical call requirements.

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 annotations cover safety, schema covers all parameters, and the description explains output and use cases with an example, there is nothing missing. An agent can correctly select this tool, resolve prerequisites, and interpret the response without external knowledge.

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 schema already documents all six parameters in detail. The description largely repeats this information, though it adds value by clarifying the ID/entityKey distinction and default version behavior. With full schema coverage, a baseline 3 is appropriate.

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 tool fetches test case steps for a specific test case by numeric ID, with a specific verb and resource. It also distinguishes itself by explicitly noting the ID is an internal numeric identifier, not the entity key like 'MAC-TC-1684', which helps differentiate it from other test case tools.

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 'Hints' section explicitly states the tool requires a numeric ID and instructs agents to resolve entity keys via FETCH_TEST_CASES first. It also provides clear context for when to use pagination and the default version behavior. This is strong when-to-use guidance that also names the alternative resolution path.

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