list_jobs

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

With no annotations, the description carries the full burden, and it offers only two behavioral hints: the operation is a read ('List') and results are paginated. It does not explain what qualifies a job as 'persistent', whether results are ordered, or how filters behave. The unexplained 'persistent' qualifier raises more questions than the description answers.

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?

One sentence of five words with no filler: the verb, resource, and pagination mechanism are all present. It borders on under-specification by omitting filter semantics, but as written it is genuinely tight and front-loaded.

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?

The output schema covers return shape, but the description leaves three gaps for a tool with no annotations: 'persistent' is undefined, status/project filters have no semantics (0% schema coverage), and there is no routing guidance among 12 siblings. An agent can invoke it safely with defaults but cannot use it correctly for filtered lookups.

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 0%, so the description was expected to compensate, but it covers only pagination (which gives limit/offset meaning) and says nothing about status or project. Valid status values, whether filters are exact-match, and how filters combine with pagination are all unexplained. With 0% coverage, the description needed to address every parameter and did not.

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 uses a specific verb-resource pair ('List persistent jobs') and names the pagination mode, which distinguishes the tool from single-item siblings like get_job and non-job resources like list_artifacts. However, it does not explicitly differentiate from the overlapping-sounding list_ready_results or get_project_runs, and the qualifier 'persistent' is left undefined.

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?

No when-to-use guidance or alternative routing is given. The description names none of the 12 siblings and states no conditions, prerequisites, or exclusions, so the only usage signal is the implied action of listing. An agent cannot tell from the description whether list_jobs or list_ready_results is the right entry point for a given request.

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