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

With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates that this is a write operation ('Create') but does not mention side effects, validation, permissions, response behavior, or how previousRequest/superseding works. Important behavioral context is missing.

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, front-loaded sentence with no filler or redundant elaboration. It is concise, though it sacrifices informative detail for brevity.

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 7 parameters, no annotations, and no output schema, this description is incomplete. It does not explain the broader request-creation context, dependent resources like get-meta-fields for timeOffTypeId, possible validation rules, or what the tool returns. The schema covers parameters but not operational context.

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 input schema has 100% parameter description coverage, so the schema carries the parameter semantics burden. The description adds no additional meaning beyond the schema, but the baseline of 3 is appropriate because it does not need to compensate for schema gaps.

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 action ('Create') and the resource ('a new time-off request') for an employee, making the core purpose unambiguous. However, it does not explicitly distinguish itself from sibling tools such as get-time-off-requests or estimate-time-off-balance, leaving some differentiation to inference.

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 no guidance on when to use this tool versus alternatives, no prerequisites, and no conditions for when not to use it. The usage is only implied by the tool's name and the verb 'Create'.

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 verb 'List' communicates a read-only enumeration action, and 'all available' suggests completeness. However, with no annotations at all, the description does not disclose the return format (e.g., names, IDs, metadata), required permissions, or any other behavioral constraints. The core behavior is clear, but additional disclosure would strengthen it.

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, direct sentence with no fluff or repetition. It front-loads the action and resource clearly, making it easy for an agent to parse quickly.

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 zero parameters and no output schema, the description is mostly sufficient for calling the tool: the agent knows the action and target resource. It could be slightly more complete by clarifying what a 'dataset' contains and how this relates to sibling analytics tools, but the low complexity keeps this from being a major gap.

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 there is no parameter semantics to document. The schema already fully covers this, making the description's lack of parameter detail acceptable. Baseline for zero-parameter tools 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 uses a specific verb ('List') and resource ('all available BambooHR datasets'), and adds the qualifying context 'for analytics queries'. It clearly states what the tool does, though it does not explicitly distinguish itself from the similarly-named sibling 'discover-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 phrase 'for analytics queries' implies this is the tool to use when you need to see available analytics datasets, but there is no explicit guidance about when to prefer this over siblings like discover-fields, list-custom-reports, or workforce-analytics. Usage context is implied rather than explicit.

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 verb 'List' signals a read-style operation, and there is no contradiction with annotations since no annotations are provided. Still, with no annotations, the description carries the full behavioral burden and does not disclose pagination, output format, or behavior for invalid dataset IDs.

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 one concise sentence with no filler. The key scope information appears up front, making it easy for an agent to quickly understand the tool's purpose.

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 single-parameter list tool, the description adequately states what is returned and the input scope. It is reasonably complete even without an output schema, though it does not mention how dataset IDs can be obtained or handle invalid inputs.

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 schema already describes datasetId as 'The dataset ID (alphanumeric, hyphens, underscores)' with 100% parameter coverage. The description adds only the word 'specific', which reinforces the scope but does not meaningfully supplement the schema's documentation.

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 clear operation and resource: 'List available fields for a specific BambooHR dataset'. It scopes the tool to a single dataset, which helps distinguish it from discover-datasets, but it does not explicitly differentiate it from all sibling tools like get-meta-fields or run-custom-report.

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 'for a specific BambooHR dataset' implies this tool is appropriate when a caller has a dataset ID and wants its fields. However, the description does not provide explicit guidance on when to prefer alternatives, mention prerequisite steps like discovering datasets first, or state when not to use this tool.

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 no annotations provided, the description carries the full disclosure burden. The verb 'estimate' implies a read-only computation, but the description does not state whether pending requests are included, what assumptions are made, or that no data is modified. It provides basic behavioral direction but lacks supporting context.

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 sentence with no repetitive or extraneous content. It front-loads the core purpose and stays appropriately brief for a tool with only two parameters.

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 tool with full schema coverage, the description is essentially complete. It does not specify the structure of the return value since no output schema exists, but the estimated balance is reasonably inferable from the tool name and purpose.

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 input schema provides 100% parameter description coverage, including the date format (YYYY-MM-DD) and numeric employee ID. The tool description adds no parameter-specific meaning beyond what the schema already supplies, so it meets the baseline without extra contribution.

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 uses a specific verb ('estimate') and a distinct resource ('future time-off balance') with a clear target ('employee on a given date'), which distinguishes it from sibling tools like get-time-off-requests and get-whos-out. The agent can determine exactly what this tool computes without inspecting the schema.

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 the use case—projecting a balance for a future date—but does not explicitly compare with alternatives such as get-time-off-requests or get-whos-out. It offers no when-not-to-use guidance or known limitations, leaving the agent to infer context from the tool name and sibling list.

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 no annotations provided, the description carries the full burden. 'Search' implies a read-only operation and the scope is clear, but the description does not state whether results are returned as a list, how matches are ranked, whether matching is partial or exact, or any pagination/limit behavior.

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, front-loaded sentence with no filler. It states the action, resource, and searchable fields efficiently, with every word contributing 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?

