list_employees

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

No annotations are provided, so the description carries the full behavioral burden. The 'Maps to GET /employees' and '[tier: readonly-owner]' hint at a read-only operation, which is useful safety context. However, it doesn't disclose pagination behavior, default sort order, or what happens with large result sets, which would be valuable for a list endpoint.

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 a single concise sentence (plus API mapping and tier tag). Every element earns its place. It's appropriately front-loaded with the core purpose first. The tier tag and endpoint mapping add useful context without bloat.

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 list tool with 8 parameters, low schema coverage, no output schema, most describing a simple list operation, the description is adequate but thin. It doesn't explain the employee roles fully, pagination semantics, filtering behavior, or the q/role/tags/is_active parameter semantics. It's a minimum-viable description but leaves the agent to guess about key behaviors.

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 13% (1 of 8 params described in schema). The description mentions 'optional filters' generically and identifies the domain roles (field techs, office admins), but doesn't explain the 8 parameters or how they interact. It adds minimal value beyond the schema's near-empty parameter descriptions, and doesn't compensate for the low coverage.

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 employees (field techs and office admins), with optional filters' - a specific verb (list) + resource (employees) with field/domain context. It distinguishes nicely from siblings like get_employee (single record vs list). The 'Maps to GET /employees' adds API grounding. It could explicitly differentiate from similar list_* siblings, but the resource name is clear.

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 this is a list/collection tool via 'optional filters' and the GET mapping, which gives some context. However, it doesn't explicitly state when to use this vs alternatives like list_employees vs get_employee (single lookup), or when pagination is needed. There are no explicit exclusions or when-not-to-use guidance.

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