query_failed_system_jobs

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces rather than contradicts that ('Does not retry, cancel or change jobs'). It adds real behavioral context beyond the annotations: sensitive payloads (job data, configuration, message text) are excluded by default and only surfaced on opt-in. It does not mention that bounded reads can return partial/incomplete results, which is only visible in the schema.

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?

Three short sentences, no filler, and the operative content (what is read, what is excluded, what it will not do) is front-loaded. Every clause carries distinct information.

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 15-parameter, all-optional read tool with 87% schema coverage and no output schema, the description covers purpose, default privacy posture, and non-mutating behavior adequately. Gaps remain around pagination/incompleteness semantics and what a returned row contains (no output schema to lean on), but nothing an agent needs to invoke it safely is missing.

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?

With 87% schema description coverage the schema does the heavy lifting, and the description only lightly maps its filters ('completion-time bounds and optional correlation/owning step IDs'), which does clarify that step_id is the owning step rather than the failing one. It says nothing about the extensive camelCase alias duplicates, the default 24-hour window, top vs. max_pages pagination interaction, or the include_text/max_text_chars coupling — all left entirely to the schema.

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 and resource ('Read native failed system jobs (statuscode 31)') and pins the precise domain definition of failure via the statuscode constant, which is genuinely useful. It is clear about scope (completion-time bounds, correlation/owning step IDs), but it never names a sibling it competes with (e.g. query_plugin_trace_logs, diagnose_plugin_failure), so it stops short of full sibling differentiation.

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 phrase 'using completion-time bounds' implies when the tool fits (post-hoc failure triage over a time window), and 'Does not retry, cancel or change jobs' rules out remediation use. However, there is no explicit 'use this instead of X when Y' routing among the many diagnostic siblings, nor any statement of prerequisites such as which time window to pick or what to do when the read is incomplete.

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