Employee report

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds important behavior beyond that: inactive employees are excluded unless includeInactive is true, missingFields reports fields BambooHR did not return, and filtering/aggregation is client-side only. No contradiction with annotations.

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?

Four sentences, each carrying distinct operational information: the core call, guaranteed fields, inactive-employee handling, and missingFields/filtering caveats. The main action is front-loaded and there is no filler.

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 no output schema, the description conveys what the response will contain (requested fields plus always-included fields), how missing fields are surfaced, how inactive employees are handled, and that no server-side filtering exists. This is sufficient for an agent to invoke and interpret the tool correctly; 'in one call' also implies a single bulk response.

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 100%, so the baseline is 3. The description adds real value by explaining that id/displayName/status are always included, clarifying that missingFields may indicate API key visibility issues or wrong field names, and linking fields to bamboohr_list_fields.

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 operation—'Pull chosen fields for every employee in one call'—against a clear resource, with examples. It also emphasizes always-included id, displayName, and status, which differentiates it from single-employee or field-list sibling tools.

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 gives clear context: use when you need the same chosen fields for all employees, and it directs agents to bamboohr_list_fields for checking field names. It does not explicitly say when not to use it relative to siblings like bamboohr_list_employees, so it stops short of a 5.

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