QMetry: Fetch Test Suite Details

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the description doesn't need to repeat safety. The description adds the output behavior: 'Returns a JSON object with full test suite details including UDFTypeData map and all UDF field values'. This clarifies what the caller receives but doesn't disclose additional behavioral traits like pagination, auth, or error handling. Given the annotations already cover the safety profile, the description provides adequate but not rich additional context.

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 sections: Toolset, Parameters, Output Description, Use Cases, and an Example. It is longer than necessary but every section adds value—especially the example and use cases. The main purpose is stated first, making it front-loaded. It could be trimmed of redundant parameter repetition, but the structure is clear and scannable.

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 fetch-by-id operation with a single required parameter, the description provides sufficient context: it explains the output shape (full suite details with UDF fields), gives a concrete example, and outlines common use cases. It doesn't describe error handling or edge cases, but for a read-only, idempotent operation with annotations covering safety, this is adequate. The absence of an output schema is compensated by the output description.

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?

The input schema covers 100% of parameters with descriptions (e.g., 'Test Suite ID (numeric ID)', 'Scope of the operation...'). The description repeats these exactly, adding no extra meaning beyond the schema. The description does tie parameters to use cases (e.g., id for specific suite) but that's implied. Since schema coverage is complete, the baseline is 3, and the description does not elevate it further.

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 full detail data for a QMetry test suite including UDF field values. It quickly differentiates from sibling tools like qmetry_fetch_test_suites (which lists suites) and qmetry_update_test_suite (which updates), by specifying it retrieves full details for a single suite. The verb 'Fetch' plus the specific resource 'test suite details' leaves no ambiguity.

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 'Use Cases' section explicitly states when to use this tool: to get UDF field values, retrieve full metadata, or inspect before updating UDF values. This provides clear context for selection. While it doesn't mention alternatives or when not to use it, the use cases implicitly distinguish it from listing or updating tools. The lack of explicit exclusions is a minor gap.

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