TeamPredict HR Calculators

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: the counting convention ('the start date itself is not counted; day 1 is the next business day'), the exact holiday set (11 US federal holidays with observed dates), and the supported year range 2000–2100. These are the details that actually determine whether a call returns the expected date.

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 core definition, then use cases, then sibling routing, then edge-case semantics. Every sentence carries distinct information; nothing restates the title or the 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 read-only date calculator with an output schema, an agent needs purpose, counting convention, holiday behavior, and bounds — all present. Return values need not be described since an output schema exists.

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 parameter documentation is already complete and a 3 is the floor. The description adds interpretive value by clarifying the 'after (or before)' meaning of direction, the optionality of holiday skipping, and the non-obvious off-by-one counting rule for business_days.

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 ('Find the date that is a given number of business days after (or before) a start date') and immediately pins the scope with 'skipping weekends and optionally US federal holidays'. It is trivially separable from business_days_between and add_to_date, which it names 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?

Gives concrete use cases ('due date 10 business days from now', delivery dates, deadlines, notice periods) and explicitly routes the agent elsewhere: business_days_between for counting between two known dates, add_to_date for calendar-year/month/week/day arithmetic. When-to-use and when-not-to-use are both covered with named 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?

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely valuable semantics beyond them: days shift the calendar date and preserve clock time while hours/minutes count real elapsed time, so DST transitions inside the span are handled correctly. It does not cover range limits or error behavior, 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?

Three sentences, front-loaded with the action and result, then the semantic rule, then the routing alternatives. No filler and nothing repeated from the 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?

Annotations carry the safety profile, an output schema exists so return format need not be described, and all seven parameters are documented in the schema. What remains for the description — the DST/calendar-day semantics and sibling routing — is exactly what it covers.

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 and the schema already defines each parameter. The description nonetheless adds meaning the schema does not: the days-versus-hours semantic distinction and the consequence of the time_zone parameter (real elapsed vs. plain 24-hour days).

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+resource: move a date and clock time forward or back by days, hours and minutes, and return the result. It immediately scopes itself to US time zones, which separates it from any generic date-arithmetic 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?

Names three alternatives (time_duration_between, add_to_date, convert_time_zone) and the exact condition that selects each. An agent can route without opening any 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?

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the description rightly spends its words on non-obvious behavior instead: calendar-first application order and the month-end clamping rule ('Jan 31 plus one month is the last day of February'), plus the supported year range 2000-2100. The clamping rule is exactly the kind of edge case that silently changes results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, front-loaded with purpose, then edge-case rule, then sibling routing, then validity bound. No sentence is filler and nothing important is 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?

Output schema exists, so the description need not enumerate return fields; it nonetheless names them in passing. Between the use cases, arithmetic ordering rule, sibling alternatives and validity range, an agent has everything needed to call this 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%, so the baseline is 3; the description adds meaning by framing all four magnitude parameters as operating under a single add/subtract polarity, which explains why direction exists alongside non-negative amounts. It does not restate per-parameter ranges or the YYYY-MM-DD format, but the schema already covers those fully.

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 ('add or subtract years, months, weeks and days to or from a calendar date') with the exact output ('resulting date with its weekday, ISO week and day of the year'). It is unmistakable against siblings like add_time_to_datetime and days_between_dates.

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 use cases ('90 days from today', contract end dates, probation periods, anniversaries) and explicitly routes elsewhere: add_business_days for skipping weekends/holidays, days_between_dates for measuring a gap. When-to-use and when-not-to-use are both present.

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 readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuinely non-obvious behavior: exactly which 11 holidays are skipped, that observed dates are used for weekend holidays, that company/state holidays are excluded, and the supported year range — none of which is in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five tight sentences, front-loaded with the core verb and scope, then routing, then the holiday caveat and year bounds. Nothing repeats the schema 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 date arithmetic tool with an output schema, 100% parameter coverage and full annotations, the description closes the remaining gaps an agent would care about: sibling disambiguation, holiday dataset scope, and valid year range.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description still adds meaning beyond the schema by defining what 'skipping US federal holidays' concretely means (11 holidays, observed dates), which directly clarifies the skip_us_federal_holidays flag rather than restating it.

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 ('Count the business days ... between two dates') plus the default holiday rule in the same sentence. It explicitly separates itself from add_business_days and days_between_dates, so the agent can pick it without opening schemas.

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 use cases (notice periods, delivery windows, payroll runs, lead times) and names both alternatives with the condition that selects them (N business days from a start date vs. plain calendar days). It also bounds the tool: US federal holidays only, years 2000–2100.

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 readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered. The description adds behavior annotations don't: DST is resolved for the specific date, and the tool returns an overlap window in addition to conversions. It does not describe how out-of-range or DST-ambiguous times are handled, which keeps it below 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 sentences, front-loaded with the primary operation and ending with the sibling exclusion. The middle sentence's example list slightly overlaps the first sentence's use-case 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?

