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

Beyond the annotations, the description discloses the async-return model, the four termination conditions (readiness, deadline, attempts, cap), that remote tools are never invoked, and the credit accounting rules including broken targets and free-but-counted unavailable workers. Consent and no-cash-charge notes add real pre-call context. The 15s poll interval is stated but not reconciled with the schema's configurable interval_sec, a minor tension.

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?

Front-loaded with the action and return contract, then grouped into semantics, polling, economics, and safety constraints. The telegraphic fragment style ("No cash charge.") is dense but each line carries operational weight; a couple of the cost sentences could be merged without loss.

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 10-parameter, credit-charging async job starter, the description covers cost model, consent, idempotency, termination, and polling, and an output schema already documents the job-ID response. Remaining gaps are the unexplained url/api_key parameters and the exact shape expected in expect.

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?

With 0% schema description coverage the description must carry the load, and it does explain kind (HTTP/MCP/assert), expect (assert_healthy conditions), confirm, request_key reuse, max_coins as credits, and implicitly interval/deadline/attempts via the polling and stop conditions. url and api_key receive no explanation, and the mapping of "attempts" and "cap" to max_checks and timeout_sec must be inferred.

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?

"Start a private bounded readiness job; returns immediately with a job ID" gives a specific verb, resource, and async contract that separates it from blocking siblings like assert_healthy and diagnose_http. It also names read_readiness_jobs as the polling counterpart, though it never states when to choose wait_until_ready over assert_healthy or diagnose_mcp directly.

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 operational guidance: the kind-specific success criteria (HTTP 2xx, MCP initialize + tools/list, assert accepting assert_healthy conditions) tell the agent which mode to pick, and "Poll read_readiness_jobs every 15s" plus "Nothing starts without confirm=true" define the calling sequence. It lacks an explicit exclusion such as "use assert_healthy for a single immediate check" to complete the routing picture.

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