The tool is simple with one well-documented parameter, but there is no output schema and no annotations. The description is adequate for invocation but does not explain return shape, result limits, or how it differs from nearby directory tools, leaving some ambiguity for an agent choosing among siblings.

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 schema already provides 100% coverage for the single query parameter, including the same searchable fields. The description adds no additional parameter semantics such as wildcard support, case sensitivity, or matching behavior, so the baseline of 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 uses a specific verb ('Search') and identifies the resource ('employee directory') plus the fields being searched (name, email, department, job title). It clearly communicates the tool's function, though it does not explicitly contrast itself with siblings like get-employee or get-employee-directory.

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: when you need to find employees by name, email, department, or title. However, it provides no explicit guidance about when not to use it or when a sibling like get-employee or get-employee-directory would be more appropriate.

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 no annotations, the description carries the burden of conveying that this is a read-only metadata retrieval rather than a content download or mutation. 'Get metadata' provides that basic behavioral signal, but it does not disclose error handling, permissions, or whether the file must belong to the authenticated company. For a simple getter this is minimally transparent.

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?

A single, front-loaded sentence with no filler. It states the verb, resource, and scope immediately and 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?

The tool is simple (one required parameter, no nested objects), and the description covers the basic call. However, there is no output schema, so a fuller description of what metadata fields are returned would improve completeness; for now, agents must infer the response shape from 'metadata'.

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%, and the fileId parameter is already documented as a numeric string. The description adds no parameter-level detail beyond 'specific company file', so the schema carries the weight; 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 names a clear verb ('Get') and resource ('metadata for a specific company file'), and 'specific' contrasts with sibling list-company-files. However, it doesn't explicitly name or distinguish alternatives like list-company-files or get-employee-files, so the differentiation is inferred rather than stated.

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 phrasing 'for a specific company file' implies this is the single-item lookup counterpart to list-company-files, but there is no explicit guidance about when to choose it over siblings. An agent can infer usage from the input schema requiring a fileId, but no alternatives or 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?

No annotations are present, so the description carries the full burden of explaining behavior. It clearly communicates a read-only, all-departments listing, but it does not disclose details such as whether inactive or hidden departments are included, whether authentication is required, or what the response structure looks like.

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, direct sentence with no wasted words. It front-loads the action and resource immediately and contains no redundant or unclear 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 list operation, the description provides enough context for an agent to select and invoke the tool: it knows the purpose, scope, and lack of required inputs. The absence of an output schema and annotations means response-format details are left unspecified, but for such a simple tool this is acceptable.

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 input schema has zero properties and 100% schema description coverage, so there are no parameters that the description would need to explain. With no parameters, the description is not required to add semantic detail beyond what the schema already conveys.

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 is specific: 'Get all departments in the company' names the verb ('get'), the resource ('departments'), and the scope ('all in the company'). It is also clearly distinct from all siblings, which focus on reports, employees, files, and time off rather than departments.

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 usage context is implied — use this tool when you need a list of all company departments — but there is no explicit guidance about when to prefer it over other list-like tools such as discover-datasets or get-team-info. For a zero-parameter lookup this is a minor gap, not a serious one.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that the tool gets information; it does not mention read-only guarantees, authentication requirements, return format, or any limits or side effects.

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, tight sentence that front-loads the action and resource. There is no filler or redundancy, 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 simple two-parameter get operation with full schema coverage, the description is minimally viable. However, with no output schema and no annotations, it would benefit from a note about what 'detailed information' includes and how optional fields affect the 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 description coverage is 100%, so the input schema already documents both employeeId and fields. The description adds minimal parameter meaning beyond restating that lookup is by ID, which matches the employeeId parameter. 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 clearly states the action ('Get') and resource ('detailed information about a specific employee') and identifies the required key ('by their ID'). It does not explicitly distinguish itself from siblings like find-employee or get-employee-photo, but 'specific employee by ID' provides a reasonable scope.

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 find-employee or get-employee-directory. The description implies the use case of knowing an employee ID, but it does not state exclusions or mention sibling tools.

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?

