list_attachments

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

Annotations only declare readOnlyHint=true, and the description goes well beyond that: no pagination and no fields projection, asymmetric step aggregation verified live, 404 for out-of-range stepIndex versus [] for an in-range step with no attachments, and [] rather than 404 for a nonexistent testResultId while a bogus case/run key errors. That is exactly the extra behavioral context the annotations cannot carry.

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?

Purpose, addressing rules, and constraints are front-loaded in that order, and the Cross-references to delete_attachment/download_attachment close the loop. The middle section is dense and runs several independent constraints into single sentences, so it is slightly heavier than needed, but nearly every clause carries distinct information.

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?

There is no output schema, and the description compensates by describing the return value: the API's array of attachment records as-is, each carrying the numeric id delete_attachment needs and the url download_attachment accepts. Combined with the error semantics and per-target rules, nothing an agent needs to call this 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: which target/identifier pairing is required, that an unmatched identifier is rejected, and the divergent error behavior of stepIndex and testResultId (404 vs []). It stops short of restating formats for every field, but the additions are meaningful rather than duplicative.

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 (List) and resource (attachments) and enumerates the exact entity families it covers: test case, test run/cycle, test result, or a single step of a case/result, with the concrete URL templates. It is clearly distinguishable from the Jira sibling jira_list_attachments and from download_attachment/delete_attachment, which it references by name.

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?

Explicitly maps each target enum value to its required identifier ('test_case' needs testCaseKey, 'test_run' needs testRunKey, 'test_result' needs testResultId), states that mismatched identifiers are rejected, and restricts stepIndex to 'test_case'/'test_result'. It even gives the operational consequence for step enumeration (one extra call per step for cases; double-counting risk for results).

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