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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: server-side host resolution from the project rather than caller input, the 2KB response truncation, redirect following, and a semantic enumeration of outcomes including the non-obvious 'auth_gate' case (private-commit 302/303 gate vs. Google sign-in). That is exactly the behavior an agent could not infer from structured fields.

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 purpose and host-selection rules are correctly front-loaded, but a large share of the single dense paragraph enumerates return fields (host, host_kind, final_url, status, latency_ms, body prefix, redirect, outcome) that an output schema already declares. That duplication lengthens the read without adding selection value, and the wall-of-text format makes the outcome semantics harder to scan than a short list would.

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 4-parameter read-only probe with an output schema, everything an agent needs is present: when to use it, how hosts are chosen, path constraints, alias precedence, and how to interpret each outcome class. Nothing material is left to inference.

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 already 100%, so the baseline is 3; the description goes beyond it by documenting alias behavior and precedence ('job_id wins if both are given'), by naming the source of each id (list_projects, list_deployments), and by stating the host is never taken from caller input. It does not add much for `path` beyond the schema, keeping it short of a 5.

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 concrete verb and resource ('Server-side HTTP GET against a project's OWN app as deployed on kad.dev hosting') and frames it as a smoke test the client cannot run itself. It is clearly differentiated from build/status siblings by the line 'A green build alone does not prove the app responds; this does.' An agent can pick between this, get_app_status, and get_build_status without opening any 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?

Explicit branching rules: no job_id → canonical production host; with job_id (sourced from list_deployments) → that commit's own host. It also names where the canonical host comes from (canonical_host in list_projects) and explains the precondition (client egress does not reach app hosts), so the agent knows exactly when this tool is the right call and when a direct fetch is not possible.

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