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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: the exact contents of the response (status, contacted/replied counts, ranked quotes) and the fact that calls are free, which matters for agent retry/polling decisions. It stops short of saying whether status is live or cached, whether ranked quotes can be paginated, or whether an in-progress job may return an empty quote list.

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 short sentences, front-loaded with the usage trigger, followed by return contents and a cost note. Every sentence carries information an agent would otherwise have to infer, and there is no redundant restatement of the title or annotations.

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, read-only polling tool this is close to complete: annotations cover safety, and with no output schema the description correctly takes on the job of enumerating return fields. The remaining gap is operational — nothing about polling cadence, result limits on 'ranked quotes so far', or behavior on an unknown token — which an agent calling this repeatedly would want to know.

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 0%, so the schema documents only that job_token is a required string; the description must carry the meaning. It does the most important part by tracing the parameter's provenance to request_quotes, telling the agent where a valid token comes from. It does not describe the token's format or what happens with an invalid or expired token, so it adds real but incomplete semantic value.

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 specific action (retrieve status of a quote job) and enumerates the concrete payload: status, contractors contacted, contractors replied, and ranked quotes. It also anchors the resource to a sibling (a job_token from request_quotes), so an agent can tell it apart from request_quotes, check_fair_price, and list_job_types 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?

Gives an explicit trigger condition: use when the user asks how their contractor quote request is going. That is a clear when-to-use signal, but it does not state when NOT to use it (e.g., before request_quotes has been called, or as an alternative to check_fair_price for price questions). The implicit prerequisite — that a job_token must already exist — is only hinted at via 'from request_quotes'.

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