With an output schema present, return values need not be explained, and scope limits (24 zones, 1–12 targets) are stated. Remaining gap is DST edge-case handling for ambiguous/nonexistent local times, which matters for a date-sensitive converter.

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%, including formats and the enum list, so the baseline is 3. The description only points to the schema for zone ids and mentions the 24-zone limit; it adds no format, default, or semantics beyond 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?

States a concrete verb and resource ('convert one date and clock time from a source time zone to other time zones') and adds a non-obvious secondary capability (finding the 9 AM–5 PM overlap window). It also names the sibling it is not (time_duration_between), so an agent can distinguish 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 use cases ('schedule across offices', 'pick a meeting time for a distributed team', the 3 PM Eastern in London example) and an explicit exclusion routing duration questions to time_duration_between. When-to-use and when-not-to-use are both present.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description does not need to cover safety. It adds useful behavioral context by explaining that every cost line is optional, defaults to the calculator's default, and can be excluded by setting it to 0.

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, then gives usage boundaries and alternatives in two compact sentences. The cost component list and default handling are useful and earn their place without excess.

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 output schema exists, return values need not be described. For an 8-parameter estimation tool, the description covers purpose, scope, alternatives, and optional parameter handling well enough for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter and its default. The description adds practical semantics beyond the schema: cost lines are optional and setting one to 0 omits that line from the estimate.

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: estimating the total cost of one bad hire, and lists the cost components included. It explicitly distinguishes itself from employee_turnover_cost and severance_pay, so an agent can select it without opening schemas.

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 explicit when-to-use guidance: a single failed hire with known salary and tenure. It also names two sibling tools and explains when to use them instead, covering both the primary use case and the main 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the supported year range 2000–2100 and describes what the result breaks down into, which is useful. However, the swap-when-end-before-start behavior lives only in the schema, and no further runtime behavior (e.g., how partial weeks/months are rounded in the breakdown) 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?

Three sentences, front-loaded with the core operation and with zero filler; the year-range constraint is tucked at the end but remains visible. The only weakness is that the routing sentence is dense and could be split, but no sentence 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?