No annotations are provided, so the description carries the full burden. It indicates a read-style operation ('Get') and broad scope ('full company'), but it does not disclose output format, whether the directory includes active/inactive employees, pagination, or any access requirements.

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 seven-word sentence with no filler or repetition. For a no-parameter tool, this length is appropriate, and the scope 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?

With no annotation or output schema, a fuller description would help: an agent still does not know what fields or record shape the directory returns, or whether any filtering applies. The core action is clear, so it is minimally viable but not complete.

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?

There are zero parameters, so the schema is trivially fully covered. The description adds no parameter-level detail, but none is needed; per the baseline for zero-parameter tools, this is appropriately handled.

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 and resource: retrieving the full company employee directory. It is semantically distinct from siblings like get-employee and find-employee, which target individual employees, though it does not explicitly contrast with them.

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 statement about when to choose this tool over the many employee-related siblings. The phrase 'full company employee directory' implies a bulk-listing use case, but the absence of explicit guidance or exclusions leaves the routing decision to the agent.

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 no annotations provided, the description must carry the behavioral burden. 'List' implies a read operation and 'organized by category' hints at the return structure, but the description omits details such as pagination, authentication needs, or what happens when no files exist.

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 front-loaded sentence with no filler. It states the verb, resource, target, and output organization clearly and efficiently.

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 one-parameter list tool, the description is minimally sufficient, but there is no output schema to clarify return values and no detail about categories or file metadata. The missing usage guidance and behavioral caveats leave clear gaps for an agent to infer.

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% and the employeeId parameter is documented as a numeric employee ID. The description does not add parameter semantics beyond matching 'specific employee' to employeeId, so the baseline score 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 action ('List') and the resource ('all files for a specific employee'), and the phrase 'organized by category' adds useful scope. However, it does not explicitly distinguish this from sibling file-related tools like get-employee-photo or list-company-files.

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 list-company-files or get-employee-photo. The phrase 'for a specific employee' implies one circumstance, but no exclusions or comparison are provided.

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?

No annotations are provided, so the description must carry the behavioral disclosure burden. The verb 'Get' clearly implies a read operation with no side effects, but the description does not mention behavior for missing employees, empty goal lists, or permission requirements.

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, front-loaded sentence with no filler words. Every word contributes to identifying the operation and its scope.

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 getter this is minimally adequate, but with no output schema and no annotations the description could usefully state what is returned (e.g., goal details, status, or empty results). The gaps are not severe, but common call-time questions remain unanswered.

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%; employeeId is already documented as 'The employee ID (numeric)'. The description only adds 'specific employee', which is consistent but adds no meaning beyond the schema, so the 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 uses a specific verb ('Get') and clearly identifies the resource ('performance goals') and the target ('a specific employee'). It distinguishes from sibling tools like get-employee by naming the resource, though it does not explicitly call out any sibling.

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 'for a specific employee' implies this tool is for per-employee goal retrieval, not bulk or directory queries. However, it gives no explicit when-to-use guidance or alternatives, such as using find-employee when the ID is unknown.

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 no annotations provided, the description carries the full burden. It does disclose the key behavioral fact that the tool returns a URL rather than binary image data, which is genuinely useful. However, it says nothing about behavior when no photo exists, URL characteristics (public vs. signed), or authentication needs — acceptable for a simple read tool, but minimal.

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?

