Build / deploy status of a commit

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

While annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds valuable behavioral context beyond that: it explains the polling behavior of waitSeconds (waits until everything finishes instead of a pending snapshot) and discloses a host-specific quirk (Cloudflare Pages on this setup reports nothing, so checks alone stay empty). This goes beyond the annotation coverage and helps the agent understand edge cases.

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 compact (four sentences) and front-loaded with the core purpose, immediately followed by the critical usage sequence. Every sentence serves a function: purpose, usage order, waitSeconds behavior, and read-only nature. There is no filler or repetition beyond the redundant 'Read-only' which aligns with the annotation but is harmless.

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 read-only status tool with no output schema, the description is remarkably complete. It specifies what data it returns (GitHub Actions check runs, combined commit status, deployments with latest state), when to call it, how the polling works, and even a host-specific caveat (Cloudflare Pages not reporting). It covers all the operational context an agent needs to invoke it correctly and interpret results.

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 all six parameters are already documented in the input schema with detailed descriptions. The tool description adds minimal extra parameter meaning—only a brief note about waitSeconds polling behavior, which is partially redundant with the schema's 'Keep polling until every check and deployment settles.' The baseline of 3 is appropriate since the schema does the heavy lifting and the description doesn't compensate for any gaps.

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 clearly states the tool's purpose: to report whether a site actually built and went live after a commit, listing the specific sources (GitHub Actions, commit status, deployments). It also distinguishes itself from siblings by naming the exact calling sequence relative to github_commit_files and IndexNow/Google Search Console. This is a specific verb+resource with clear scope.

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 call: 'Call it after github_commit_files with the sha it returned, before submitting the URL to IndexNow or inspecting it in Search Console.' This provides a concrete ordering and references sibling tools, leaving no ambiguity about context. It also explains the waitSeconds parameter's purpose for polling until completion.

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