With an output schema present and rich annotations, the description only needs to cover scope, alternatives, and constraints — and it does all three, including the 2000–2100 validity window that would otherwise be an undocumented failure mode. Nothing an agent needs in order to call this 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 description coverage is 100%, including the swap semantics for end_date and the include_end_date increment, so the schema carries the parameter burden. The description's only added semantic is the contrast between calendar days and business days, which is helpful framing but not parameter-level detail. 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 — count calendar days between two dates — and adds what the result contains (weeks/months/years breakdown plus weekday and weekend counts). This is immediately distinguishable from siblings like time_duration_between, which count clock time rather than calendar days.

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 use cases ('how many days until X', tenure, age of a record, notice periods, countdowns) and then explicitly routes away: business_days_between for excluding weekends/holidays, time_duration_between when clock times matter. Both the when and the when-not are stated with named 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?

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description is free to add domain behavior. It does: it enumerates the returned metrics and explains the non-obvious property that retention and turnover need not sum to 100%. Slightly reduced because an output schema exists, making the return-value enumeration partially redundant.

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, no filler, and the differentiating mechanism is front-loaded ahead of the alternative routing. Every sentence carries a distinct job: what it does, when to use it, what to use instead.

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 4-param pure-calculation tool with a full output schema and complete annotations, the description covers purpose, routing, and the key conceptual subtlety. Minor gap: it does not reinforce the schema constraints (leavers cannot exceed the corresponding headcount/new-hire totals), though the schema states them.

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 each parameter is documented in the schema, so the baseline is 3. The description still adds conceptual meaning beyond the schema by explaining why the leaver count is split into two inputs, which helps an agent populate them correctly rather than guessing at a single total.

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 ('Calculate the employee retention rate exactly') and immediately pins down the defining mechanism: separating leavers from the starting group vs. leavers hired during the period. It names the sibling employee_turnover_rate and the condition that distinguishes the two, so an agent can route 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?

Explicit when-to-use ('when you can tell those two groups of leavers apart') paired with an explicit when-not plus named alternative ('Use employee_turnover_rate instead when you only have one total for people who left'). This is textbook alternative 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it frames the result as an estimate, describes the savings calculation, names the default replacement-cost assumption implicitly, and cites the underlying formula source. Return formatting is left to the output schema.

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 front-loaded with the core purpose and follows with usage and alternatives in a logical order. It is slightly longer than strictly necessary because the return-value sentence partially duplicates the output schema, but no sentence is redundant or confusing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, rich input schema, output schema, and safety annotations, the description is complete. It covers purpose, usage conditions, alternatives, savings semantics, and formula provenance, leaving no critical gap for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters and their defaults/ranges are already documented in the schema. The description reinforces the input concepts (headcount, average salary, annual turnover rate) and explains that the savings figure comes from a given cut in turnover, but it does not add syntax or constraints beyond what the schema already 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 and resource ("Estimate what employee turnover costs a company per year") and explicitly distinguishes itself from employee_turnover_rate and cost_of_a_bad_hire. An agent can identify this tool's role without opening any 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?

It states the exact conditions for use ("when you know headcount, average salary and the annual turnover rate and want the dollar cost") and names the two sibling alternatives with their respective purposes. This is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is behavioral detail. It adds real value by disclosing the annualization behavior and summarizing the computed outputs, though it doesn't state assumptions or edge cases (e.g. zero starting headcount) for a calculation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: what it computes first, then when to use, then which siblings to prefer. Front-loaded and free of padding.

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 an output schema present, return values needn't be explained in depth, and the description still summarizes them. Full schema coverage, explicit alternatives, and documented annualization make the definition complete for a four-parameter calculator.

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 already documents its meaning and bounds, so the baseline is 3. The description names the inputs but adds no format or interpretation detail 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?

States a specific verb and resource ('Calculate the employee turnover (attrition) rate') plus the scope (month/quarter/year) and the exact inputs used. It also differentiates itself from two named siblings, so an agent can pick it 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 an explicit when-to-use ('when you have headcounts and separations and need the rate') and names two concrete alternatives with the conditions that select them: employee_retention_rate for split leaver data, employee_turnover_cost for dollar costing.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the bar is lower; the description adds real context by disclosing the output shape (score, percentages, rule-of-thumb band) and cautioning that the reading is not a universal benchmark. It does not state behavior for a zero-response input (division by zero), which would be the remaining useful disclosure for a computation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the calculation and scope, then the usage condition. Minor internal redundancy in restating 'eNPS' and the promoter/detractor definition, but 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?

