job_status

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

No annotations provided, so description carries full burden. It discloses that it returns status and timings, that it does not return heavy results, and that unknown IDs yield JOB_NOT_FOUND. It does not cover permissions or rate limits, but these are less critical for a read-only polling tool.

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?

Two concise sentences, front-loaded with the main purpose, then elaborating on status values and usage flow. No unnecessary words or repetition, every sentence adds value.

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 the tool has a single parameter, an output schema, and 17 siblings, the description adequately covers usage flow and error condition. It explains the polling pattern with job_result, which is critical. Minor omissions like timeouts or concurrency are acceptable for a status tool.

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?

Only one parameter 'job_id' with 0% schema coverage. The description adds context by stating that an unknown ID returns JOB_NOT_FOUND, which goes beyond the schema's type definition. However, no further details about format or validation are provided, so it meets the minimum requirement.

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 clearly states 'Report one background job's status and timings' with a specific verb and resource. It distinguishes from siblings like job_result by noting 'no heavy result' and mentioning JOB_NOT_FOUND for unknown IDs.

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?

Explicitly provides when to use: 'Poll this, then call job_result once the job is succeeded (or to read the failure of a failed / cancelled job).' Also notes that JOB_NOT_FOUND is returned for unknown IDs, guiding the agent on error handling.

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