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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so restating 'Read-only' earns no credit. The added value is limited to the permission caveat that results depend on the API key's resource permissions, which is genuinely useful context but doesn't cover pagination behavior or result ordering.

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 with the resource scope front-loaded and no filler. The telegraphic style ('scheduled dates, customer and vehicle references') is slightly fragmentary but wastes nothing.

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?

With nine optional parameters, no output schema and low schema coverage, the description should explain at least the filtering and pagination model. It gives only a date format convention and an auth note, leaving an agent guessing about how status/name/appointmentId filters interact and what page/pageSize defaults do.

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 only 11% (just shopId), so the description must compensate for eight undocumented parameters. It only adds the date format rule for startDate/endDate; filtering semantics for status, firstName, lastName, appointmentId, page and pageSize are left entirely unexplained.

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 names the resource (appointments) and the fields surfaced (scheduled dates, customer and vehicle references), so an agent can infer it is a list/read operation on appointments. However, the verb is the soft 'Review' rather than an explicit list/query statement, and it never distinguishes this tool from the many sibling list_* tools beyond its name.

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?

There is no guidance on when to use this tool versus alternatives such as shopboss_list_customers or shopboss_list_repair_orders, nor any mention of which filters are worth combining. The only contextual sentence concerns API key permissions, which is authorization context rather than usage guidance.

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