get_job_status

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

The description emphasizes the difference between 'status' and 'result' but never explains it, leaving the behavioral contract (blocking? error semantics? readiness) undefined. With no annotations to fill in the gaps, the description carries the full burden and falls short of clarity.

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 a tight two sentences; it front-loads the action and resource, then tucks parameter documentation away in a nested Args block that preserves skimmability. Nothing is wasted, and nothing essential is missing.

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 simple get-by-identifier operation, the description is adequate but thin—it doesn't mention error conditions or the shape of the result, although the output schema may cover the latter. The description gives no warning about potential unavailability of a 'result' while processing is still ongoing, a likely pitfall.

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 description identifies the job_id as 'returned when the job was submitted,' resolving ambiguity about its origin. The schema merely labels it 'Job Id,' so this detail adds genuine signal and is valuable to a model.

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 verb 'Get' and resource 'status and result of a specific job' are clear and unambiguous, and the word 'specific' helps set it apart from list-style siblings like list_jobs. It's a recognizable get-by-identifier pattern that is easy to act on without confusion.

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 offers no guidance on when to prefer this tool over alternatives such as list_jobs or cancel_job, nor does it explain the polling or persistence semantics. A developer is left to infer that this is a getter associated with submissions from sibling tools like submit_generate, a connection the text never draws.

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