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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context beyond annotations: it defines inserted/updated/deleted semantics, notes edits to job, compensation, or employment status tables, and states the newest-first ordering. 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?

Three sentences each earn their place: the first defines the tool's scope, the second states sort order, and the third references the sibling tool for follow-up detail. The most important information is front-loaded, with no fluff or repetition.

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 two parameters, full schema documentation, and safety annotations, the description is complete. It explains what changed means, how results are sorted, and how to get current employee details. No output schema exists, but the description gives enough structural context to understand the tool's purpose and follow-up path.

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 schema already documents both parameters, providing a baseline of 3. The description adds semantic value by mapping enum labels to real-world meanings: new hires = Inserted, edits = Updated, removals = Deleted. This helps the agent choose the type parameter more accurately than the schema alone.

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 starts with a specific verb and resource: 'List employees whose record changed since a timestamp.' It enumerates the three change categories (Inserted, Updated, Deleted), which fully clarifies what 'changed' means. It also differentiates itself from bamboohr_get_employee by pointing there for current values.

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 for when to use the tool: when a changed-record list is needed after a timestamp. It routes the agent to bamboohr_get_employee for current values, providing a concrete alternative. It does not explicitly state exclusions versus other list-style siblings, but the scope is clear enough.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds two behavioral details beyond the schema: the default range (current calendar year) and the inclusion of multi-day holidays that overlap. These are useful, non-obvious traits that help an agent reason about the result set.

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 sentences, no redundancy, and the primary action is stated first. The default and edge-case behavior are added efficiently without padding. Every clause 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 full schema coverage, the description covers the core behavior and defaults. It does not mention the response format, but the verb 'List' implies a list, and with no output schema, this is a minor gap. An agent can call it correctly without further info.

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 100%, so both start and end parameters are already documented with formats and defaults. The description reiterates the default but adds no new parameter-specific semantics. The multi-day overlap rule is behavioral, not parameter-focused. Thus a baseline 3 is appropriate.

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 verb ('List'), a clear resource ('company holidays'), and a precise condition ('overlap a date range'). It also defines defaults, making it unambiguous. With no sibling tool for holidays, it stands alone without confusion.

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 provides clear context on what the tool does and its default behavior, which implies when to use it (when company holiday data is needed). It doesn't explicitly contrast with alternatives like 'whos_out', but the scope is clear enough that an agent can infer its purpose.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable non-obvious details beyond those annotations: national ID numbers are masked, and Benefits Administration permission is required. This helps agents anticipate auth failures and data formatting.

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 dense sentences deliver purpose, scope, a data-format caveat, and a permission prerequisite with no filler. All content earns its place and the primary purpose is front-loaded.

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 simple, optional-parameter list tool, the description plus schema covers what the tool does, how to scope it, what authorization is needed, and an important return-value behavior. Nothing essential to calling it correctly is missing.

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?

The sole parameter employeeId is already fully described in the schema as 'Internal employee id. Omit for all employees.' The description adds the nuance that omission returns everyone the key may see, but this is a modest extension of the schema's existing meaning. Baseline 3 is appropriate given 100% schema 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 clearly states the verb 'List', the resource 'dependents', and the scope: either one employee or all employees the key can see. The subject is distinct from sibling tools like get_employee or list_employees, so an agent can easily differentiate it.

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?

It gives clear context for when to use the tool and how to scope it: pass employeeId for one employee or omit it for all visible dependents. It does not explicitly name alternative tools or state when not to use it, but the intended use case is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavioral context by stating 'Metadata only; files are not downloaded.' This clarifies that the tool will not return binary file content, which is useful beyond the structured 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?

