List employees

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

Annotations already cover the safe read-only behavior (readOnlyHint=true, destructiveHint=false), so the description does not need to restate that. It adds minor behavioral context by noting that employee roles are included and that other entities reference employees by id, but it does not describe pagination, soft-delete handling, or response shape.

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 short sentences with no filler; the core purpose is front-loaded and the second sentence adds relevant cross-reference context. Every word earns its place.

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 read-only list tool with no required parameters and a well-documented schema, the description is mostly sufficient: it names the returned resource and clarifies the employee-id relationship used by receipts/shifts. It could be slightly more complete by mentioning pagination or the employee_ids filter, but these are already covered in the schema and the operation is low-risk due to readOnlyHint.

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 high (86%), with all parameters except employee_ids having descriptions, so the schema carries most parameter semantics. The description adds no parameter-level details, and employee_ids remains undocumented, but the baseline of 3 applies because the schema provides sufficient guidance for most parameters.

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 action and resource: 'List employees and their roles'. This clearly differentiates it from the sibling get_employee tool (which would return a single employee) and from other list_* tools by naming the exact resource. The added note that receipts and shifts reference employees by id gives extra purpose context.

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 when to use the tool through 'Receipts and shifts reference employees by id' – i.e., for resolving employee references in other records – but it does not explicitly state when to prefer this over get_employee or other list tools. There are no exclusion criteria or alternative tool names mentioned.

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