list_job_appointments

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

The description includes '[tier: readonly-owner]' which signals a read-only operation and ownership constraint. No annotations are provided, so the description carries the burden. It adds the readonly and owner-scope context, which is useful, though it doesn't detail behaviors like pagination, sorting, or what happens with no appointments. The tier marker adds some transparency value beyond 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?

The description is four sentences/short clauses and to the point, front-loading the core purpose and endpoint. The '[tier: readonly-owner]' tag is compact metadata. Minimal waste, though the 'filters' mention creates an expectation of parameter documentation that isn't fulfilled.

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 single-parameter list tool with no output schema and no annotations, the description is reasonably informative: it states scope (per-job or account-wide), the endpoint mapping, and access tier. However, it promises 'filters' without enumerating them, and with 0% schema coverage the job_id parameter and any filter parameters go undocumented. Given the tool's simplicity, this is adequate but leaves the filter behavior under-specified.

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%, and there's only one parameter (job_id: string). The description never mentions the job_id parameter explicitly — it's only implied by 'List appointments for a job.' With 0% coverage, the description should compensate, but it adds no parameter-specific detail about job_id format, whether it's required, or any filter parameters that the 'across the account with filters' clause implies would exist. This is a meaningful gap.

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 'List appointments for a job, or across the account with filters' — a clear verb+resource with scope indicated. It maps to GET /jobs/{job_id}/appointments, which confirms the endpoint. However, it doesn't explicitly distinguish from sibling get_appointment (singular vs plural could be inferred but not stated).

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 notes it lists for a specific job OR across the account with filters, so an agent knows it can be used in both scopes. However, it doesn't explicitly state when to prefer this over get_appointment (retrieving a single appointment by ID vs listing), and the 'or across the account with filters' is vague — no detail on what filters are available.

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