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

The description significantly expands on the annotations. While readOnlyHint=true and destructiveHint=false are useful, the description adds critical behavioral details: the asynchronous nature of jobs, that 'queued' for a few minutes is normal, that the tool returns a user-safe error reason on failure, and that the agent should keep polling. This is far beyond the annotations and helps the agent understand the tool's runtime behavior.

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 description is structured with a clear first sentence stating the core action, followed by failure handling, then queued-status behavior, and a final clause on when to escalate. Each sentence earns its place, and the length is justified by the need to prevent misinterpretation of the queued status. There is no fluff or redundancy.

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?

Even without an output schema, the description adequately covers the essential return information: statuses (succeeded, failed, queued), the presence of an error reason on failure, and the attempts count implied by '0 attempts'. It does not enumerate all possible statuses or include other fields, but for a polling tool, it provides sufficient context for an agent to act 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?

The schema already provides 100% coverage for the single parameter 'job_id', stating that it is the job id returned by generate_schedule_iii. The description does not add any additional semantic detail about the parameter itself. Therefore, the baseline of 3 is appropriate, as the schema does the heavy lifting and the description adds no extra 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?

The description clearly states the tool's function: 'Poll a background job by id until status is succeeded or failed.' It identifies the specific resource (background job) and action (poll by id), and it distinguishes this tool from siblings by focusing on generic background job status rather than specific entity statuses. The description also clarifies the end condition, which fully captures the tool's purpose.

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?

The description gives extensive usage context, including polling frequency (every ~30–60s), how to interpret the 'queued' status (normal initially), and how to communicate results to the user (show error reasons, reassure user). However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5 but provides clear enough context for when it should be used.

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