QMetry: Fetch Test Case Details

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds contextual transparency: it explains that the tool uses a numeric ID (not entity key), does not persist UI filters, and provides output description. While it doesn't disclose any negative traits (none exist), it adds useful context beyond annotations. Score 4 for adding value without contradictions.

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 long but well-structured with clear sections (purpose, parameters, use cases, examples, hints). It is front-loaded with the core purpose and key usage. While some repetition exists (e.g., parameter descriptions duplicated from schema), the structure makes it easy to scan. A slightly more concise version could exist, but the format is effective for a complex tool.

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 no output schema, the description provides an adequate output description. It covers use cases, examples, and hints that fill gaps. It tells the agent how to handle entity keys and when to use this tool vs others. The only minor gap is not explicitly stating return format details, but the examples and output description are sufficient. Overall, complete for the task.

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 coverage is 100%, so the baseline is 3. The description adds significant value by explaining the critical tcID parameter: it emphasizes the exact parameter name ('tcID'), clarifies it is a numeric internal identifier (not entity key), and provides examples. It also lists use cases and hints for parameter usage. This goes beyond the schema's description.

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's purpose: 'Get detailed information for a specific QMetry test case by numeric ID' and emphasizes it's for single test case lookup. It distinguishes from siblings like qmetry_fetch_test_cases and qmetry_fetch_test_case_steps by specifying that this tool is for single test case details, not listing or step-level data.

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 provides explicit guidelines: 'USE THIS for single test case lookup', 'ALWAYS prefer this tool over FETCH_TEST_CASES with filters', and hints like when the user asks to 'fetch test case VKMCP-TC-5'. It also tells when not to use it (e.g., for step details use another tool) and offers alternative options for resolving entity keys. This is comprehensive and well-structured.

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