Check the badge on the site

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

The rate limit of 10 checks an hour per project is disclosed in the description and is not available from the annotations, which is exactly the kind of side-effect context that matters. This also implicitly explains why readOnlyHint=false and idempotentHint=false despite the read-like verb. It does not say what a check consumes or what happens when the quota is exhausted.

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 short sentences, no filler, with the core action first and the operational constraint second. Every clause carries information the agent needs to call it correctly.

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 single-parameter, low-complexity verification tool the description covers when to call, how often, and the quota. The one gap is outcome semantics: there is no output schema and the description does not say whether a missing badge produces an error, a status field, or a failed result. That is a modest but real omission for a network-side check.

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% and the single project_id includes a regex pattern, so the schema carries the parameter burden. The description only alludes to "per project", adding no format or scoping detail beyond what the schema already states. Baseline 3 applies.

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 uses a concrete verb and resource ("checks the client's site for the badge") and adds temporal scope ("now", i.e. a live check) that separates it conceptually from get_badge. It never names get_badge or any sibling explicitly, so an agent must still infer that this is the execution/verification counterpart to fetching badge markup.

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?

Strong context: "check once after the client says it is installed" tells the agent the triggering condition and warns against repeated calls. The rate limit (10/hour per project) reinforces the when-to-use guidance. It stops short of naming alternatives or stating what to do when the check fails, so it is clear context rather than full routing guidance.

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