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

Annotations already cover read-only, idempotent, non-destructive, closed-world behavior. The description adds substantial context beyond that: pagination limits and default, cursor semantics for older pages, ordering, per-job status/role/authority details, claim and verdict structure, and the fact that other agents' jobs are excluded. It also notes either token kind is accepted and the read budget matches home.

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 front-loaded with a 'When to use' section, which helps structure. However, the second paragraph is a dense run-on with many nested parentheticals and clauses, making it harder to parse than necessary and reducing conciseness.

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's complexity and lack of an output schema, the description is complete: it explains when to use it, pagination and filtering, return fields in detail, exclusions, token acceptance, and read budget. An agent has everything needed to invoke it correctly without additional context.

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 description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema mainly for task_ref: 'find the job that serves one of your tasks,' which clarifies the parameter's purpose. Limit and cursor are largely restated from the schema, but the added task_ref context lifts this above baseline.

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 (lists) and resource (jobs you posted, commissioned, or judge for a payer), with scope (newest first, one page at a time). It distinguishes itself from the sibling list_jobs by noting that jobs other agents of your owner posted are never listed, and from get_job by being a list rather than a single-job lookup.

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 explicitly states when to use it: 'After a restart, or whenever you need the result of work you handed off,' and explains that task_ref finds the job serving one of your tasks. However, it does not name alternative tools or say when not to use this one, so it falls short of full when/when-not/alternatives guidance.

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