Covers inputs, formula, output range and interpretation caveat for a simple three-integer tool, and an output schema exists so return values needn't be explained. Missing only edge-case handling description (all-zero counts), which keeps it from a 5.

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 already documents its 0-6 / 7-8 / 9-10 bucket, so the baseline is 3. The description restates those same bucket mappings rather than adding new semantics such as whether non-integer or negative counts are rejected.

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 (Calculate) plus the resource (eNPS) and spells out the exact formula (percentage of promoters minus percentage of detractors) and output range (-100 to +100). This clearly distinguishes it from the payroll/date siblings, which involve no survey math.

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 'Use it when you have the count of people who answered 9-10 / 7-8 / 0-6' clause gives explicit triggering conditions, including the exact survey question context. It stops short of stating when NOT to use it (e.g., if you hold raw per-respondent scores rather than counts), so no full alternative 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 establish readOnly/idempotent/non-destructive, and the description goes further by disclosing the actual computation rules (weekly hours over one full-time schedule; IRS 30-hour rule with a 120-hour monthly cap) and the modeling assumption that 'every month looks like the one entered'. That assumption is exactly the kind of caveat an agent needs; only rounding/precision and validation failure behavior are left 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?

Four sentences, front-loaded with the verb and resource, then usage, then method, then return/assumption. No filler and no repetition of schema content.

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?

An output schema exists, so return formatting need not be explained; the description still notes that both counts are returned. Combined with the disclosed formulas and the month-uniformity assumption, an agent has everything needed to invoke this 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%, so the baseline is 3, but the description earns credit above that by explaining the role of full_time_hours_per_week as the FTE divisor and how part-time groups feed the ACA 120-hour cap. It adds conceptual meaning rather than merely restating field names.

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 ('Count full-time equivalent employees') plus a second concrete output (ACA count) and the regulatory threshold it decides. Nothing in the sibling list overlaps with this domain, so an agent can route here without ambiguity.

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?

Names three concrete use cases ('workforce planning, headcount reporting or checking applicable-large-employer status'), which gives clear when-to-use context. It stops short of stating exclusions or naming a sibling alternative for adjacent questions (e.g., hourly_to_salary or overtime_pay).

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile needs no restating. The description adds real context the annotations cannot: the default assumptions (40 hours/week, 52 paid weeks, a 2,080-hour year) and that results are gross pre-tax. It stops short of warning that changing hours_per_week or paid_weeks_per_year makes all figures assumptions rather than facts, but the coverage is solid.

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 conversion scope, then examples, then the assumptions, then the sibling routing – a sensible order with no filler. The example questions are slightly redundant with the first sentence and could be shortened, keeping it just under a 5.

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?

An output schema exists, so return formatting is out of scope for the description. Given five parameters with enum and defaults, the description supplies exactly what is missing: default assumption semantics, gross-vs-net boundary, and tool choice. Nothing an agent needs to invoke it correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the combined effect of hours_per_week and paid_weeks_per_year ('a 2,080-hour year is the default') rather than merely restating each field. days_per_week, the least intuitive parameter, is still only defined in the schema and not touched on in prose.

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 ('Convert pay between hourly, daily, weekly, biweekly, semimonthly, monthly and yearly, in either direction, from one amount') and anchors it with two concrete example questions. This is unmistakably distinct from the sibling payroll tools such as overtime_pay or us_paycheck_take_home.

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 routes the agent: 'Use us_paycheck_take_home for take-home pay after tax and overtime_pay for pay that includes overtime hours.' It names the alternatives and the condition that selects them, and the 'gross, before tax' clause makes the exclusion boundary clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine behavior beyond that: the midnight-wrap rule ('an end at or before the start counts as the next day') and the return shape (hours, minutes, decimal hours). It stops short of error conditions or input validation behavior, which keeps it at 4 rather than 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?

