QMetry: Fetch Test Run UDF Metadata

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no contradiction exists. The description adds substantial behavioral context beyond that: the exact response shape (fields array + lookupOptions map), the empty-lookupOptions failure mode and required user action, the mapping between fieldID and projectUserFieldID, and the resolved-value behavior for LOOKUPLIST/MULTILOOKUPLIST fields. It transparently discloses a known API limitation and instructs the agent not to guess.

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-structured with clear Markdown sections (Toolset, Parameters, Output Description, Use Cases, Examples, Hints) and is front-loaded with the core purpose. It is on the verbose side — the Examples section largely repeats the Output Description, and Hints #3 and #5 are dense — but every major section earns its place given the complexity of UDF metadata and its downstream use in bulk updates.

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?

Despite having no output schema, the description fully specifies the output structure, enumerates use cases, gives an invocation example, and documents edge cases (empty lookupOptions, DATE format, lookup item id semantics). It even coordinates with sibling tools like Bulk Update Test Run UDFs and Fetch Test Run UDF Values. For a single-parameter read-only tool, nothing an agent needs to call it correctly is missing.

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 schema coverage is 100%, so the schema already documents projectKey with type, default, and description. The description's Parameters section largely repeats the schema, adding no new semantic detail beyond the context that fields are 'configured in this QMetry project.' Per the baseline rule for high schema coverage, a 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 opens with a specific verb and resource: 'Fetch the metadata (field definitions) for all Test Run UDF ... configured in this QMetry project.' It clearly distinguishes itself from the sibling qmetry_fetch_test_run_udf_values (fetches values, not metadata) and qmetry_bulk_update_test_run_udfs (writes, not fetches). The intended output — field names, labels, types, and fieldID — is explicit.

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 says 'ALWAYS call this tool before Bulk Update Test Run UDFs' and states it is the authoritative source of fieldIDs, with explicit 'do NOT guess or hard-code' guidance. It also provides concrete use cases, including when a user just asks what Test Run UDF fields are available, and explains how LOOKUPLIST/MULTILOOKUPLIST values are resolved by sibling value-fetching tools. This is explicit when-to-use and when-not-to-guess guidance, naming the relevant alternative.

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