Contributions

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true. The description adds genuinely new behavioral context: that the call can consume paid API credits, that confirm=true is mandatory, and that this read-like POST does not publish to social platforms - directly explaining why a read-style operation is flagged non-read-only. It doesn't cover rate limits or failure modes, so not a full 5.

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?

Three tight sentences, front-loaded with the payload description followed by input rules and then the cost/confirm caveat. The final clause ("Read-like POST requests do not publish to social platforms") is slightly elliptical, but nothing is wasted.

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 credit-consuming fetch tool with no output schema, the description covers the returned data shape, the input forms, and the payment/confirmation requirement. What remains unstated - pagination, error behavior, credential resolution for account - is minor but not trivial.

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 every parameter is already documented in the schema. The description only restates that handle and url are alternatives and that year defaults to the current year, which the schema already says. Baseline 3 is appropriate given the schema does the heavy lifting.

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 gives a specific verb and resource ("Retrieves the public GitHub contribution graph for a user and year") and enumerates the payload (totals plus daily counts/intensity). It is clear enough to separate this from generic profile tools, but it never explicitly names competing siblings like github_activity or github_user, so an agent must infer the boundary.

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 gives input guidance (pass a handle or a full profile URL, year defaults to current) and a hard prerequisite (confirm=true, credits consumed), which is useful. However, there is no explicit when-to-use versus when-not, and no routing to an alternative for related GitHub data, so usage is only implied.

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