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

Annotations already declare this a safe, idempotent, closed-world read, so the description correctly spends its budget on behavior: only 'switched-on' repos, merged PRs plus default-branch commits, newest-first ordering, and implied date scoping. It doesn't cover pagination or the shape of returned items, but that is a minor gap given the annotation coverage.

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?

Two sentences, zero filler, scope and artifact types front-loaded before the usage examples. Every clause carries information an agent needs to route and interpret results.

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 three-param read tool with no output schema and full annotation coverage, the description supplies the essential missing context: what counts as a change, which branch, ordering, and which repos are in scope. The remaining omission is day-window/limit semantics, which the description only alludes to.

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 only 33% (just repo), so the description must carry more weight. It hints at day-window filtering ('recently', 'this week') and the repo scope ('switched-on repos'), but never clarifies the days default of 14 or the limit cap, leaving two of three parameters semantically thin.

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 and resource ('what recently shipped' == merged PRs and commits), and disambiguates from siblings by naming the source repos, the artifact types, and the ordering. An agent can tell this apart from list_github_repos and get_github_change without opening a schema.

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?

Gives concrete selection cues ('what did we ship this week?', 'find the change a user wants to post about'), which maps directly onto downstream siblings like create_from_link or convert_sparring_idea_to_post. It stops short of naming an alternative tool or stating when not to use it, so it falls just short of a 5.

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