A single front-loaded sentence with zero wasted words: verb, resource, output type, and the key sizing capability all in order. 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 simple two-parameter read tool with full schema coverage, the definition is nearly sufficient: the schema documents inputs, and the description states the return value (URL) since no output schema exists. The only gap is guidance on failure or fallback behavior, which is minor for a getter of this simplicity.

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 fully documents both parameters, including the allowed size values and default. The description's phrase 'in a specific size' reinforces the size parameter but adds no meaning beyond what the schema enumerates, so the baseline of 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 states a specific verb ('Get'), resource ('employee photo'), and output type ('URL'), so an agent knows exactly what is returned. The word 'photo' cleanly separates this from sibling tools like get-employee-files, get-employee-goals, and get-employee-directory, though it never names them explicitly.

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, no exclusions, and no context about prerequisites (e.g., that an employee photo must exist). Among many employee-related sibling tools, the agent is left to infer usage entirely from the name and one-line description.

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 no annotations provided, the description carries the behavioral burden. It conveys read-only intent through the verb 'Get' and shows the optional filtering behavior, but it does not mention permissions, the response shape, or what happens when the type filter is omitted. This is adequate for a simple metadata query but leaves some 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?

The description is two short sentences with no wasted words. The core action is front-loaded and the optional filter detail is presented compactly.

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 only one optional parameter and no output schema, the description covers the essential invocation details: what metadata is retrieved and what filters are available. It does not describe the return structure, but that is less critical for a simple metadata lookup. Overall this is largely complete given the low complexity.

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 schema coverage is 100%, and the schema description already fully documents the 'type' parameter and its allowed values. The tool description repeats those values but adds no new meaning beyond the schema, so a baseline score 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 states a clear verb-resource pair: 'Get BambooHR field metadata' and identifies an optional type filter. It is distinct from employee- and report-related siblings, but it does not explicitly distinguish itself from 'discover-fields' or 'discover-datasets', so it misses the top score.

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?

No guidance is provided about when to use this tool versus alternatives like 'discover-fields' or 'discover-datasets'. The description explains what the tool does but not when to prefer it or what conditions would make another tool the better choice.

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 no annotations, the description carries the full burden of behavioral disclosure. It does not state what is returned (e.g., list of employees), how the two optional filters combine, behavior when no filters are provided, or any pagination/sorting details.

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?

One compact sentence with no filler. The action and object are front-loaded, making it easy for an agent to parse quickly.

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?

The tool has no output schema and no annotations, yet the description is minimal. It leaves ambiguity about whether 'team members' means direct reports or a wider hierarchy, how filters interact, and what happens when no parameters are supplied (both are optional).

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 maps 'supervisor/manager' to the supervisorId parameter implicitly, but it adds no meaning beyond the schema's existing parameter 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 a specific verb ('Get'), a resource ('team members'), and a scoping context ('for a specific supervisor/manager from the employee directory'). It clearly differentiates from get-employee-directory by focusing on a supervisor's team, though it does not explicitly name sibling alternatives.

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?

No guidance is provided about when to use this tool versus siblings like get-employee-directory or find-employee. There is no mention of exclusions, prerequisites, or decision criteria beyond the basic 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It signals a read operation through 'Get' and lists filters, but it does not disclose return format, pagination, permissions, or behavior when filters conflict. This is minimal but not misleading.

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 sentence with the primary action and filter list front-loaded. It contains zero redundant words and is easily parsed at a glance.

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 5-parameter tool with 2 required parameters and no output schema, the description gives enough to initiate a call but omits the return shape and does not clarify that the date range is mandatory. It is adequate for a simple filtered list operation but not fully comprehensive.

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 every parameter is already documented in the schema. The description's phrase 'date range, employee, status, or action' restates the parameter set in prose but adds no new format, constraint, or relationship details beyond what the schema provides.

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 uses a specific verb ('Get') and resource ('time-off requests') and explicitly enumerates the filtering dimensions (date range, employee, status, action), making the tool's purpose unmistakable. No sibling tool retrieves time-off requests, so it is clearly distinct from create-time-off-request and estimate-time-off-balance.

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 the general-purpose retrieval tool for time-off requests, especially through the phrase 'filtered by date range, employee, status, or action.' However, it provides no explicit guidance on when to choose this tool over alternatives such as get-whos-out or estimate-time-off-balance, nor any exclusions.

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?

