TalentHR MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true and idempotentHint=false; the description adds genuinely new context beyond them — the note is visible to the hiring team, triggers no e-mail notifications, and is permanent because it cannot be edited or deleted through this server. That immutability note is exactly the kind of consequence an agent needs before a non-idempotent write.

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 tight sentences, front-loaded with the WRITE marker, then prerequisites and side effects. No filler and nothing buried.

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 3-required-parameter mutation with no output schema, it covers prerequisites, visibility, notification behavior and irreversibility. The only minor gap is not saying whether the call returns the new note's identifier or just a confirmation, which would help a caller that needs to reference the note later.

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?

With 100% schema description coverage the baseline is 3, and the description adds provenance for the two id parameters by naming talenthr_get_applicant as their source. It does not restate the note_text length limit, but the schema already documents that.

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?

Opens with a specific verb+resource pair ("WRITE: add an internal note to a job application") and scopes it as internal-only. An agent can distinguish it from read siblings like talenthr_get_applicant and from the other create tool, talenthr_create_time_off_request, without opening either 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?

States the prerequisites (job position id and application id) and routes the agent to talenthr_get_applicant to obtain them, which is clear use context. It does not, however, give explicit when-not conditions or contrast with other ways of recording applicant information.

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 only declare destructive/openWorld/non-idempotent; the description goes far beyond by disclosing the manager e-mail side effect, the exact semantics of the auto-approve path, the date-window and cycle restrictions, and that the action 'Cannot be undone through this server' — consistent with destructiveHint=true. This is the side-effect detail an agent needs before a mutation.

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?

Front-loaded with the write action and the highest-stakes branch (manager e-mail) first; every sentence carries information. It is dense to the point of run-on in the preapproved sentence, which slightly slows parsing, but nothing is wasted.

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?

A destructive 7-parameter mutation with no output schema, and the description covers side effects, constraints, and the key optional parameter's fallback. It stops short of saying what comes back (e.g., whether a request id or pending state is returned), which forces the agent to infer the success signal.

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 baseline is 3, but the description adds real meaning: the per-day value convention (1, 0.5, 0 for non-working days) and, crucially, that TalentHR computes amounts when amount_options is omitted — behavior absent from the schema. preapproved's 'allowed to' caveat also adds nuance beyond the schema text.

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?

Opens with an explicit verb+resource pair ('WRITE: book a time off request for an employee') and immediately distinguishes the operation from sibling reads (list_time_off_requests) and the related reply_time_off_request. An agent can route to it without opening 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?

Gives explicit when-to-use conditions for the ambiguous parameter ('only use it when the user explicitly said the time off is already approved'), names the sibling that supplies the type id (talenthr_list_time_off_types), and states hard eligibility constraints (within one year, inside a time off cycle). No 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?

readOnlyHint=true already declares this is a safe read, so the description's added value is the return-content disclosure (contact, CV, applications with hiring step). It omits behavior like not-found handling, authorization needs, or response shape, so 3 is appropriate given annotation coverage.

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 tight sentences, front-loading what the call returns and then the cross-tool link to create_applicant_note. 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 carries the return-value burden and does so with a concrete field listing. Minor gaps remain (not-found behavior, whether applications are paginated), but the essential shape is clear.

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?

Only one parameter exists and the schema documents it fully at 100% coverage, including the source (from talenthr_list_applicants) and bounds. The description adds nothing 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?

States a specific verb (Get) and resource (one candidate) plus the payload returned: contact data, description, CV info, and all applications with their hiring steps. The phrase 'one candidate' distinguishes it from the sibling talenthr_list_applicants.

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?

Usage is implied (fetch a single applicant) and it links forward to talenthr_create_applicant_note via the application ids, but it never names talenthr_list_applicants as the way to obtain an applicant_id, leaving alternative selection implicit.

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 only declare readOnlyHint=true, so most behavioral burden falls on the description, which delivers the important surprises: default end date, a max 2-year range, and that unfiltered results include terminated employees. It does not mention pagination or result ordering, which is a meaningful omission for a potentially large calendar.

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?

Front-loads the core purpose in a short clause, then packs defaults and the filter grammar into two dense sentences with no filler. The long filter sentence is heavy but every clause carries actionable 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?

With no output schema, the description does state what the payload conceptually contains (employees, their time off requests, holidays) plus range and filter semantics. It could say more about response shape or volume, but an agent has enough 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?

