get_release

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

The description goes substantially beyond the readOnly/idempotent/destructiveHint annotations, revealing critical behavior: status is a person-applied label and not a derived verdict; manual rollups count executions only, result rows rather than surviving cases, and no deduplication; deleted-case artifacts show as null-caseId; and the launches rollup has special flaky/skipped semantics inconsistent with get_launches_statistics. This is rich, non-obvious, and fully consistent with the annotations.

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 remarkably dense—every sentence adds a distinct caveat, envelope alternative, or semantic clarification that an agent needs before trusting the output. It fronts the core detail, then progressively deepens into data-quality warnings and finally routing guidance, with no filler to trim.

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 tool with no output schema, the description names the return payload, explains rollup semantics, warns about misleading counts, provides the exact lookup method to troubleshoot archived releases, and routes agents to list_releases for browsing. It is difficult to think of a required input-output or edge-case detail missing for successful invocation and interpretation.

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, and the description adds meaningful context on top: releaseId should be obtained from list_releases, includeLinkedExecutions/includeLaunches control only the payload arrays while the stats rollup still comes back either way. This is more than simple schema restatement, though less than exhaustive since nested response shape is covered only narratively.

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 target resource—'Get one release by releaseId with full detail'—and immediately enumerates the returned fields. It also distinguishes itself from list_releases by noting that list_releases browses, searches, and filters while get_release fetches a single already-identified release.

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?

It explicitly instructs when to use list_releases instead (browse, search, filter, obtain releaseId) and when to call get_release once the release is known. It also explains when to pass includeLinkedExecutions and includeLaunches false to keep the response small, and warns about archived releases versus list_releases requiring includeDeleted.

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