release_tracking

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

Annotation Contradiction: the description discloses mutating effects — 'Writes CHANGELOG.md, creates GitHub Releases and Milestones' — while the annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Writing a file and creating GitHub resources are write operations that directly contradict read-only semantics; creating Releases/Milestones is also not reliably idempotent. This inconsistency could lead an agent to treat a mutating tool as side-effect-free.

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?

Four short sentences totalling roughly 40 words, with the core purpose front-loaded in sentence one. Each subsequent sentence adds a distinct type of information: capabilities, project-type support, and external effects. Minor filler: 'Supports greenfield and brownfield projects' doesn't affect invocation behavior, but the overall size is appropriate for a multi-operation 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?

For a tool with 21 parameters, 9 distinct operations, no output schema, and contradictory annotations, the description is too thin. It doesn't differentiate the nine operations, doesn't explain the gh CLI dependency beyond schema hints, and leaves the read-only contradiction unresolved. An agent cannot reliably choose an operation or predict state changes without opening the schema and inferring behavior.

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% — all 21 parameters carry individual descriptions and two have enums, so the schema does the heavy lifting. The description adds a small amount of context (CHANGELOG.md maps to writeToFile, GitHub Releases to createGithubRelease, local persistence fallback to localOnly) but doesn't systematically map operations to their parameters. The baseline 3 is appropriate when the schema fully documents params.

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+resource ('Track releases mapped to ADR decisions') and enumerates concrete capabilities: generates changelogs, manages milestones, compares releases, and assesses release readiness. It names tangible outputs (CHANGELOG.md, GitHub Releases, Milestones), making the tool's function clear. It doesn't explicitly differentiate from adjacent siblings like deployment_readiness or analyze_deployment_progress, but the ADR linkage and named outputs largely carry the purpose.

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?

No guidance on when to use this tool versus alternatives; it never names a sibling or an exclusion condition. With 61 siblings that include adjacent tools like deployment_readiness, analyze_deployment_progress, and smart_git_push, and a 9-operation surface, the absence of when-to-use/when-not-to-use direction is a real gap. The agent must infer usage entirely from the operation enum.

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