Schema coverage is 100% (baseline 3), but the description goes beyond it by enumerating the valid filter keys (time_off, department, division, location, emp_state, time_off_type), giving an example syntax string, and explaining the end_date default and employee_id narrowing. The schema only says valid keys come from talenthr_get_directory_filters, so this compensates usefully.

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 a specific verb+resource ('Who is off when: employees with their time off requests and the holidays for a date range'), which distinguishes it from siblings like talenthr_list_employee_time_off_requests and talenthr_list_holidays by making it the combined calendar view. The scope (per-employee time off plus holidays) 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?

Gives clear operating context: default range extends to end of the start month, default scope includes every employee including terminated ones, and it names the filter keys and the single-employee variant. It stops short of explicitly naming alternatives (e.g. use list_employee_time_off_requests for request-level detail or get_time_off_report for aggregates), so an agent must infer when not to use 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?

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add beyond that, and it does: it discloses that results are id-bearing option lists and which four filter dimensions are covered. It doesn't describe the response envelope or whether the options are account-scoped, but for a zero-parameter lookup that is a minor gap.

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 sentence, front-loaded with the verb and the returned content, with the intended consumer trailing. No filler and nothing repeated from the title.

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 carries the burden of saying what comes back, and it does so by enumerating the option categories and noting each carries an id. What is missing is only the exact response shape, which is low-stakes for a static options list.

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 takes zero parameters, so the baseline is 4 and the description has nothing further to explain. It correctly implies no inputs are needed by presenting the tool as a pure options lookup.

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?

Specific verb ('List') plus resource ('valid filter options'), and it enumerates the concrete categories returned (departments, divisions, locations, employment statuses) along with the ids. This distinguishes it from siblings like talenthr_list_departments, though it never explicitly warns that those sibling list tools are not the filter source.

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?

States the purpose plainly: build the `filter` argument of talenthr_list_employees and talenthr_get_calendar. That gives an agent a concrete triggering condition and names the downstream consumers. It stops short of saying when not to call it or of naming alternatives for other filtering needs.

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, but the description adds substantive context beyond that: the payload contains sensitive personal data and can include the SSN, plus a caution against speculative fetching. Return shape and pagination are not discussed, but for a single-record read the sensitivity disclosure is the key behavioral fact.

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 waste: the first front-loads purpose plus returned fields, the second front-loads the privacy constraint. The long field list is dense but each item distinguishes the tool's payload.

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 read-only tool with no output schema, the description compensates by enumerating the returned fields and flagging sensitive content. Nothing an agent needs to invoke 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 schema already documents employee_id including its source (talenthr_list_employees). The description adds nothing about the parameter, 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?