The description is two sentences with no wasted words. It front-loads the primary action and resource, then supplements with output details and a key limitation. Every sentence adds value.

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 simple one-parameter read-only tool with no output schema, the description covers the resource, output fields, and behavioral limit (no downloads). It is complete enough for an agent to call correctly, though it could optionally mention pagination or error behavior.

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 100%, so the employeeId parameter is already well documented as 'Internal employee id.' The description adds only implicit context by referring to 'an employee's record', which does not materially improve parameter understanding beyond the schema.

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 opens with the specific verb 'List' and names the exact resource ('document categories and files stored on an employee's record'), including examples of document types and the returned metadata fields. This clearly differentiates it from sibling tools like bamboohr_get_employee or bamboohr_table_rows.

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 purpose statement makes it easy to infer when to use this tool, but it never explicitly says when to choose it over alternatives or mentions conditions like 'use this when you need file metadata but not downloads'. It is adequate but relies entirely on inference.

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

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.

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: how omitted employeeId is interpreted, what happens when fields is omitted, and that missingFields reflects fields that may be empty or hidden from the API key. This discloses a real visibility limitation.

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 sentences with no filler. The first sentence states the core purpose, the second covers the two optional-behavior decisions, and the third explains the missingFields semantics. The most decision-relevant information is front-loaded.

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 simple read operation with two optional parameters and strong safety annotations, this is complete. It covers the purpose, default behavior, self-record behavior, and what missingFields means. Without an output schema, the explicit mention of missingFields is especially useful and nothing needed to invoke the tool correctly is missing.

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 parameter mechanics are already well documented. The description still adds meaning by listing example standard fields, mentioning custom fields, and explaining what the default field set is. The missingFields note also clarifies what the fields parameter's result will contain.

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 opens with 'Read one employee's field values', naming a specific verb, resource, and field scope. It clearly distinguishes itself from list-style siblings by emphasizing 'one employee' and even explains how to read the API key owner's own record.

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 usage context: omit employeeId to read your own record and omit fields for a sensible default set. It does not explicitly name bamboohr_list_employees as the alternative for listing employees or retrieving IDs, but the singular/plural contrast and the concrete omit-behavior guidance make the intended use clear.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, so the bar is lower. The description adds meaningful behavioral context by specifying the exact field set returned and signaling that the output is a directory listing of current employees. It does not mention pagination or sorting, but for a zero-parameter list tool these are minor gaps.

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 focused sentences, with the core action and scope front-loaded and the downstream usage hint placed second. Every sentence earns its place with no redundant phrasing.

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 simple, zero-parameter listing tool, the description is complete: it states what is listed, which fields are returned, and how the returned IDs should be used. The annotations cover safety and idempotency, so nothing essential for correct invocation is missing.

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?

The tool has zero parameters, so the description does not need to explain parameter behavior; the baseline of 4 applies. The field list in the description compensates for the absence of an output schema by indicating what the returned data will contain.

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 verb ('List'), a precise resource ('current employees from the BambooHR directory'), and enumerates the returned fields (id, name, job title, department, division, location, supervisor, work email). It clearly differentiates from sibling tools like get_employee and list_users by focusing on the employee directory listing.

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: this is for obtaining current employees and their IDs for downstream use with 'balance and request tools.' It does not explicitly state when to avoid this tool in favor of a sibling such as get_employee, but the 'current employees' scope and the downstream ID guidance provide usable direction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral detail: it returns all fields, includes custom fields, and optionally includes options for list fields. This goes beyond the structured annotations and clarifies what the agent can expect.

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 concise sentences, each serving a purpose: stating the output, guiding search, explaining includeOptions, and directing downstream use. It is front-loaded with the primary purpose and contains no filler or redundant information.

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 simple read-only list tool with two optional parameters, the description covers the purpose, output attributes, parameter usage, and how to use the results. It lacks explicit mention of pagination or response format, but given the tool's simplicity and the annotations covering safety, this is adequate.

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% with both parameters described ('Case-insensitive substring' and 'Attach the option list... Default false'). The description adds examples ('shoe', 'hire') and rephrases includeOptions as 'allowed values', which slightly enriches understanding but does not add critical new semantics. Baseline of 3 is appropriate.

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 clearly states the tool lists every employee field (standard and custom) with specific attributes (id, name, API alias, type). It distinguishes itself from sibling list tools (e.g., bamboohr_list_employees) by focusing on fields, not people or time-off types. The purpose is explicit and actionable.

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 provides concrete usage instructions: 'Use search to find a field by name' and 'Set includeOptions to see the allowed values of list fields.' It also explains downstream usage by passing the alias/id to other tools. While it doesn't explicitly contrast with alternatives, the intended workflow is clear and contextually sufficient.

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

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

With annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the safety profile is fully covered. The description adds useful behavioral context beyond that: it explains the output shape (alias and columns) and the relationship to bamboohr_table_rows, which helps the agent know how the result is meant to be consumed.

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 sentences with no filler. The first sentence names the resource and examples, and the second sentence gives the crucial usage linkage to a sibling tool. It is front-loaded with the action and scope, and 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 no-parameter discovery tool with rich annotations and no output schema, the description is complete: it explains what the tool returns, gives concrete category examples, and tells the agent exactly how to use the returned alias. Nothing needed for correct invocation is missing.

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?

This tool takes zero parameters and the schema coverage is 100%, so there are no parameter semantics left unexplained. The description appropriately focuses on behavior rather than wasted parameter detail, earning the baseline for a zero-parameter tool.

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 verb ('List'), a clear resource ('every tabular field in BambooHR'), and what is returned ('table alias and its columns'). The examples of job history, compensation, employment status, and custom tables make the scope concrete and distinguish it from listing employees or other entity types.

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 explicitly instructs the agent to 'Use the alias with bamboohr_table_rows,' providing a direct next step after calling this tool. It does not explicitly list when not to use it, but the purpose is clear enough that no alternatives are genuinely competing for this metadata-discovery role.

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

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

Annotations already indicate read-only, non-destructive, idempotent behavior. The description adds value by stating what the response contains (ids, units, and default hours per weekday), which is useful behavioral information beyond the annotations. No contradiction found.

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 concise sentences: the first states the action and output contents, the second states the practical use case. No filler or redundant phrasing.

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 zero-parameter, read-only list tool, the description is complete. It names the resource, the output fields, and the follow-up purpose (finding type name/id for other tools), leaving no critical gap for an agent to invoke it correctly.

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?

The tool has zero parameters and an empty input schema, so the baseline is 4. There are no parameter details needed, and the description appropriately focuses on output semantics rather than inventing parameter guidance.

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 clearly states a specific verb ('List') and resource ('company's time-off types'), and adds concrete detail about the returned fields ('ids and units, plus the default hours per weekday'). This distinguishes it from sibling list tools like 'bamboohr_list_employees' or 'bamboohr_list_fields'.

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 second sentence provides clear usage context: 'Use this to find the right type name or id for other tools.' It does not mention exclusions or alternative tools, but for a lookup/reference tool the use case is well-defined.

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

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

Annotations already signal read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context by specifying the returned fields (linked employee id, email, status, last login) and the access-review purposeais without contradicting 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?

The description is two sentences with no filler. It front-loads the core behavior and result fields, then adds a concrete use case. Every sentence 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 simple list tool with one optional parameter and strong annotations, the description covers what the tool returns, who it applies to, and why it is useful. No critical information for invoking it correctly is missing.

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% and the only parameter, status, is fully documented with an enum and default of 'all'. The description mentions 'status' but does not add meaning beyond what the schema already provides, so the baseline score applies.

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 a specific verb ('List') and resource ('BambooHR user accounts') and clarifies that these are 'people who can log in', distinguishing them from employee records. This clearly differentiates from siblings like bamboohr_list_employees.

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 a clear use case: 'access reviews: who has an enabled account, who never logged in.' It does not explicitly state when not to use this tool or name alternatives, but the definition of user accounts versus employees makes the appropriate context clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds a meaningful behavioral caveat: 'Rows are unsorted; sort by date yourself.' It also clarifies the scope ('for everyone') without contradicting the 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?

Three short sentences with no filler. The main action and scope are first, examples follow, and the important unsorted-data caveat is saved for the end. Every sentence 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 two-parameter read tool with annotations covering safety, the description covers purpose, valid inputs, and the unsorted output behavior. It does not describe the return format, but there is no output schema to reconcile, and the essential call details are all present.

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 100%, so the schema already documents both parameters. The description mostly repeats the example alias values found in the schema, adding only the hint to fetch aliases from bamboohr_list_tables. Since the schema carries the semantic load, baseline 3 is appropriate.

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 verb ('Read') and resource ('rows of an employee table'), then scopes it to one employee or everyone with concrete examples (jobInfo, compensation, employmentStatus, custom tables). It clearly distinguishes itself from bamboohr_list_tables by instructing the agent to get valid aliases from that sibling, so the tool's purpose is unambiguous.

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 provides clear context for when to use the tool: whenever table rows are needed, and it points to bamboohr_list_tables for valid aliases. It does not explicitly contrast with alternative employee-data tools like bamboohr_get_employee, but the examples make the intended use evident, so the guidance is strong but not exhaustive.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds behavioral context beyond that: the temporal dimension ('as of a date') and the future-projection behavior, plus the response scope (every assigned type, year-to-date used). It doesn't mention auth or rate limits, but for a read-only tool with full annotation coverage this is acceptable.

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 sentences, zero filler. The core purpose is front-loaded, followed by a single, high-value usage note. Every word contributes.

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 tool with 2 params and no output schema, the description sufficiently conveys the purpose, the parameter behavior, and the expected data (balances per type, ytd used). It could list return fields in more detail, but the simplicity and annotations make this an adequate level of completeness.

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?

Input schema coverage is 100%, so the baseline is 3. The description adds meaning above the schema by explaining that the asOf date can be a future date to project the balance, and clarifies the balance includes year-to-date usage, which goes beyond simple schema field descriptions.

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 the specific verb 'Get' and the resource: 'one employee's time-off balances for every assigned type as of a date, including amount used year-to-date.' The explicit single-employee scope differentiates it from sibling tools like 'time off requests' or company-wide overviews.

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 usage (when you need a single employee's balance history) and provides a useful tip for the asOf parameter ('Use a future date to project the balance'), but it does not explicitly state when to prefer this tool over siblings such as 'bamboohr_vacation_overview', and no exclusions are given.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: the 'overlapping' semantics for date range and the visibility limitation to employees the API key owner may see. This enriches the agent's understanding without contradicting 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?

The description is two sentences with no redundant words. It front-loads the core purpose and then adds the critical scope restriction. Every sentence earns its place, and the structure is efficient.

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?

Given the tool's moderate complexity (5 params, all documented in schema) and rich annotations, the description covers the essential behavioral aspects: the overlap semantics and the visibility constraint. It doesn't mention pagination or response format, but with no output schema, the phrase 'List time-off requests' suffices. It is complete enough for correct invocation.

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 100%, so baseline is 3. The description adds meaningful nuance by clarifying that the date range selects requests overlapping the range (not just contained), and explicitly mentions the optional filters (employee, status, time-off type) which map directly to parameters. This goes beyond simple schema repetition.

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 clearly states the verb (List) and resource (time-off requests), and specifies the key filters (date range, employee, status, time-off type) and the scope limitation to visible employees. It is unambiguous and distinguishes this tool from sibling listing tools by its focus on requests with these specific filters.

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 provides clear context: it lists time-off requests with optional filters and notes the visibility restriction. It doesn't explicitly name alternatives or conditions for when not to use it, but the tool's purpose is self-evident and no competing sibling tool has the same filter set, so an agent can infer usage.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior; the description adds concrete facts about scope ('per employee', 'completed') and return content (dates, instructor, hours, credits, cost, notes). It does not discuss edge cases like missing employee IDs or pagination, but the disclosed context exceeds the annotated baseline.

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 sentences, front-loaded with action and resource, no redundant filler. Each clause 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 simple 2-parameter read tool with no output schema, the description covers the core return fields, the per-employee scope, and a representative use case. The schema and annotations fill in safety and parameter details, so nothing essential is missing.

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%: employeeId and trainingTypeId are described in the schema, including the link to bamboohr_training_types. The description only restates that trainingTypeId is optional, adding no new semantics. Baseline 3 applies.

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 opens with a specific verb ('List') and a bounded resource ('one employee's completed trainings'), and enumerates the returned fields. This distinguishes it from sibling tools like bamboohr_training_types, which lists type definitions rather than per-employee records.

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?

It gives a clear operational context: 'Optionally limit to one training type' and 'To check who is missing a required training, call this per employee.' It does not explicitly name alternatives or exclusions, 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.

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

Annotations already establish this as a safe, read-only, idempotent operation. The description adds the output fields and the relationship to training records, but does not describe response structure or other behavioral details. This is adequate but not extensive beyond the 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?

Two concise sentences, front-loaded with the core purpose and followed by a useful usage pointer. No wasted words.

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?

Given the zero-parameter schema and read-only annotations, the description is nearly complete. It lists the returned fields and connects to the related sibling, but the exact response shape (e.g., array vs. object) is not stated. Still, this is a minor gap for such a simple list operation.

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?

The tool has zero parameters, so the baseline is 4. The description adds value by enumerating the returned fields and clarifying that training categories are part of the result, which helps the agent understand the output even though no inputs are needed.

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 clearly says this tool lists the company's training types with specific fields and training categories. It is unambiguous and distinguishable from the sibling bamboohr_training_records, with which it directly connects via the type id.

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 clearly implies this is the lookup tool for training type definitions and tells the agent to use the returned type id with bamboohr_training_records. It does not explicitly exclude other alternatives, but the context and sibling list make the intended usage clear.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations by disclosing important behaviors: adjacent requests are merged, the summary counts before the onlyMissingFourteenDayBlock filter, and planned vacation excludes a request already in progress because BambooHR's balance may have already deducted it. This is exactly the kind of non-obvious behavior an agent needs.

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 dense but every sentence carries information: the report scope, the detailed output fields, the block-merging rule, the filter behavior, and the critical caveat about in-progress requests. It is front-loaded with the most important scoping statement.

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 compensates by enumerating all returned columns and their meanings. It could additionally clarify what 'current employee' means or whether results are paginated, but for the tool's complexity the essential calling context is present.

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 the interaction of onlyMissingFourteenDayBlock with the summary count, the as-of date semantics, and default timeOffType resolution, which are not evident from the schema alone.

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 purpose: a company-wide vacation report for one calendar year, and enumerates the exact computed columns (balance, used YTD, planned, unplanned, longest block, 14-day block flag). This clearly distinguishes it from individual-level sibling tools like bamboohr_time_off_balances or bamboohr_time_off_requests.

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 phrase 'Company-wide vacation report' and 'For every current employee' provides clear context that this is an aggregate overview, not a per-employee lookup. However, it does not explicitly name alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety traits. It adds valuable behavioral detail by describing the output structure (each entry has type 'timeOff' or 'holiday' with specific fields) and the default date range. This goes beyond annotations and helps the agent understand what to expect.

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 concise sentences: purpose, defaults, and output format. No redundant information, front-loaded with the core action. Every sentence adds value.

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 two optional parameters and no output schema, the description covers the essential details: what it lists, the default range, and the shape of entries. No missing information is needed for an agent to call it correctly.

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 100%, with both 'start' and 'end' documented with defaults and formats. The description does not add new parameter semantics beyond what the schema already provides; it repeats the default behavior in prose. Baseline 3 is appropriate since the schema carries the semantic load.

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 verb ('List') and a clear resource: employees out of office and company holidays. It distinguishes itself from siblings like bamboohr_list_employees (all employees) and bamboohr_company_holidays (holidays only) by combining both into a single view. The purpose is unambiguous.

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 provides context (date range, defaults) but does not explicitly state when to use this tool versus alternatives. It does not mention exclusions or recommend sibling tools for specific needs, leaving some inference to the agent. However, the combined nature is implied by the title and content.

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