Front-loaded with the purpose, then the midnight rule, then the return, then sibling routing — a sensible order with no filler. The middle sentence is dense but every clause carries information; only the parenthetical example is arguably redundant with the parameter descriptions.

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 two-parameter, read-only calculation tool with an output schema and full annotation coverage needs exactly this much: purpose, the one ambiguous edge case, the return units, and sibling disambiguation. Nothing an agent needs in order to call 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 both params already explain the 0630 / 06:30 forms, so the baseline is 3. The description adds real meaning on top by spelling out the wraparound interpretation and giving a concrete 2200→0630 example, which is the one semantic an agent could plausibly get wrong.

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 ('find how long a shift or interval lasts between a start and an end in military time') and immediately scopes it with a worked example (2200 to 0630 = 8h30m). It distinguishes itself from military_time_convert and time_duration_between by name, so an agent can route correctly 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 names both alternatives and the exact conditions that select them: military_time_convert for translating a single time, time_duration_between when dates differ or a DST time zone is involved. This is a clean when-to-use / when-not-to-use split.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds value by describing what comes back: every common written form, the plain-English name for midnight/noon, and the chart hour. That last part overlaps somewhat with the existing output schema, keeping it just 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?

Three tightly written sentences, front-loaded with the core conversion and followed by input routing and an alternative. Minor waste in the return-value sentence, which partly restates what the output schema will already show.

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 a simple 4-parameter, zero-required tool with full schema coverage, annotations and an output schema, the description covers purpose, both input paths, accepted formats and sibling routing. Nothing an agent needs to call 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%, so the baseline is 3, but the description adds real meaning: it shows accepted input formats for military_time ('1345, 13:45 or 0800') and reveals that colon-separated and bare forms are both valid, which the schema's maxLength 10 alone does not convey. It also clarifies the either/or relationship between the two input paths.

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 (convert) and resource (military/12-hour time), explicitly bidirectional, and names the sibling it is not (military_shift_hours) with the reason. An agent can distinguish it from the other time tools 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 explicit input paths — 'Give military_time ... to get the standard time, or hour_12, minute and period to get the military time' — and explicitly routes the interval use case to military_shift_hours. Both when-to-use and the alternative are spelled out.

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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds that the result is 'gross before tax' and enumerates the returned components (regular and overtime hours and pay plus the week's total), which pre-empts the most likely misunderstanding about net vs. gross. It stops short of stating error behavior (e.g. what happens if hours_worked is supplied with california), so it is not a full 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 sentences in a deliberate order: what it computes, how to invoke each rule set, then where to go for related work. No filler and no repetition of the enum values or numeric bounds already in the 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?

An output schema and rich annotations exist, so the description need not restate return shapes, yet it still front-loads the gross-before-tax caveat. The subtle California seventh-consecutive-day condition and the double-time-over-12 threshold are both surfaced, which is the main correctness risk in this tool.

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 cross-parameter routing semantics the schema only states piecemeal: it explains that extra_pay_usd is pay that 'counts toward the regular rate, such as a nondiscretionary bonus', which conveys the legal concept rather than just the type. It also reinforces that daily_hours is a seven-entry per-day breakdown for the California path.

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 ('Calculate a week of overtime pay') plus the two governing rule regimes (federal FLSA over-40 weekly, California daily/eighth-day/seventh-day/double-time). The scope is precise enough that the agent can distinguish it from payroll-adjacent siblings without opening any 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 maps each rule_set to the inputs it requires ('rule_set federal with total hours worked... use rule_set california with the hours worked on each of the seven days'). It also names two alternatives and the condition selecting them: us_paycheck_take_home with overtime_hours_per_week for take-home pay, hourly_to_salary for pay without overtime.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: accrual pauses at the cap and resumes after time is used, which affects how projections should be interpreted. It stops short of stating other modeling assumptions (e.g. how starting_balance_hours interacts with hours_used_this_year), keeping it below 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?

The capability statement is front-loaded in the first sentence, followed by use cases and then the alternative-tool routing, so the most important content comes first. The opening sentence is long and packs three output dimensions plus the balance, but nothing is truly 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 an output schema present, the description need not explain return values, and it covers purpose, use cases, cap behavior and sibling routing. Only the interaction between starting balance, hours used and period count is left implicit, a minor gap for a 9-parameter pure-calculation tool.

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 every parameter is already documented in the schema, establishing a baseline of 3. The description only reiterates the optional cap and hours-already-used inputs without adding format, interaction or defaulting guidance beyond what the schema says.

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 computation ('how paid time off accrues') and enumerates exactly what is produced: hours per pay period, per month, per hour worked, plus balance after each period. It explicitly contrasts with the pay-related siblings, so an agent can distinguish it from hourly_to_salary or overtime_pay 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?

It gives two concrete use cases ('design or explain a PTO policy', 'project an employee's balance by year end') and an explicit exclusion routing pay questions to hourly_to_salary or salary_increase. When-to-use, when-not-to-use, and the alternatives are all 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 already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful behavioral context not in the annotations: results are pre-tax, and the tool cross-checks the raise against inflation. It does not discuss default assumptions for hours_per_week or inflation (those live in the schema), so it stops 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?

Front-loaded with what is computed, then the input contract, then the sibling routing rules, then a closing scope caveat. Three sentences, every clause carrying distinct information, with no filler or restated 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?

Output schema exists, so return values needn't be specified, and annotations carry the safety profile; the description fills the remaining gaps (pre-tax scope, mutually exclusive inputs, unit handling, sibling routing). Nothing an agent needs in order 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 description coverage is 100%, so the baseline is 3. The description restates the raise_percent/new_pay mutual exclusivity, but the schema already documents that on both properties ('Give this or raise_percent' / 'Give this or new_pay'), so it adds little beyond the schema except linking pay_unit to the units of both amounts.

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 ('Calculate a pay raise') and enumerates exactly what it returns: new annual/hourly pay, raise per year/month/biweekly, raise percentage, and inflation comparison. It also names the sibling tools it is not (hourly_to_salary, us_paycheck_take_home), so an agent can disambiguate without opening any 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 input-selection rules ('Give either raise_percent ... or new_pay') and explicit exclusions with the alternative named for each: hourly_to_salary for period conversion without a raise, us_paycheck_take_home for after-tax pay. The 'all amounts are before tax' note further scopes when this tool is 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: results are pre-tax, and the min/max interplay ('if below the minimum, the cap wins' via schema) is clarified. Return format is handled by the output schema, so the remaining gap is minor.

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 core operation and formula are front-loaded in the first sentence, followed by usage and then the alternative-tool routing. Dense but nearly every sentence earns its place; only the long first sentence is slightly heavy.

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 9-parameter calculation tool with an output schema and full safety annotations, the description is complete: it gives the formula, usage framing, the pre-tax caveat, and sibling disambiguation. Nothing an agent needs to call 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%, so parameters are fully documented already (baseline 3). The description nonetheless reinforces the calculation semantics (weekly pay, per-year-of-service multiplier, optional min/max, PTO payout) and the pre-tax caveat, adding slight value over 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 ('Estimate a severance package') and spells out the exact formula (weeks per year × years × weekly pay, plus PTO, health, lump sums). It also names the sibling it is not (cost_of_a_bad_hire), so an agent can distinguish it without opening schemas.

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 gives both personas/use cases ('employer budgeting an exit or an employee checking an offer') and routes the alternative scenario to cost_of_a_bad_hire. It also explains that inputs come from the plan's terms because no federal formula exists, which frames correct usage.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine non-schema behavior: that daylight saving transitions are accounted for so the real elapsed hour is counted, and that output granularity is days/hours/minutes rather than a raw timestamp. It does not mention limits on span size or handling of an end before start, 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?

Three sentences, each earning its place: purpose first, then use cases, then sibling routing. No filler and the core definition is front-loaded ahead of the disambiguation.

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 an output schema present, return-value detail is unnecessary, and annotations cover the safety profile while the schema fully documents all five parameters. The description supplies the remaining DST and granularity context an agent needs to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including the format patterns and an explicit explanation of the time_zone enum and the 'none' option, so the schema already does the heavy lifting and the baseline is 3. The description adds only that the times are read in a US zone with DST adjustment, which largely restates the time_zone schema text; it says nothing extra about how start_date/start_time pair together.

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-plus-resource statement: it computes elapsed time between a start and an end date-time, returned in days, hours and minutes, and it flags DST-awareness. An agent can distinguish it immediately from siblings like days_between_dates or add_time_to_datetime without opening any 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?

It gives concrete scenarios (shift lengths crossing midnight, ticket elapsed time, on-call windows, billing) and then explicitly routes three named alternatives with the condition that selects each. This is the when-to-use / when-not-to-use pattern in full.

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine domain behavior beyond that: withholding is not the final tax liability, the 37% threshold above $1 million in annual supplemental pay, and that a separately-paid bonus additionally returns the result under the other federal method for comparison. It does not discuss edge cases like zero-salary or state-specific exceptions, keeping it at 4 rather than 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?

Front-loaded with the core computation and expected result, then caveats, then alternatives — a sensible ordering with no filler sentences. It is dense but each clause carries information; only the closing comparison note feels slightly tacked on.

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 9-parameter calculator with full schema coverage, an output schema, and complete annotations, the description supplies the remaining context an agent needs: scope (50 states + DC), the domain caveat that withholding ≠ final tax, and sibling disambiguation. Nothing required to select or 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?

With 100% schema description coverage the baseline is 3, but the description adds substantive meaning that the schema only implies: it explains the two federal methods and the interaction with the $1M/37% cap, which maps directly to federal_method and earlier_supplemental_pay. It does not elaborate on filing_status, pay_frequency, or w4_step2_checkbox, so it stops short of 5.

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?

Starts with a specific verb and resource ('Calculate how much tax is withheld from a US bonus in 2026 and what is left') and enumerates exactly which components are computed: federal (flat 22% or combined, 37% above $1M), Social Security, Medicare, and state bonus rules. This is unmistakably distinct from siblings like us_paycheck_take_home or overtime_pay.

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 a literal user-phrasing trigger ('how much of my $X bonus will I keep in <state>?') plus explicit routing: use us_paycheck_take_home for regular pay, salary_increase for a raise. When-to-use, when-not-to-use and alternatives are all present.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered; the description adds real value by disclosing that it returns full-year totals and employer-side cost, and by enumerating the payroll contributions modeled (federal, FICA, state income tax, state payroll contributions). It does not discuss precision/rounding or edge-case behavior, keeping 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?

Front-loaded with the verb and scope, then usage exemplars, then exclusions, then assumptions — a sensible order with no filler. The final assumption sentence is long and packs several constraints, but each carries information an agent needs.

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 19-parameter calculator with an output schema and full annotation coverage, the description covers purpose, honest usage boundaries, sibling disambiguation, and the modeling assumptions. Nothing needed to decide whether to call it and interpret the result 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 description coverage is 100%, so all 19 parameters are already documented in the schema, and the description names no individual parameter. It does add framing that ties the w4_* inputs to Form W-4 and mentions state payroll contributions, but it gives no syntax, ranges, or default guidance 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?

States a specific verb and resource ('Calculate US take-home (net) pay') plus scope: 2026, salary or hourly, all 50 states or DC, and the exact taxes included. The sibling alternatives named later make the boundary between this and us_bonus_tax / overtime_pay / hourly_to_salary 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 concrete selection contexts ('how much will I take home on $X in <state>?', comparing states, pricing an offer) and explicitly routes three sibling cases elsewhere: bonus withholding, pre-tax overtime pay, and pure pay-period conversion. Also states the modeling assumptions (one job, standard W-4, 2026 withholding method) that must hold for the result to be valid.

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