States a specific verb and resource ('Get one employee's profile') and then enumerates the exact fields returned, which clearly separates it from the list, report, and sub-resource siblings (get_employee_job, get_employee_benefits). An agent can identify the tool without opening 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?

Provides an explicit guardrail: 'only fetch it when the user asked about that person,' which tells the agent when not to call it. It stops short of naming an alternative for discovery (e.g., list/search), so it is strong but not fully routing.

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, so safety is covered and the description only needs to add operational traits. It does: it discloses that results are paged and that next_offset is the continuation mechanism, which is exactly the kind of behavior an agent needs beyond the annotation. It stops short of stating default page size or that an empty list means no assignments.

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, with the core purpose front-loaded and the pagination caveat second. Nothing repeats the title verbatim and every clause carries 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 read-only five-parameter list tool with no output schema, the description covers the essentials: what entity is returned, that two asset kinds are mixed in, and how to page. The remaining gap is the shape of an individual asset record, which the description does not sketch and which no output schema supplies.

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 including the enum'd sort/order fields is already documented, setting a baseline of 3. The description adds nothing new about parameters — its mention of next_offset merely restates what the offset property already says, and it does not clarify that sort/order apply to the returned asset rows.

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 and resource ("List the assets") and scopes it to "one employee," plus it disambiguates the overloaded word "assets" as inventory and memberships. It implicitly separates itself from the sibling talenthr_list_assets, but never names that sibling, so the differentiation is inferential rather than explicit.

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?

Usage is implied by the per-employee scope: use this when you already have an employee_id and want their assigned assets, and presumably use talenthr_list_assets otherwise — but the description never says that. The only explicit guidance is pagination ("use next_offset to continue"), which is a mechanical instruction rather than a when-to-use rule.

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, so the safety profile is covered and the description does not need to re-state it. The description adds useful return-content context by naming the fields returned (category, cost, start and end date), which an agent needs since there is no output schema, but it says nothing about empty results, enrollment gaps, or history depth.

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 sentence with the field list packed into a parenthetical, front-loading the action and scope with zero filler. 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 one-parameter read tool with a clear annotation and no output schema, the definition covers the essentials and even sketches the return fields. Only the relationship to talenthr_list_benefits is left implicit, which is a minor gap given the tool's 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 coverage is 100% and the single parameter already documents its own origin ('from talenthr_list_employees'), so the schema does the heavy lifting. The description adds no meaning beyond that — no format edge cases, no note about invalid or unknown employee ids.

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 and resource ('List the benefits one employee has'), which pins down both the entity and the scope. The phrase 'one employee has' implicitly separates it from the sibling talenthr_list_benefits, but that sibling is never named, so the differentiation requires a small 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?

Usage is implied by 'one employee' — an agent can infer this is for per-employee benefit lookups rather than benefit-plan catalogs. But there is no explicit guidance on when to prefer it over talenthr_list_benefits, and no mention of prerequisites such as whether the employee must be active or enrolled.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower, and the description adds a useful caveat that compensation data is sensitive. It does not disclose volume or pagination behavior for what is clearly a multi-collection historical response, nor whether terminated/inactive records are included.

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 dense sentence, front-loaded with the verb and resource, followed by a compact colon list of contents and a single high-value caution. No redundant restatement of the title or annotations.

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 read with no output schema, enumerating the returned record categories plus the compensation-sensitivity warning covers what an agent needs to call it and interpret the result. Minor gaps remain around historical range and multi-collection response shape.

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 schema already documents that employee_id comes from talenthr_list_employees, so the description's silence on the parameter is acceptable. It adds no format or sourcing detail beyond the schema, making the baseline 3 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?

States a specific verb ('Get') and a well-defined resource ('one employee's job information'), then enumerates the record types returned: employment status history, manager records, job records, compensation, benefits. This enumeration effectively distinguishes it from generic sibling reads like talenthr_get_employee, though no sibling is named 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?

The clause 'only fetch it when the user asked' is real usage guidance for the sensitive compensation portion, but it is a data-handling constraint rather than a routing rule. It never says when to prefer this tool over talenthr_get_employee or talenthr_get_employee_benefits, which overlap with the returned data.

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, so the safety profile is clear. The description adds valuable behavioral context by specifying the returned fields (budget, original budget, used days, accrual figures) and clarifying that the optional parameters limit results to a cycle. It does not mention pagination, but for a per-employee read operation that is 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?

A single, front-loaded sentence that efficiently conveys the core purpose, return fields, and optional filters. Every phrase earns its place, and there is no redundancy or 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?

For a simple read tool with annotations, rich schema descriptions, and no output schema, the description provides adequate completeness: it states the returned data and how to restrict scope. It could be slightly improved by clarifying whether 'active' and 'time_off_cycle_id' can be combined or what happens if neither is provided.

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 all parameters are already documented. The description mirrors the schema's intent for 'active' and 'time_off_cycle_id' without adding new syntax, mutual exclusivity rules, or defaults. It meets the baseline for well-covered schemas but offers little extra semantic value.

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 and resource ('Get one employee's time off budgets per type and cycle') and lists the specific data fields returned. It does not, however, differentiate this tool from related siblings like talenthr_list_employee_time_off_requests or talenthr_get_time_off_report, which could confuse an agent choosing between 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?

The description implies the use case ('how many days they have left') and explains how to filter by cycle, but it gives no explicit guidance on when to use this tool versus alternatives such as the requests list or the time off report. The agent is left to infer the appropriate context.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's added value is the return shape: a monthly series plus a current-headcount figure, which matters because there is no output schema. It does not disclose permission requirements, whether the monthly series is sparse or zero-filled, or how the 'current' value relates to the end of the requested range.

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 dense sentence that front-loads the primary metric and appends the supplementary 'current headcount' clause. No filler, though the parenthetical enumeration is doing a lot of work and slightly buries the grouping parameter story.

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 five optional parameters, no output schema, and no required inputs, the agent has to infer defaults – notably what period applies when neither period nor start_date/end_date is supplied. The description covers the returned data reasonably but leaves this default behavior and the relationship between period and the custom range undocumented outside the schema.

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 each parameter is already pattern- or enum-constrained with its own explanation, so the schema does the heavy lifting. The description's only added semantic is that grouping is optional and that dimensions include 'location, department, division, ...', which is marginally richer than the schema's enum list.

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 a concrete resource (headcount per month over a period, plus current headcount) and explicit breakdown dimensions, so the agent knows exactly what data comes back. It stops short of distinguishing itself from other report siblings such as get_hires_leaves_report or get_time_off_report, which share the 'report' niche.

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?

Usage is only implied by the resource name and the phrase '(total and optionally grouped by ...)', which signals that grouping is an opt-in variant. There is no explicit when-to-use, no mention of the alternative report tools, and no note that the filter ids must first be retrieved via talenthr_get_directory_filters (that only appears in the schema).

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 readOnlyHint annotation already covers the safety profile, so the description carries a lighter burden. It does add the useful grain detail 'per month over a period,' but says nothing about how attrition rate is computed, how the period interacts with the custom date range, or what the response 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?

A single short sentence with no filler, and the metric list is front-loaded. It reads as a fragment rather than a full statement of purpose, which slightly weakens the framing, but nothing is wasted.

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?

No output schema exists, yet the description doesn't hint at the response shape or how metrics are broken down. For an analytics report with zero required parameters and four optional scoping params, the agent has enough to call it but not enough to predict or interpret its output.

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 every parameter carries its own description, including the filter syntax, valid period values, and the start/end-date alternative with a 36-month cap. The description adds no parameter meaning beyond that, 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 names the report's contents (hires, terminations, attrition rate) and grain (per month), which is more specific than the title alone. However, it doesn't say what distinguishes it from sibling reports like talenthr_get_headcount_report or talenthr_get_time_off_report, leaving the agent to infer which report answers which question.

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 no when-to-use guidance, no prerequisites, and no alternatives. An agent must guess whether this is the right report for a given HR analytics question versus the headcount or time-off reports.

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 only declare readOnlyHint=true; the description adds genuinely new behavioral context by scoping results to 'current employees' (implying inactive/terminated records are excluded) and revealing that hierarchy is returned as a flat list with a reports_to_employee_id rather than a nested tree. It omits size/pagination limits, which matters for a whole-org dump.

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 sentence that front-loads the operation, then the returned fields, then the question it answers. 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 input parameters and no output schema, the description must carry the return-shape burden, and it does name the key fields and the manager-id linkage. It stops short of describing ordering, pagination, or volume, which is a modest gap for an org-wide listing.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate with the schema coverage at 100%.

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 a concrete verb and resource ('List all current employees') plus the exact fields returned (manager's reports_to_employee_id, job title, role) and the question it answers. An agent can tell this produces a reporting hierarchy rather than a plain roster, though it never names talenthr_list_employees as the distinction.

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 'to answer who reports to whom' implies the use case, but there is no explicit when-to-use versus talenthr_list_employees or talenthr_get_employee, and no stated exclusions. The agent must infer routing from the sibling names alone.

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 readOnlyHint annotation already establishes the safety profile, and the description adds meaningful scope details: only approved, non-canceled time off is included, and results are aggregated by month, weekday, and type. However, it says nothing about permission requirements, whether 'approved' uses request or effective approval dates, or any pagination/row-limit behavior for the report.

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 dense sentence that front-loads the inclusion criteria and then the aggregation dimensions. Every clause carries information and nothing is redundant.

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 helpfully specifies the shape of the aggregation (per month, per weekday, split by time off type), which is the most important thing an agent needs. It is nearly complete for a read-only report, though it leaves default behavior ambiguous when no parameters are supplied.

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 all four parameters (filter, period, start_date, end_date) are already well documented, including valid keys routing to talenthr_get_directory_filters. The description adds only the phrase 'for a period', which does not extend parameter meaning beyond the schema, 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?

States a specific verb-less but precise resource and scope: approved, non-canceled time off summarized per month and per weekday, split by type. An agent can tell this is an aggregated time-off report rather than raw request listing, but the description does not distinguish it from sibling reports like talenthr_get_hires_leaves_report or talenthr_get_headcount_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?

No guidance on when to choose this report versus the hires/leaves report, headcount report, or per-employee time off budgets/requests. The only implied usage comes from the data scope, and there are no exclusions or prerequisites stated.

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 only declare readOnlyHint=true, and the description adds real behavior beyond that: cross-position scope, pagination via next_offset, and what the two undocumented filters actually do. It stops short of describing default ordering or result size, so not a 5.

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, front-loaded with scope and payload, then paging, then filter semantics. Every clause carries information an agent needs; nothing is redundant.

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 paginated list with no output schema, the description discloses returned fields loosely ('contact data and the number of applications'), paging, and both filter behaviors. Default limit/sort are left to the schema, which covers them adequately.

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 67%; the two undescribed parameters (`search`, `starred_only`) are precisely the ones the description explains, including which fields `search` matches and that `starred_only` means the talent pool. The remaining four are already documented in the schema, so this compensates well for the gap.

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 a specific verb and resource (list candidates) plus the scope 'across all job positions', which effectively distinguishes it from the sibling talenthr_list_job_position_applicants. It also names the payload fields (contact data, application count). The sibling is not named explicitly, so it falls short of a 5.

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?

Gives clear usage context: use `search` to match name/e-mail and `starred_only` to reach the talent pool, plus how to page. It does not state exclusions or explicitly point to talenthr_list_job_position_applicants when the caller wants a single position, so a 4 rather than 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 readOnlyHint=true, so the safety profile is covered; the description adds real behavioral context on top: pagination continuation via next_offset, the scope of `search` matching, and the filter expression format. It doesn't mention result counts or default ordering, but nothing contradicts the read-only annotation.

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, front-loaded with what the tool returns, then paging, then parameter hints. No repetition of schema text and 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?

For a 6-parameter, no-output-schema list tool, the description compensates well by enumerating returned fields and pointing to talenthr_get_directory_filters for valid filter keys. Minor gaps remain around sort/order and whether unpaged calls silently truncate at the default limit of 10.

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?

With 83% schema coverage the baseline is 3, and the description earns above it by explaining `search` semantics (name, description, category) and giving a concrete filter example (status=1,2;category=19) that shows multi-value syntax. Sort/order behavior is left entirely to 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?

Specific verb ('List') plus resource ('company's assets') plus the exact fields returned (status, category, serial number, cost, purchase/warranty dates). The qualifier 'company's' implicitly distinguishes it from the per-employee sibling talenthr_get_employee_assets, so an agent can route between the two without opening a 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?

Gives concrete operational guidance: page with next_offset, use `search` to match name/description/category, use `filter` for status and category ids. It does not explicitly say when to prefer this over talenthr_get_employee_assets, so it stops short of full alternative routing, but the intended usage is 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that results carry category, cost, dates and eligibility, but says nothing about pagination, result volume, or ordering for what could be a long list.

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 tight sentences: purpose and returned fields first, filter mechanics second. 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?

No output schema exists, and the description compensates by enumerating the returned attributes, which is the main thing an agent needs. Pagination behavior is the one remaining 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?

Schema coverage is 100% and the schema already documents the key=ids;key=ids pattern, valid keys, and the get_directory_filters pointer. The description repeats the same example rather than adding new semantics, so 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?

States a specific verb (List) and resource (the company's benefits) plus the fields returned (category, cost, dates, eligibility). It is distinguishable from talenthr_get_employee_benefits by being the company-wide catalog, though it never says so 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?

Explains how to filter and points the agent to talenthr_get_directory_filters for valid keys and ids, which is clear usage context. It stops short of stating when to prefer this over get_employee_benefits.

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?

readOnlyHint already declares safety, so the description only needs added context. It supplies one genuinely useful fact: the returned ids are the filter keys used by talenthr_list_employees — but says nothing about pagination, ordering, or whether inactive departments are included.

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 sentence with the core action front-loaded and the integration detail tucked into a parenthetical. 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?

No output schema exists, so the description must convey the return concept; 'departments with their ids' does that at a high level, though it omits other likely fields (name, headcount, parent). Nothing needed to invoke the tool 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?

Zero parameters, so the baseline is 4; the description correctly adds no param noise and instead spends its words on what the returned ids mean.

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 a specific verb and resource: lists all company departments with their ids. However, the sibling set includes talenthr_list_divisions and talenthr_list_locations, and the description never distinguishes departments from divisions, which an agent could easily confuse.

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 parenthetical implies usage — fetch ids before calling talenthr_list_employees — but it is phrased as a fact rather than an instruction, and no exclusions or alternative tools are named.

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, so the safety profile is covered. The description adds genuinely useful relational context — that the returned ids are the values talenthr_list_employees filters on and that employee records reference them — which is not derivable from structured fields.

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 sentence with no waste, leading with the resource and following with the practically important detail about id usage.

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-param list tool there is little to omit, and the key fact (ids feed employee filtering) is present. With no output schema, a brief indication of other returned fields (e.g., names) and a note on how divisions differ from departments would make it fully 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?

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond what the empty 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?

States a specific verb and resource ('List all divisions of the company') and clarifies the payload ('with their ids'). It does not, however, distinguish divisions from the closely related sibling talenthr_list_departments, which an agent could easily confuse.

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?

Implies a clear use case: fetch division ids so they can be passed to talenthr_list_employees as filters. No explicit exclusions or when-not-to-use guidance, and no routing away from talenthr_list_departments.

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 only declare readOnlyHint=true, so the description usefully adds pagination mechanics (next_offset continuation, limit max 100) and a data-sensitivity warning that the response contains personal data. It does not cover permissions/scopes or rate limits, but for a read-only directory listing the added context is substantial.

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, front-loaded with the resource and the returned field set, then paging, then filtering, then the privacy note — a logical reading order with no filler. The long comma-separated field list is slightly heavy but earns its place by telling the agent what comes back without an output schema.

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 four optional parameters, no output schema, and only a readOnlyHint annotation, the description carries the needed burden: it enumerates return fields, explains paging and offset continuation, explains the filter string source, and warns about personal data. An agent can call this correctly without consulting anything else.

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 all four parameters are already documented with formats and examples, making 3 the baseline. The description mostly restates the schema's own pointer to talenthr_get_directory_filters and adds only a light note that custom_fields come from the company's custom field catalog.

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?

A specific verb plus resource ('List the company's employees from the TalentHR directory') with an explicit enumeration of the returned fields, which makes the bulk-list nature obvious against the singular get_employee sibling. It never explicitly names that sibling or states the single-vs-bulk tradeoff, so it stops just short of the top mark.

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?

Gives concrete operational guidance: page with next_offset, cap limit at 100, obtain filter ids from talenthr_get_directory_filters, and restrict custom field slugs to the company's catalog. It also adds a consumption rule ('summarize only what the user asked for'). It does not say when to prefer talenthr_get_employee instead, so no explicit exclusion.

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 only declare readOnlyHint; the description adds real behavioral detail beyond that — pagination via next_offset and the non-obvious rule that approved=null means pending. It stops short of stating default page size or ordering 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?

Three short, front-loaded sentences with no filler; scope first, then pagination mechanics, then the null-status caveat. Every sentence carries information an agent would otherwise have to guess.

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 paged list with no output schema, the description covers returned fields, paging continuation, and status interpretation. Minor omissions like sort behavior and default limit are handled by the schema, so nothing critical 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 all four parameters are already documented, including offset's 'use next_offset from the previous reply' hint. The description's pagination note restates what the schema already says, adding little new meaning.

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 a specific verb and resource ('List one employee's time off requests') and enumerates the returned fields (dates, type, days, status). The 'one employee's' scoping implicitly separates it from the org-wide report siblings, though no sibling is named 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?

Usage is only implied: the tool is clearly the per-employee read path, but the description offers no explicit when-to-use/when-not versus talenthr_get_time_off_report or talenthr_get_employee_time_off_budgets. The agent must infer the routing itself.

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 declare readOnlyHint=true, so the safety profile is already covered. The description adds useful context beyond that: the default-to-current-year behavior and the fact that results include date and applicability scope. It stops short of describing ordering, count, or whether non-applicable holidays are omitted.

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 sentence, front-loaded with the action and resource, with the default behavior and return content folded in compactly. No filler or 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?

For a single-optional-parameter read tool with no output schema, the description covers the essentials: scope, default, and the shape of returned data. A brief note on result ordering or whether the list is filtered by employee applicability would make it fully 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% and the single parameter already documents its bounds (1990-2100) and its default. The description restates the default but adds no further semantics such as whether partial-year or multi-year queries are possible. 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?

States a specific verb (List) and resource (company holidays) plus the scoping dimension (a year, defaulting to the current one). It is clearly distinguishable from siblings like talenthr_list_time_off_types or talenthr_get_calendar, though it doesn't explicitly name the boundary between 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?

Usage is only implied: an agent can infer this is the read path for holiday data, and the default-year note hints at optional filtering. There is no explicit when-to-use statement, no exclusion, and no mention of the related calendar or time-off-type tools that might also answer a holiday question.

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 only declare readOnlyHint=true; the description adds substantive behavior beyond that: the shape of returned data (contact data, current hiring step, disqualification status) and the pagination contract. It stops short of noting ordering defaults or result-size limits, but the added context is genuinely useful.

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: payload content first, paging second, search semantics third. Nothing is repeated from the title and no sentence is 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?

For a read-only list tool with no output schema, the description covers what comes back, how to page, and the one ambiguous filter. The only remaining gap is the caller must guess when to prefer this over the broader talenthr_list_applicants.

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 leaves `search` undescribed (83% coverage overall), and the description fills that gap by naming the three matched fields — first name, last name, and e-mail. It also reinforces the offset/next_offset continuation pattern, though sort/order semantics are left entirely to 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?

States a specific verb and resource with scope conveyed ('applicants of one job position') and lists the notable fields returned. It doesn't explicitly distinguish itself from the sibling talenthr_list_applicants, which is the main ambiguity an agent would face.

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 paging instruction ('use next_offset to continue') is a real operational cue, implying repeated calls. But there is no statement of when to use this versus talenthr_list_applicants or talenthr_get_applicant, so the agent must infer the distinction.

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?

readOnlyHint=true already declares the safety profile, so the description's added value is in disclosing the result shape (title, status, location, department, publish date, hiring steps) and that closed positions are included by default. That is meaningful behavioral context absent from annotations, though pagination and ordering are unstated.

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; scope and returned fields come first, and the follow-on hint is placed last where it belongs. Every clause carries 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?

With no output schema and no parameters, the description must carry the return-value burden, and it does by naming the fields returned and the open/closed scope. Gaps remain around pagination, result volume, and whether any filtering exists, which matter for a list tool on a potentially large dataset.

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 takes zero parameters, so the baseline is 4. The description correctly signals there is nothing to supply and instead redirects the 'id' mention to the applicant-listing tool, avoiding confusion about a nonexistent input.

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 a specific verb and resource ('List the company's job positions') plus scope ('open and closed') and enumerates the returned fields, so an agent knows exactly what it gets. It also points at the follow-on tool (list a position's applicants via the id), which partially separates it from talenthr_list_job_position_applicants, though it never names that sibling outright.

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?

Usage is only implied: the tool lists all positions, and the trailing sentence about using the id to list applicants hints at the workflow. There is no explicit when-to-use, when-not, or named alternative such as talenthr_list_job_titles or talenthr_list_job_position_applicants.

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 readOnlyHint annotation already establishes that this is a safe read operation, and the description reinforces the listing behavior. However, it does not add details such as pagination, ordering, or return shape beyond saying all job titles are returned with 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 a single front-loaded sentence with no wasted wording. The parenthetical earns its place by explaining the downstream use of the returned ids.

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 tool with no output schema, the description is nearly complete: it states what is listed and what the ids are used for. Minor omissions around ordering or pagination are unlikely to matter for this simple lookup.

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 baseline is 4. The description adds useful semantics about the returned ids, even though there are no input parameters to explain.

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 and resource ("List all job titles") and defines the company scope. It also clarifies the practical meaning of the returned ids by connecting them to talenthr_list_employees, which helps distinguish this list tool from sibling list tools such as list_job_positions and list_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 parenthetical gives clear usage context: the ids are what talenthr_list_employees filters and employee records refer to. That effectively tells an agent why and when to call this tool before filtering employees, though it does not state explicit exclusions or alternatives.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower, and the description still adds real value by disclosing the shape of the result (address, remote flag, ids) even though no output schema exists. It does not mention pagination, ordering, or whether all locations are returned unconditionally, which keeps it short of a 5.

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 sentence with the resource stated first and the qualifier nested afterwards; no waste. The nested parenthetical is slightly dense but carries two distinct pieces of information (returned fields and a downstream dependency).

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 tool with no output schema, the description covers what is listed, what fields come back, and how the ids are consumed elsewhere. The only gap is result-set size or ordering behavior, which is minor here.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. Nothing in the description misrepresents the empty input 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?

States a specific verb and resource ('List all locations') and adds scope detail (address, remote flag, ids) that tells an agent exactly what comes back. It is clearly distinguishable from sibling list tools such as talenthr_list_departments or talenthr_list_divisions, though it never names 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?

The parenthetical note that these ids are what talenthr_list_employees filters on implies the main use case (fetch ids before filtering employees), which is genuinely useful context. However, it is framed as a fact about the data rather than explicit guidance ('use this when...'), and no alternatives or exclusions are stated.

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?

readOnlyHint=true already covers the safety profile, and the description adds the concrete return payload (id, yearly budget, approval flag, paid flag), which is valuable because there is no output schema. It omits ordering, completeness, or tenant-scope 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?

Two sentences, zero filler: the first defines the content and shape of the result, the second states the dependency on the create tool. Front-loaded and immediately actionable.

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 and no parameters, the description carries the full burden of explaining what comes back, and it does so by naming all four returned attributes plus the key relationship to talenthr_create_time_off_request.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond confirming this is an unfiltered list.

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 a specific verb (List) and resource (time off types), enumerates examples (vacation, sick leave) and the fields returned, so an agent can distinguish this from list_time_off_requests or get_time_off_report without opening a 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?

Explicitly frames the downstream use: the returned id is required for talenthr_create_time_off_request, which tells the agent when to call this first. It does not name exclusions or alternatives (e.g. get_employee_time_off_budgets), so it falls short of a full 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?

readOnlyHint already covers safety, and the description adds genuinely new behavioral context: an authorization prerequisite ('key whose user may see everyone's time tracking') and pagination semantics with next_offset. It stops short of describing page-size defaults or ordering behavior, but the critical access constraint is disclosed.

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 short sentences, front-loaded with what is returned and the cross-employee scope, then paging, then the running-timer toggle and the permission requirement. Every sentence carries distinct information, including the field list which substitutes for a missing output schema.

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 10-parameter, filter-heavy list tool with no output schema, the description covers return shape, paging, default period, the running-timer special case and the permission gate. Gaps are minor: the free-text 'search' parameter and the sort/order interplay are left entirely to the schema.

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 90%, so the schema already documents period, working_now, dates, paging and sorting. The description restates working_now and the period range without adding new syntax or constraints, so it lands at the baseline for well-documented schemas.

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 a specific verb (List) and resource (time tracking entries) plus the scope that matters most: across all employees, with the returned fields (start, end, duration, tags) named inline. No sibling tool lists time tracking entries, so scope language is enough to place it unambiguously in the toolset.

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?

Gives concrete selection guidance inside the tool: 'working_now=true lists only running timers', 'Paged: use next_offset to continue', and period-with-default vs explicit date range. It does not name a sibling alternative or state when not to use it (e.g. vs. calendar/report tools), which keeps it below 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?

Goes well beyond the annotations (destructive/non-idempotent already declared) by disclosing the real-world side effect that the employee is automatically e-mailed the decision, and the state rule that an already-answered or canceled request cannot be answered again. That e-mail side effect and the terminal-state constraint are exactly the facts an agent needs before committing a destructive write.

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, all front-loaded: action and flag mapping first, then side effects/constraints, then the usage guardrail. No filler, and the most decision-relevant facts (WRITE, e-mail, already-answered restriction) appear before the routing hints.

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 3-required-parameter destructive tool with no output schema, the description covers action semantics, irreversibility signals, terminal-state behavior, id sourcing, and the confirmation requirement. Nothing an agent needs to call it safely and 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 schema already documents accept=true/false plus both id parameters, so the description's accept mapping is redundant. It adds no format or provenance detail for employee_id and time_off_request_id beyond naming the sibling tools that produce those ids, which is standard baseline when the schema carries the 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?

Opens with an explicit mutation marker (WRITE) and names both the verb and the resource: approve/reject a pending time off request, with the accept flag mapping spelled out. Clearly distinct from the sibling talenthr_create_time_off_request, which creates rather than answers a request.

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?

States the precondition explicitly ('Only do this when the user explicitly asked for that decision on that request') and routes id discovery to the two concrete alternatives, talenthr_list_employee_time_off_requests and talenthr_get_calendar. No inference needed about when to call this versus the list tools.

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