No annotations are provided, so the description carries the full burden. It clearly indicates a read operation ('Get a list') and states the temporal scope, but it does not define what qualifies as 'out', whether returns are paginated, or what the employee list contains beyond employees.

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 focused sentence with no filler or redundant information. It efficiently communicates the tool's core purpose and temporal scope.

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 tool with two optional, fully described parameters, the definition is mostly adequate. However, there is no output schema and no annotation coverage, and the description does not clarify what fields are returned for each employee or precisely what 'out' includes.

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%; both 'start' and 'end' parameters have descriptions with format and defaults. The description adds little beyond the schema beyond the general date-range concept, so the baseline score 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 uses a specific verb ('Get') and a clear resource ('list of employees who are currently out or will be out') with a date-range scope. It is unambiguous about what the tool returns, though it does not explicitly distinguish itself from the similar get-time-off-requests sibling tool.

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: when you need employees who are currently out or will be out within a date range. It does not name alternatives or exclusions, so it stops short of full guidance, but the intended use case is explicit.

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 no annotations, the description must carry the behavioral disclosure burden. It implies a read-only list operation and indicates the output is grouped by category, but it does not explicitly state side-effect-free behavior, pagination, or whether file contents or metadata are returned.

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 sentence with no filler. The action and scope are front-loaded, making it easy to parse quickly.

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 listing tool, the description conveys the essential scope ('all company-level files') and the output organization ('by category'). It does not enumerate the exact categories or specify the returned shape, but the low complexity makes the description 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?

The tool has zero parameters and 100% schema description coverage, so there is no parameter semantics burden on the description. Baseline 4 applies because no parameters require explanation.

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 uses a specific verb ('List') and resource ('all company-level files'), and adds 'organized by category' to define the output structure. It clearly states what the tool does, though it does not explicitly differentiate it from the sibling get-company-file or get-employee-files beyond the 'company-level' scope.

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?

No usage guidance is provided. The description does not state when to prefer this tool over get-company-file or get-employee-files, nor does it mention any conditions or exclusions for using it.

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 no annotations, the description carries the full burden. 'List' implies a read-only operation, but the description does not disclose potential pagination, authentication needs, or the structure of the response. For a zero-parameter list tool, this is minimally adequate but not detailed beyond the core behavior.

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?

A single, direct sentence with no filler words. The key action and target resource are front-loaded, making it immediately parseable by an agent.

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 low complexity (zero parameters, no output schema), the description gives the essential purpose. However, it does not clarify what fields the returned list contains (e.g., names, IDs) or how it differs from list-report-presets, so an agent might still lack confidence in what the tool returns. The lack of an output schema makes the description the only source of this information.

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?

There are zero parameters, so no semantic clarification is needed. The schema is fully covered by having no properties. The baseline for zero-parameter tools is 4, and the description appropriately says nothing about parameters since none exist.

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 ('saved custom reports available in BambooHR'). It distinguishes itself from siblings like run-custom-report and run-adhoc-report by focusing on enumeration rather than execution, making its purpose 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 implies usage when an agent needs to see all saved custom reports, but it does not explicitly state when to prefer this over list-report-presets or run-custom-report. No alternatives or exclusions are named, leaving some inference required.

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?

No annotations are provided, so the description must carry the behavioral burden. 'List' implies a read-only operation, and 'built-in' suggests stable presets, but the description does not disclose return format, ordering, or pagination behavior. For a simple zero-parameter listing tool this is adequate but not rich.

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 entire description is a single focused sentence with no filler. It front-loads the action and resource and includes the key relationship to run-adhoc-report without unnecessary detail.

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 has no parameters and no output schema, the description is nearly complete: it tells an agent what the tool returns (built-in field-set preset names) and why that matters (they can be executed by run-adhoc-report). It could optionally specify whether return values include only names or richer preset metadata, but this is a minor gap.

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 the empty schema already fully documents this. The description adds that presets are identified/executed by name, which is useful context for how results may feed into run-adhoc-report, though no parameter-level documentation is 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 uses a specific verb ('List') plus a clear resource ('built-in field-set presets') and explicitly ties them to run-adhoc-report by name. This differentiates it from siblings like list-custom-reports, which lists custom reports rather than built-in presets.

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 'that run-adhoc-report can execute by name' gives clear context: this tool is the discovery mechanism for preset names to pass to run-adhoc-report. It does not explicitly list excluded alternatives, but the built-in/custom distinction and named target are enough to guide selection.

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 no annotations, the description carries the full burden of behavioral disclosure. It provides valuable runtime behavior: output defaults to JSON unless format=CSV, and the onlyCurrent flag controls whether terminated employees are included. It does not mention permissions or side effects, but the tool's read-oriented report nature makes this less critical.

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 cover the core action, parameter alternatives, output format, and the key scoping flag. The most important information is front-loaded and every sentence earns its place without redundancy.

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?

