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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds value by disclosing that job records are kept for the life of the project, that results are newest-first, and that pagination semantics indicate the last page. It does not explicitly state rate limits or auth requirements, but the safety profile is already covered by annotations.

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 single focused paragraph that front-loads the main behavior (list, newest first) and then adds enumeration of contents and pagination instructions. The phrase 'the first job of the job_type you want is the latest' is slightly awkward but informative. Every sentence contributes to usage clarity.

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 read-only listing tool with full schema coverage and annotations declaring safety, the description covers the key use case (finding past operations without job_id) and pagination behavior. No output schema exists, so return format is not explicitly described, but the list of fields (status, error, failure_side, start/end times) gives agents a good expectation of output content.

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 schema fully documents all three parameters (project_id, limit, offset). The description adds context that offset skips jobs 'newest first' and clarifies pagination, but does not add format or type information beyond the schema. Baseline 3 is appropriate.

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?

Description uses a specific verb and resource ('List a project's jobs'), enumerates the operation types included (create, deploy, promotion, rollback, resource change, module operation), and clarifies it's newest-first. It differentiates from siblings like get_job_status (which retrieves a single job by job_id) by explicitly addressing the case where job_id is unavailable.

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 states when to use this tool: to find what an operation did when job_id is no longer available, e.g., after an interruption or in a later session. It explains pagination behavior ('Read older jobs a page at a time with offset; a page shorter than limit is the last'). It does not name alternative tools, but the use case of locating past jobs without job_id is clear.

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