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

With no annotations, the description carries the full burden and largely meets it: it discloses the status lifecycle, that intermediate responses are streamed, that pending changes carry chunk IDs and HTML diffs in metadata.pending_changes, and that headless/MCP clients receive typed progress events (documents_changed, continue_prompt, model_fallback, proposed_change_batch). It stops short of stating auth/permission requirements or rate-limiting expectations for polling, which is the main remaining gap.

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 response payload is front-loaded in the first sentence, followed by usage guidance and then the approval/streaming details. It is dense and runs long, but nearly every clause carries non-obvious behavioral information rather than restating structured fields.

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?

Given an output schema exists, the description need not explain return values, yet it usefully ties the status values to the approval workflow and streaming events an agent must act on. Combined with the polling guidance and the cross-session alternative, an agent has everything needed to call and follow up on this tool correctly.

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 only 33% — only 'compact' is documented, while job_id and authorization are undocumented in both schema and description. The description implies job_id via 'the job's current state' but adds no meaning for the authorization parameter, so it does not compensate for the low coverage; job_id is self-evident from the tool name, keeping this at a baseline 3.

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 states a specific verb and resource (returns the job's current state) and enumerates the exact status values (pending, in_progress, awaiting_approval, completed, failed, cancelled), plus the full payload. It clearly distinguishes get_job from siblings like list_jobs, get_session_jobs, and cancel_job by describing per-job result retrieval rather than listing or mutating.

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 gives explicit routing: 'Poll this after chat_async to track progress and retrieve results,' and names the follow-up action when status is awaiting_approval (POST /v1/chat/{session_id}/approve). It also points to an alternative for a related need (GET /v1/sessions/{session_id}/doc-events for cross-session updates), so when-to-use and when-to-use-something-else are both covered.

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