The definition gives enough to invoke the tool correctly: it explains preset vs fields, JSON/CSV output, and the onlyCurrent behavior. Gaps are minor, such as not explicitly stating that presetName and fields are mutually exclusive and not pointing to run-custom-report for saved custom reports, but overall it is reasonably complete.

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, but the description adds meaningful parameter relationships: presetName and fields are presented as alternatives, format=CSV overrides the JSON default, and onlyCurrent=false includes terminated employees. This goes beyond the schema by clarifying defaults and usage intent.

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 action ('Run an ad-hoc custom report') and the resource ('BambooHR') with a distinct mechanism ('posting a field list'). It also differentiates itself from saved-report tools by emphasizing ad-hoc field selection, making its purpose unambiguous even among siblings like run-custom-report.

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 explains internal options ('Use either a saved preset or pass an explicit fields array') and notes the onlyCurrent behavior, but it does not explicitly state when to choose this tool over run-custom-report or list-report-presets. The 'ad-hoc' wording implies the use case, but no direct alternatives or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'execute' and 'get results', but does not mention whether the operation is read-only, whether it can be long-running, how format affects output, or any error conditions. The lack of behavioral context beyond the basic action leaves significant 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?

The description is a single, direct sentence with no fluff or repetition. It is front-loaded with the action and resource, making it quick to parse. There is no wasted wording.

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 two-parameter tool with no output schema, the description is adequate but minimal. It confirms that the tool returns results, but does not hint at result structure, pagination, or whether the format parameter is required. Since the schema fully covers parameters, some context is missing but not critical.

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 input schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds no additional meaning about reportId or format, relying entirely on the schema to document parameter semantics.

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 ('Execute'), the resource ('a saved custom report'), and the outcome ('get results'). It does not explicitly differentiate from the sibling run-adhoc-report, but the phrase 'saved custom report' implies a distinction from ad-hoc reports, making the core purpose understandable.

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 explicit guidance on when to use this tool versus alternatives like run-adhoc-report or list-custom-reports. The description only implies usage through 'saved custom report', but never states prerequisites, exclusions, or conditions for choosing this tool.

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 no annotations, the description carries the disclosure burden. It usefully exposes that allowed fields may be restricted by an environment variable, which is non-obvious. It does not explain behavior on restriction, partial updates, or error handling, leaving 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 short sentences with no filler. The primary action is front-loaded, and the environment-variable caveat is the only additional detail included and it 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 two-parameter mutation, the schema plus description provide a workable calling contract. Still, with no annotations or output schema, an agent is left guessing about what happens when a field is restricted or what the response looks like.

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 schema already documents both parameters fully, including types and an example for fieldsJson. The description adds no parameter-level meaning, but at 100% schema coverage that is acceptable.

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?

States the exact operation (Update) and resource (employee information), clearly distinguishing it from the many get- and report-oriented sibling tools. The action and purpose are 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 write intent is obvious, and the BAMBOO_UPDATE_ALLOWED_FIELDS note gives a relevant condition to consider before calling. However, it does not explicitly address when to use this tool instead of get-employee or how to handle restricted fields.

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?

There are no annotations, so the description carries the full burden of behavioral disclosure. It indicates an analytics query but does not state whether it is read-only, what the response contains, whether pagination exists, or any permissions/rate-limit considerations. This is a minimal behavioral signal.

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 sentence, front-loads the primary action, and contains no filler. Every phrase contributes meaning: what it runs, the target system, and the key optional behavior.

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 relatively simple three-parameter tool with full schema coverage, the description is minimally viable for basic invocation. However, with no annotations, no output schema, and no sibling differentiation, it leaves gaps around return value expectations and tool selection guidance.

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 structured schema already documents all parameters. The description adds a small reinforcement of 'optional filters', matching filtersJson, but it does not provide additional semantic detail 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 clearly states the verb 'Run' with a specific resource ('analytics query against a BambooHR dataset') and mentions optional filters. It does not explicitly distinguish itself from sibling tools like run-adhoc-report or run-custom-report, but the dataset-focused wording is sufficiently specific for basic purpose clarity.

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?

No guidance is given about when to use this tool versus alternatives such as run-adhoc-report, run-custom-report, or discover-datasets. The description implies usage for dataset queries but provides no context, exclusions, or selection criteria.

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