list_jobs

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

The '[tier: readonly-owner]' tag signals read-only/ownership scope, providing some behavioral context. With no annotations provided, the description partially carries the transparency burden. However, it doesn't disclose pagination behavior, default sorting, result limits, or whether filters are combinable. The tier tag is useful but limited in detail.

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?

Two concise sentences with zero waste. Front-loaded with the primary action and all key filter dimensions, plus the endpoint and tier context. Every element contributes value.

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 listing tool with 11 parameters, 45% schema coverage, and no output schema, this is moderately complete. The description captures the filtering dimensions but lacks detail on pagination defaults, result shape, and any permission implications beyond the tier tag. Sibling tools like list_estimates and list_invoices follow similar patterns, so some inference is possible, but the 11-parameter surface area warrants more guidance.

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 coverage is only 45%, so the description must compensate. It names the filter dimensions (customer, employee, status, date range) which maps to ~5 of the 11 parameters (customer_id, employee_id, work_status, scheduled_* bounds). This helps decode several undocumented params. However, it doesn't clarify page/page_size/sort_by/sort_direction semantics beyond what schema type hints suggest, and the date range mapping is implicit.

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 states it lists jobs with optional filters (customer, employee, status, date range), clearly distinguishing it as a listing operation. It verb+resource is specific and the endpoint mapping adds clarity. Could benefit from explicitly distinguishing from get_job (single resource retrieval), but sibling differentiation is partially achieved by the plural listing nature.

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 implies it's for listing jobs and mentions the filter options, giving context on when to use it. However, it doesn't explicitly state when NOT to use it (e.g., when you need a single job use get_job, or when you need job line items use list_job_line_items). No exclusions or alternative tool mentions beyond the implicit endpoint mapping.

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