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

Annotations already declare readOnly/idempotent/non-destructive, and the description is consistent with them by framing every result as 'a host report, not proof of execution or consent' — a meaningful trust-boundary caveat that annotations cannot express. It also discloses refusal behavior ('a refusal names the field to fix') and that artifacts stay local with hashes sent instead, adding genuine behavioral context beyond the 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?

Five tight sentences with the hard constraint ('Team jobs only') front-loaded and no filler. A few phrases are compressed to the point of opacity ('Each step checks its record'), which costs a little clarity but not length.

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?

Return values need not be explained since an output schema exists, and annotations cover the safety profile. Still, for a 7-parameter, nested-object tool with zero schema documentation, the description omits what the event values mean and what to do on a stale-digest failure, so an agent could not reliably call it without inspecting the enum.

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 semantics, and it does explain the critical ones: state must be 'the latest complete state,' state_digest must be sent 'unchanged' (implying an optimistic-concurrency token), one event plus its document, and hashes rather than artifact bodies. But it says nothing about job_id, the 'schema' parameter, accept_proposal, or the meaning/ordering of the twelve event enum values, leaving several parameters undocumented in either place.

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 title ('Check the next step of a team job') supplies the verb, but the description never states plainly what invoking the tool accomplishes beyond 'Each step checks its record' and returning 'a host report.' It describes the mechanics of the call (state, digest, event, document) rather than the outcome, leaving the agent to infer that this submits a step event to a team job state machine.

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?

'Team jobs only' is an explicit exclusion, which is real scoping guidance. However, no alternative is named for non-team jobs, and siblings such as advance_outcome or start_job are never contrasted, so the agent must guess which tool handles the other case.

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