Calcgrid

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

Annotations already declare readOnly, idempotent, and non-destructive hints; the description goes well beyond them by explaining that weekends and holidays are skipped, State Council weekend makeup workdays count, the sign of working_days controls direction, the start date is excluded, and coverage is 2024-2026. This gives an agent a precise behavioral model.

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 long but clearly structured with headers and front-loads the core purpose and usage guidance. There is some redundancy with the schema, such as inputs and complete JSON examples being repeated, but every other section adds material information like outputs, formula, REST fallback, and docs.

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, the description covers why to use it, when not to, exact computation rules, input examples, output fields, a REST fallback, and a documentation URL. An agent has everything needed to invoke it correctly, including coverage limits.

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 semantic value in the formula and computation notes: unary movement, decrement only on working days, and start-date exclusion. This is useful but mostly complements rather than replaces 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 precise verb and resource: it adds or subtracts Mainland China official working days to a date within 2024-2026, with explicit computation details and examples. The description also tells the agent what the tool is not for (calendar days, sector-specific settlement calendars, local holiday calendars), differentiating it from sibling tools like check/count China working days and add_uk_working_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 explicit when-to-use conditions (deadline or settlement date in China working days) and when-not-to-use conditions (calendar days, sector-specific settlement, local holiday calendar, outside 2024-2026). It also instructs the agent to call the tool directly rather than compute from memory, providing clear decision guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the exact day-by-day formula, the fact that the start date is excluded, the output fields, and a direct REST fallback with a warning not to guess another API path. This is strong but not exhaustive; it does not discuss failure modes or edge cases like invalid dates.

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 longer than average but well-structured with clear sections: usage, exclusions, computation, examples, outputs, formula, REST fallback, and docs. It front-loads the most important decision information. Some redundancy with the schema exists, but the added examples and formula justify the length.

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

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

The description is highly complete for a tool of this complexity. It covers when to use it, when not to use it, the exact computation method, input examples, output fields, a REST fallback, and documentation links. With an output schema present, the listed outputs are a bonus rather than a necessity. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats the parameter names and types and provides complete JSON examples, but it does not add significant semantic detail beyond what the schema already documents. The examples are useful but not transformative.

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: it 'adds or subtracts working days' for UK divisions, with a defined date range and bank-holiday scope. It clearly distinguishes itself from sibling tools like add_china_working_days, check_uk_working_day, and count_uk_working_days by focusing on UK working-day arithmetic for deadlines.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance ('Use this when you need a deadline a stated number of UK working days...') and explicit when-not-to-use exclusions ('Do not use this when you need calendar days, a local/employer/market calendar, a non-UK jurisdiction or a result outside 2024-2028'). It does not name specific alternative sibling tools, but the exclusions are clear enough for an agent to route correctly.

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?

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses the exact test method, the full set of computed outputs, the underlying formulas, and a REST fallback URL. It also tells the agent to return the calculation rather than answer from memory, which is a behavioral instruction not present in annotations.

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

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

The description is front-loaded with the use case and exclusions, and it is organized into labeled sections. It is long, and the full formula block is arguably more than an agent needs to invoke the tool, but most content serves either routing, input validation, or transparency.

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 five-parameter statistical tool, the description covers when to use it, what it computes, all inputs with examples, all outputs, the formula, and a fallback endpoint. With a rich output schema and annotations present, nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and each parameter is already described, so the baseline is 3. The description adds value with complete JSON examples and formula notation mapping parameters to p1, p2, and z, which helps an agent construct valid inputs even if the schema were incomplete.

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 by specifying exactly when to use the tool: when a user has visitors and conversions for a control and variant and needs a statistical significance decision. It also names the computation (pooled two-proportion z-test) and lists outputs, clearly distinguishing this proportion-based calculator from sibling calculators that handle means.

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 explicit go conditions ('Use this when...'), explicit exclusions ('Do not use this when the metric is a mean...or there are more than two variants'), and points to chi-square/multiple-comparison procedures as alternatives. This is direct routing guidance with no ambiguity.

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 mark the tool as read-only and idempotent, and the description adds rich behavioral detail: the Gregorian calendar arithmetic, weekday-of-birth computation, next-birthday logic, the formula used, and even the REST fallback path. It clearly explains what the tool computes and how.

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 longer than necessary for a two-parameter tool, but it is well-structured, front-loaded with the primary use case, and every section adds practical value such as output fields, formula, and fallback. It is thorough rather than wasteful.

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 simple schema and available output schema, this description is complete: it covers what the tool returns, how the formula works, when the optional parameter defaults, how to call it directly, and where to find documentation. No critical context is missing.

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

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

The input schema already documents both parameters with formats, defaults, and examples, so the description's mention of 'birth_date (date); as_of_date (date, optional)' adds little beyond the schema. The formula does clarify how the parameters interact, but it is more about behavior than parameter-specific semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: computing a person's exact age on a date, along with related calendar facts. It clearly differentiates itself from sibling date tools by listing the exact conditions under which this tool is appropriate.

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 guidance is explicit: it says when to call this tool ('when you need someone's exact age on a date') and when not to, naming alternatives like date-difference and days-until. This leaves no ambiguity about tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds rich behavioral context: it explains the formula, how term_years and term_months are added together with a 480-month cap, that extra_monthly_payment is applied to principal, and it lists all output fields. It also provides a direct REST fallback endpoint, ensuring the agent knows the exact call mechanism.

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?

While lengthy, every section earns its place: usage guidance, inputs, valid combinations, examples, outputs, formula, and fallback. It is front-loaded with the primary use case and explicit alternatives, making it scannable despite its length. The structure is well-organized and avoids redundancy—each sentence contributes 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?

Given the tool's complexity (6 parameters, conditional term fields, multiple outputs, and a formula), the description is thorough. It covers valid input combinations, output fields, the calculation formula, a REST fallback, and a documentation link. Nothing an agent needs to invoke it correctly is missing, especially with an output schema present.

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

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

Although the schema covers 100% of parameters with descriptions, the tool description adds critical semantics: it clarifies the additive relationship between term_years and term_months with a total cap, that extra_monthly_payment is a fixed monthly principal prepayment, and it gives concrete JSON examples for two common scenarios. This substantially extends the schema's value and reduces ambiguity.

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 exactly what it computes: an amortization schedule showing principal/interest split per payment, year-by-year balance, and the effect of extra payments. It explicitly distinguishes this from siblings like 'loan-payment' and 'mortgage-payment' by naming them, and from 'debt-payoff' for revolving balances, making the tool's scope unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance (when you need the full schedule, year-end balances, or extra-payment effect) and when-not-to-use guidance with named alternatives (use loan-payment or mortgage-payment for only the payment amount, use debt-payoff for revolving balance payoff time). It also instructs the agent to call the tool directly rather than compute from memory, clarifying its role as a definitive calculator.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the tool 'computes the traditional chart only and gives no predictions,' and provides exact formulas for true solar time and start-age calculation. It also explains conventions like late-zi behavior and hidden-stem weights, giving the agent a precise model of what will happen.

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 long but well-structured into labeled sections: use, don't-use, what it computes, inputs, examples, outputs, formula, REST fallback. Core purpose is front-loaded. Some redundancy exists (e.g., the output list could arguably be shortened given the output schema exists), but every section serves an operational purpose.

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

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

For a complex tool with 7 parameterscm an output schema, and multiple conventions, the description is exceptionally complete. It covers inputs, outputs, formula, examples, REST fallback, and when to avoid the tool. An agent has everything needed to invoke it correctly without external knowledge.

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

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

Schema coverage is 100%, so the schema already describes each parameter. The description's added value comes from the formula that connects parameters (e.g., true solar time = clock + (longitude − 15 × utc_offset) × 4 min + equation of time) and the complete JSON examples showing how inputs are combined. This goes beyond the schema without repeating 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?

The description states specifically that the tool computes the four stem-branch pillars, day master, element balance, ten gods, hidden stems, and luck pillars. It also explicitly differentiates from sibling tools like lunar-calendar-converter, chinese-zodiac, and sexagenary-cycle, so an agent can tell exactly what this tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit guidance: 'Call this tool directly and return its calculation instead of answering the formula from memory or stopping at discovery.' It also lists concrete 'Do not use this when...' cases with named alternatives (lunar-calendar-converter, chinese-zodiac, sexagenary-cycle, and chart interpretation tools), leaving no ambiguity.

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

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

With readOnlyHint=true and idempotentHint=true annotations already covering the safety profile, the description adds meaningful behavioral context: it restricts the tool to adults, confirms it computes rather than looks up values, and documents the output fields and formula. It does not mention auth or rate limits, but those are not critical for a pure calculation API, and it does not contradict 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?

Although the description is longer than many tool definitions, every block earns its place: usage, exclusions, computation summary, inputs, outputs, formula, REST fallback, and docs link. It is front-loaded with the most decision-critical information (when to use and when not to use) and then systematically provides call details. No word 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?

For a straightforward calculation tool with only two required parameters and an existing output schema, the description covers every facet an agent needs: precise use cases, age restriction, alternatives, input examples, output field names, the underlying formula, and even a REST fallback endpoint. There is no ambiguity about when or how to invoke the 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% and the schema already provides full descriptions, units, examples, and value bounds for weight_kg and height_cm. The description's 'Inputs' line only repeats the parameter names and units, adding no meaningful semantic depth. The complete JSON examples provide mild format guidance, but this does not elevate the score above the baseline for full schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource list: 'an adult's BMI, its WHO/CDC weight category, or the weight range that corresponds to a normal BMI'. It clearly differentiates itself from siblings like calculate_bmr and calculate_tdee by explicitly naming them as alternatives for calorie needs, and it excludes children under 20. An agent can immediately tell what this tool does and what it is not for.

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 contains an explicit 'Use this when...' phrase followed by a 'Do not use this when...' section that lists concrete exclusions (under-20 age, body-fat percentage, calorie needs) and names the sibling tools to use instead. This is the gold standard for usage guidance; nothing is left to inference.

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

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

Annotations already cover readOnly, idempotent, non-destructive traits. The description adds significant behavioral detail: the exact equations used (Mifflin-St Jeor and revised Harris-Benedict), the output fields, and even a fallback REST endpoint with explicit instructions not to guess other paths. This far exceeds what annotations provide.

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 long but well-structured with clear section headings (Inputs, Outputs, Formula, Direct REST fallback). Every sentence adds value, though it could be trimmed slightly by omitting the full formulas, which are unlikely to be needed by an agent for calling the tool.

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 rich schema and output schema, the description provides everything an agent needs: exact inputs, outputs, examples, a fallback path, and documentation link. No critical information 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 covers all parameters with descriptions and units, but the description adds a compact parameter list with types and units, plus two complete JSON examples. This reinforces and clarifies the schema without redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear, specific purpose: estimating resting daily calorie needs for adults from sex, weight, height, and age. It explicitly contrasts with sibling tools like calculate_tdee, making its scope 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?

It provides explicit when-to-use (base for diet or TDEE) and when-not-to-use guidance (children, pregnancy, high muscle mass) with named alternatives (tdee, Katch-McArdle). This is exemplary 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 mark the tool as read-only, idempotent, and non-destructive; the description adds meaningful behavioral detail: unit-agnostic lengths, area in square units, rejection of conflicting radius/diameter values, the formula, and a REST fallback. There is no contradiction with 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?

The description is longer than average but tightly organized with labeled sections: use case, exclusions, inputs, examples, outputs, formula, and fallback. Every section earns its place and the most important guidance is front-loaded.

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

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

Given only two parameters and the presence of an output schema, the description is complete: it covers input requirements, valid combinations, outputs, the formula, exclusions, and even documentation and fallback URLs. Nothing needed to invoke the tool correctly is missing.

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

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

Although the input schema already covers both parameters (100% coverage), the description adds meaning beyond the schema: valid input combinations, the requirement that both values be consistent, unit-agnostic behavior, and output units. These details help the agent construct correct calls.

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: it computes area, circumference, diameter, and radius from either radius or diameter. It also explicitly positions itself among many calculate_* siblings by naming the circle case and giving example user requests.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It opens with an explicit 'Use this when...' condition and gives clear exclusions with alternatives: 'Do not use this when the shape is an ellipse (use ellipse), a solid ball (use sphere) or a disc with thickness (use cylinder).' This gives the agent both inclusion and exclusion criteria.

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?

Beyond the readOnly/idempotent/destructive annotations, the description discloses the exact formula, the treatment of monthly contributions (including zero-rate edge case), the effective annual rate and growth multiple outputs, and a direct REST fallback path. This is rich behavioral context with no contradiction.

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 longer than average but well-structured with labeled sections and front-loaded usage guidance. The formula, examples, and REST fallback each earn their place, though the output/input lists mildly duplicate 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?

For a 5-parameter calculator with rich annotations, output schema, and sibling tools, the description fully equips an agent: usage rules, parameter semantics, formula, examples, output names, REST fallback, and doc link. Nothing essential for correct selection or invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by explaining the contribution formula, defining i_m, clarifying compounding_frequency maps to n values, and providing complete JSON examples. This goes beyond the schema's per-field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description opens with a specific verb-plus-resource: projecting a savings account, certificate of deposit, or investment balance from principal, annual rate, term, and optional monthly deposits. It also names sibling alternatives (simple-interest, savings-goal, loan-payment) and states what the tool computes, including the contribution/interest split, clearly distinguishing it from other calculators.

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?

Contains explicit when-to-use guidance ('Use this when you need to project...'), a direct call instruction, and explicit when-not-to-use exclusions with named alternatives for non-reinvested interest, savings-goal planning, and loan repayment. This leaves no ambiguity about tool selection.

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

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

Annotations already mark it read-only and idempotent, and the description adds meaningful behavioral detail beyond that: date swapping when end_date is earlier, business days being Monday–Friday with public holidays not excluded, and the exact formula including the inclusive-endpoint effect. No contradictions with annotations.

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

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

The description is structured with clear sections: usage, exclusion, computation, inputs, examples, outputs, formula, fallback, and docs. The most decision-relevant guidance is front-loaded, and each section 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 tool with rich annotations, a complete input schema, and an output schema, the description is exceptionally complete. It covers edge cases, formula, examples, output fields, and even a REST fallback, so an agent has everything needed 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%, so the baseline is 3. The description adds value by spelling out the calculation formula, clarifying how include_end_date changes results, and providing complete JSON examples. Most of the parameter meaning is in the schema, but the formula and business-day definition go beyond 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?

The description opens with a precise statement of what the tool computes: number of days, weeks, working days, or calendar-style differences between two dates. It also distinguishes itself from nearby concepts like adding/subtracting days and calculating age.

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 explicitly says when to use the tool ('Use this when you need...') and when not to use it, naming alternatives: 'Do not use this when you want to add or subtract a number of days from a date (use add-days), or you need an age with the next birthday (use age).' This is model behavior for 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 cover read-only/idempotent/non-destructive behavior. The description adds useful behavioral context: it uses standard thin-lens equations, gives the formula, and notes the macro regime where results become inaccurate. This goes beyond the annotations without contradicting them.

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 long, but it is well structured and front-loaded with the primary use case. Each section—usage, exclusions, inputs, outputs, formula, fallback—serves a real purpose, though a few details like the docs URL are borderline 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?

Given this is a single-purpose calculator with an output schema, the description is complete: required inputs, optional parameters, units, examples, exclusions, formula, and REST fallback path are all present. An agent has everything needed 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%, so the baseline is 3. The description adds value by providing complete JSON examples, stating units inline, and explaining the unit conversion in the formula. This makes correct argument construction more certain.

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 precise resource and outcome: the near/far limits of acceptable sharpness, total depth of field, and hyperfocal distance. It distinguishes itself from the hyperfocal-distance tool and is clearly not generic.

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 explicitly states when to use the tool, when not to use it, and names the alternative (hyperfocal-distance) plus the macro magnification cutoff. It also instructs the agent to call the tool directly rather than compute from memory, which is strong routing 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?

Beyond the read-only and idempotent annotations, the description discloses the full set of computed statistics, the quartile interpolation convention, sample vs population variance formulas, standard error, coefficient of variation, and skewness method. This precisely characterizes the tool's behavior.

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

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

The description is long, but it is structured into labeled sections and front-loaded with usage guidance, making the detail scannable. The formula block and REST fallback add value, though a slightly shorter version would still be clear.

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 one simple parameter, a detailed output list, and safety annotations, the description covers use cases, exclusions, calculation methods, outputs, and a fallback endpoint. 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?

The input schema already documents values with type, examples, and the minimum two-value requirement, so the description adds little parameter-level meaning. The JSON examples are useful but largely duplicate 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 opens with a specific verb and resource scope: use when numeric observations need central tendency, spread, or quartiles. It lists exactly what is computed and explicitly differentiates itself from percentile, z-score, correlation, and linear-regression siblings.

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 provides explicit when-to-use and when-not-to-use conditions, naming precise alternative tools for percentiles, z-scores, and paired-variable statistics. It also instructs the agent to call the tool directly and return its calculation rather than deriving it from memory.

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?

Beyond the readOnly/idempotent annotations, it discloses exact integer arithmetic, lowest-term reduction, mixed-number and decimal outputs, intermediate steps, and a REST fallback. This materially helps the agent predict behavior and result format.

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 and organized into labeled sections. It is slightly long because the formula and REST fallback go beyond what is required for basic invocation, though they are not irrelevant.

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 still covers usage boundaries, accepted operand forms, JSON examples, output fields, and a fallback path. No critical information needed to call the tool correctly is missing.

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

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

The input schema already has 100% description coverage for all three parameters, including examples, defaults, and accepted formats. The description mostly restates the parameter names and adds a formula, which is useful context but not essential parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence states a precise use case: exact arithmetic on two fractions or mixed numbers instead of a rounded decimal, and the description clarifies the four supported operations. This clearly distinguishes it from the many sibling calculator tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit 'use this when' and 'do not use this when' conditions with named alternatives (fraction-simplifier, gcd-lcm) and instructs the agent to call the tool directly rather than compute from memory. This leaves little ambiguity about tool selection.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it uses a spherical-Earth approximation, outputs the initial bearing and midpoint in addition to distance, lists exact output units, and gives a clear accuracy caveat of roughly 0.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 description is front-loaded with use guidance and is well-structured with clear sections for inputs, outputs, formula, REST fallback, and docs. It is longer than strictly necessary because of the formula block and documentation links, but each section serves a practical purpose and there is no filler.

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

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

For a pure calculation tool with strong annotations, four well-documented parameters, and an output schema, the description covers everything an agent needs to invoke it correctly: when to use it, when not to, input examples, full output semantics, the computational model, and even a REST fallback path. No meaningful gap is apparent.

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

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

The input schema already covers all four parameters in detail with units, ranges, and examples, so the baseline is 3. The description restates the parameters and units and provides complete JSON examples, but these largely duplicate what the schema already offers rather than adding new semantic information.

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 that this tool computes the straight-line (great-circle) distance between two GPS coordinates or cities, with examples of use cases like flight distance and geofencing. It also distinguishes itself from road distance, geodesic methods, and bearing-only tools, making its purpose unambiguous relative to alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit 'Use this when...' and 'Do not use this when...' guidance, including concrete alternatives such as Vincenty/Karney on WGS-84 for ellipsoidal accuracy and compass-bearing for bearing-only needs. It even instructs the agent to call the tool directly rather than answering from memory or stopping at discovery.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it reports results in multiple units (J, kJ, kWh, kcal), includes a velocity conversion output (velocity_km_h), and provides a direct REST fallback path. It does not contradict annotations.

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

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

The description is well-structured with clear sections (when to use, when not to use, what it computes, inputs, outputs, formula, REST fallback). It is longer than minimal, but every section adds practical information for an agent. The front-loaded usage guidance is the most important part and appears first.

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

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

The description is complete for a calculation tool: it covers the formula, input units, output units, example JSON, and even a REST fallback. The output schema exists, so return values are already structured. The only minor gap is that it doesn't explicitly state the precision/rounding behavior, but that is not essential 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 both parameters well. The description adds value by restating the formula, giving complete JSON examples, and clarifying the velocity conversion (km/h ÷ 3.6, mph × 0.44704) in the schema. The description also reinforces the physical meaning of each parameter.

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 ('compute'), a specific resource ('translational kinetic energy of a moving mass'), and the formula (KE = ½·m·v²). It also distinguishes itself from potential-energy and rotational-energy cases, making it easy for an agent to select this tool over siblings like calculate_bmi or calculate_compound_interest.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool ('when you need the energy of motion of an object of known mass and speed'), and when not to use it (rotation, relativistic speeds, height/potential energy). It even names the alternative concept (potential-energy) and instructs the agent to call the tool directly rather than answering from memory.

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 convey readOnlyHint and idempotentHint, and the description adds substantial behavioral context: the fully amortizing level-payment method, zero-rate interest handling, the exact formula, and that term_years and term_months are additive. No contradiction exists between the description and annotations.

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

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

The description is long but every section earns its place: usage routing, computation summary, examples, input combination rules, JSON examples, output fields, formula, and REST fallback. It is front-loaded with the most critical selection guidance and structured with clear labels, making it easy to scan.

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?

Despite the presence of an output schema, the description still lists outputs and gives the formula for all edge cases (including zero annual rate). It also provides a direct REST fallback and documentation link biscuits. An agent has everything needed to invoke the tool correctly across all valid input scenarios.

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 covers all parameters at 100% with descriptions, so the baseline is 3. The description adds value by stating valid input combinations (term_years, term_months, or both summed) and providing two complete JSON examples, going beyond the individual parameter descriptions but not dramatically.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('compute the monthly payment or total interest cost') and a clear resource ('auto, personal, student or other fixed-rate installment loan'). It differentiates itself from siblings by explicitly naming mortgage-payment and debt-payoff, so an agent can select it correctly without inspecting other 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?

Explicit when-to-use ('Use this when you need...'), when-not-to-use ('Do not use this when you need property tax...'), and direct alternative routing ('use mortgage-payment', 'use debt-payoff'). This leaves no ambiguity about tool selection for amortizing fixed-rate loans.

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. The description adds concrete behavioral context: parsing rules (brackets, nested groups, hydrates), use of IUPAC 2021 atomic weights, and the full list of computed outputs. It exceeds what annotations alone convey.

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 long but every section earns its place: usage conditions, computation behavior, input, examples, outputs, formula, REST fallback, and docs. It is front-loaded with the use case and structured with clear labels. Some redundancy exists (examples appear in both description and schema), but overall it is efficiently organized.

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 calculator with an output schema and safety annotations, the description covers all necessary context: when to use, what it computes, how inputs are interpreted, what outputs to expect, and even a fallback REST call. An agent has everything needed 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%, so the baseline is 3. The description restates the input as 'formula (string)' and gives examples that duplicate the schema's examples, but it does add minor context about brackets, nested groups, and hydrates parsing. This is helpful but not substantial 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 the exact trigger condition: having a chemical formula and needing molar mass, atom counts, or mass-percent composition. The verb 'calculate' and resource 'chemical formula' are explicit, and the description distinguishes this from other calculators.

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 clear 'Use this when' and 'Do not use this when' guidance, naming alternative tools (moles-mass, molarity) and even instructing the agent to return the calculation rather than answering from memory. This leaves no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral context by specifying what it computes (P&I, taxes, insurance, HOA, total interest) and provides the formula, without contradicting any annotation. It does not describe side effects (none exist) but goes beyond the annotations by detailing the computation scope.

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 long (multiple sections) but well-structured and front-loaded with purpose and usage. It includes inputs, examples, outputs, formula, REST fallback, and docs link. Each section serves a purpose; while it could be tightened, the organization makes it easy to scan and extract key facts.

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 calculator tool with 7 parameters and a full output schema, the description is exceptionally complete. It covers the computation formula, lists all outputs (matching the schema), gives two complete example JSON payloads, and includes a REST fallback endpoint and documentation link. 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 schema fully describes each parameter. The description lists inputs with units and optionality and provides two complete JSON examples, but this is largely redundant with the schema. It adds the formula relationship (e.g., loan_amount = home_price − down_payment) which is helpful, but since the schema already covers semantics, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it calculates the monthly cost of a fixed-rate mortgage including escrowed taxes/insurance, and the total interest. It explicitly excludes adjustable-rate and interest-only loans, distinguishing itself from the sibling calculate_loan_payment. The scope 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?

Provides explicit when-to-use (fixed-rate mortgage with escrow) and when-not-to-use conditions (adjustable-rate, interest-only, or plain loan amount, for which it names the alternative calculate_loan_payment). Also instructs the agent to call the tool directly rather than compute manually, leaving no ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it always returns part, whole, and percent; it instructs the agent to call directly and return the calculation rather than stopping at discovery; and it provides a direct REST fallback with a warning not to guess other paths.

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 longer than average but well-organized: usage guidance first, exclusions second, then computation details, examples, output, formulas, and REST fallback. Some redundancy exists (Inputs/Outputs repeat schema fields), but every section earns its place and the critical routing information is front-loaded.

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

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

Given the tool's three-mode complexity, the description covers everything an agent needs: when to use it, what it computes, formulas, examples, output shape, REST fallback, and documentation link. The output schema exists, so return values are further specified. No critical gap remains.

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 adds meaning beyond the schema by giving complete JSON examples and explicit formulas for each mode, clarifying exactly how x and y are interpreted in each mode. This is more than the schema alone 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 states a specific verb and resource ('calculate percentage') and enumerates the three distinct percentage questions it solves. It explicitly differentiates from sibling tools like percentage-change, discount, and sales-tax, so an agent can disambiguate 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 'Use this when' conditions and explicit 'Do not use this when' exclusions that name the correct sibling alternatives (percentage-change, discount, sales-tax). This is textbook usage 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?

Even with readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: the exact formulas, the list of computed outputs, the requirement that old_value not be zero, and the REST fallback behavior. It fully discloses what the tool returns and how it calculates.

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 long but every section earns its place: usage guidance, exclusions, computed outputs, formulas, examples, and REST fallback. It is front-loaded with the most important when-to-use information and uses clear labels for quick scanning.

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 schema richness, annotations, and output schema, the description is fully complete. It provides the formula, expected outputs, edge-case constraint for old_value, direct REST endpoint, and documentation link, so an agent has everything needed to invoke it correctly.

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

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

The input schema already describes both parameters completely, so the baseline is 3. The description adds value with complete JSON examples and the formula expressions that clarify how each parameter is used, though it mostly confirms rather than extends the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states exactly what the tool computes: percentage increase/decrease and symmetric percent difference between two values. It also names sibling alternatives like percentage, cagr, and roi, so an agent can distinguish this tool from them immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance ('when you have a starting and an ending value') and explicit when-not-to-use guidance with named alternatives. It even instructs the agent to call the tool directly rather than answering from memory, leaving no ambiguity.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds substantial context beyond that: the exact formula, the full output list, the REST fallback path, and the instruction to call the tool directly instead of computing from memory.

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 long but exceptionally well structured with bold section labels: inputs, outputs, formula, REST fallback, and docs. Every section earns its place, and the intended use case is front-loaded.

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

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

Given the output schema exists and annotations cover the side-effect profile, the description is complete: it covers when to use it, when not to, all inputs, output fields, the underlying formula, and a fallback endpoint. An agent has everything needed 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%, so the baseline is 3. The description adds value with complete JSON argument examples, the formula relating parameters to outputs, and clarification of time format variants, going slightly beyond what the schema alone 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 states a specific verb and resource: it 'computes running pace in min/km and min/mile and speed in km/h and mph' and projects finish times. It also clearly distinguishes this tool from siblings race-time-predictor and pace-converter, so an agent can select it confidently.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance ('Use this when you know a distance and the time...') and explicit when-not-to-use exclusions with named alternatives ('use race-time-predictor', 'use pace-converter'). This leaves no ambiguity about tool selection.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses the exact computation performed (network, broadcast, masks, host ranges), the arithmetic approach (32-bit unsigned), and the formula used. This is rich behavioral context that lets the agent predict results and trust the tool as a non-destructive calculation.

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 well-structured with labeled sections (What it computes, Inputs, Outputs, Formula, REST fallback) and front-loaded usage guidance. It is longer than necessary, but every major section contributes useful context such as output fields, computation formula, and API fallback, so the length is justified.

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 calculation tool with rich output schema and annotations, the description covers all essential decision points: when to use it, what inputs it accepts, what outputs it returns, how the calculation works, and even a direct REST fallback. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% and the schema already explains the cidr parameter's formats and examples in detail. The description reinforces the accepted input forms (CIDR or dotted mask) and the JSON examples, but adds little semantic meaning beyond what the schema already provides, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise statement of what the tool does: determining subnet membership, host range/count, and mask equivalents for IPv4 addresses. It differentiates from the many sibling calculate_* tools by explicitly scoping to IPv4 subnet calculations and naming excluded cases (IPv6, VLSM planning, base conversion).

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 provides an explicit 'Use this when' list and an even more explicit 'Do not use this when' list with alternatives such as base-converter and VLSM planning. It also tells the agent to call the tool directly instead of answering from memory, removing ambiguity about tool orchestration.

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 mark it read-only, idempotent, and non-destructive; the description adds the exact formula, the Mifflin-St Jeor basis, the activity multipliers, and the ±250/±500 derivation of targets. No side effects or edge behaviors are hidden.

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 usage, then exclusions, computation summary, input list, worked example, output list, formula, and fallback. Each section is short and earns its place, making it scannable despite the amount of 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 5-parameter calculator with an output schema, the description answers what, when, when-not, inputs, outputs, formula, and provides both REST and docs fallbacks. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema description coverage is 100% and includes enums, units, bounds, examples, and defaults, so the baseline is 3. The description repeats input names and units and provides a complete JSON example, but adds little parameter meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the exact resource (TDEE from Mifflin-St Jeor BMR plus activity level) and the supported goals (maintenance, mild/standard deficit/surplus). It also distinguishes the tool from calculate_bmr by explicitly reserving calculate_bmr for resting-rate needs.

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 explicit when-to-use ('need daily maintenance calories...' / 'calorie targets for a mild/standard deficit or surplus') and when-not-to-use conditions, including an explicit alternative ('use bmr') and exclusions for children and pregnancy/breastfeeding.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds beyond that: the exact formula, the computed output fields, and direct REST fallback instructions. This gives the agent a clear model of what the tool computes and returns without contradicting the annotations.

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

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

The description is front-loaded with the primary use case and contains several useful sections: exclusions, inputs, outputs, formula, and fallback URL. It is slightly redundant with the schema, especially the repeated JSON examples, but every section still serves a purpose and there is no filler.

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

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

An output schema exists, and the description still supplies everything needed for correct invocation: when to call it, when not to, parameter semantics, expected outputs, the formula, and a REST fallback. Nothing an agent needs to select or call this tool correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents each parameter's type, constraints, defaults, and examples. The description adds only light value by restating the inputs as a compact list and clarifying optionality and the even-split meaning of split_between. This matches the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'add a gratuity to a restaurant, delivery or service bill' and 'divide the total among several people.' It clearly distinguishes the tool from relatives like bill-split and sales-tax, so an agent can identify what this calculator does 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?

The description explicitly states when to use the tool, when not to use it, and names the alternatives: 'Do not use this when people pay for different items or unequal shares (use bill-split), or you need to add sales tax rather than a tip (use sales-tax).' This leaves no ambiguity about 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds behavioral detail: it specifies Welch's correction for unequal variances, describes the output fields (t, df, p-values, CI, decision), and notes the fallback REST endpoint and docs. This goes beyond annotations without contradicting them.

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 long but well-structured with clear sections: usage, exclusions, what it computes, example requests, inputs, valid combinations, examples, outputs, formula, fallback. The core usage is front-loaded. Some redundancy with schema examples exists, but each section serves a purpose and the length is justified by the tool's complexity.

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 an 11-parameter tool with three modes and conditional requirements, the description is exceptionally complete. It covers valid combinations, provides examples for every mode, gives the formulas, lists output fields, and even includes a REST fallback and documentation link. An agent has everything needed to call it correctly without external 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?

Schema coverage is 100% with descriptive parameter docs, so baseline is 3. The description adds meaningful semantics: it enumerates valid input combinations for each mode, clarifies that two_sample is the default, warns against mixing raw and summary fields, and provides complete JSON examples. This genuinely helps an agent construct valid calls.

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 precise statement of what the tool does: testing sample mean vs hypothesised value, two independent groups, or paired before/after measurements. It names the three t-test variants and clearly separates this from sibling calculators. Even without naming siblings, the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool (the three scenarios) and when not to, naming specific alternatives: proportion-z-test, chi-square-test, ANOVA, and p-value for existing t/df. This gives an agent clear routing logic.

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 mark the tool read-only and idempotent, and the description does not contradict them. It adds substantial behavior beyond annotations: the exact modulo formulas for upper/lower trigrams and moving line, the handling of remainder 0, and the full output field list including 体/用 five-element relations. Providing the REST fallback path also removes ambiguity about how the computation is reached.

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?

Long, but sectioned and front-loaded with the use/when-not guidance before any technical detail. The formula, output list, valid combinations, JSON examples, REST fallback, and docs link each serve a distinct purpose, so the length is justified by the tool's multi-method complexity.

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 seven parameters, three method variants, an output schema, and annotations, the description covers method selection, input constraints, computation formula, output fields, and a fallback REST endpoint. Little remains for the agent to infer; the output schema covers return values, and the formula section covers what happens inside the calculation. This is complete 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 coverage is 100% and each parameter already has a description, so the baseline is met. The description adds value by explaining valid input combinations and how each parameter feeds the arithmetic (number_1 mod 8, number_2 mod 8, number_3 mod 6, add_hour_to_moving_line in the two-number method). It does not fully restate constraints, but the schema and description together are strong.

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 object: 'cast a Plum Blossom hexagram' from a moment or from numbers, then lists exactly what it computes (moving line, changed/nuclear hexagrams, 体/用 relation). It also separates itself from hexagram text/structure retrieval by naming hexagram-lookup for that case. This 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?

Opens with an explicit trigger condition ('Use this when you need a Plum Blossom hexagram cast for a moment or from numbers') and an explicit exclusion ('Do not use when you already have six lines...'). It names alternatives for the excluded cases, though some names are conceptual rather than matching the sibling list exactly, so the agent has to map them; the yes/no boundary itself 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds valuable context: it computes official national working days from State Council notices, includes weekend makeup workdays (调休上班), and provides the override formula. It also lists output fields. This goes beyond annotations without contradicting them.

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 long but well-structured with clear sections (use when, do not use, what it computes, examples, inputs, outputs, formula, REST fallback). Every sentence serves a purpose, especially the formula and REST fallback, which are non-obvious. It is front-loaded with the primary directive. Slightly verbose but justified given the domain complexity.

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 complexity of the Chinese holiday calendar, the description covers scope, inputs, outputs, calculation logic, examples, and even a REST fallback and documentation link. An agent has everything needed to call it correctly. The output schema exists (listed fields) and the description complements it comprehensively.

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 description for 'date' already specifies 'Mainland China civil date (YYYY-MM-DD), within 2024-2026.' The description reinforces the range and format but adds little beyond that (e.g., example JSON). With complete schema coverage, a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('checks whether') and resource ('a specific 2024-2026 date is a working day in mainland China'). It explicitly differentiates itself from sibling tools like add_china_working_days, count_china_working_days, and check_uk_working_day by focusing on a single-date check. The purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use (need to know if a 2024-2026 date is a working day in mainland China, especially around Spring Festival/National Day) and when-not-to-use (HK/Macao/Taiwan, local minority, school, employer, bank-settlement, stock-exchange calendars, or years outside 2024-2026). It also instructs to call directly rather than answer from memory, clearly steering the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it uses a pinned snapshot of the official GOV.UK bank-holiday feed, it computes based on a specific formula (bank holiday → non-working, weekend → non-working, else working), and it returns a status_basis and source_url. It also discloses the date-range constraint (2024-2028) and the division-specific behavior. It doesn't describe pagination or error behavior, but for a read-only calculator that's not a significant 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?

The description is well-structured with clear sections: when to use, when not to use, what it computes, example requests, inputs, outputs, formula, and REST fallback. It's longer than average, but every section earns its place by providing actionable guidance. The front-loaded 'Use this when' sentence is the most important information and appears first.

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 calculator with a rich output schema, the description is complete. It covers the date range, division semantics, the formula, the output fields, the REST fallback, and documentation link. An agent has everything needed to select and invoke this tool correctly, including how to handle the substitute holiday example.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds meaning by explaining the division enum values ('England and Wales share one official list; Scotland and Northern Ireland have separate lists') and by giving complete JSON argument examples. It also clarifies the date format and range. This goes beyond the schema's basic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('check'), a specific resource (UK working day), and the exact scope (2024-2028, Monday-Friday after official bank holidays for the selected division). It also distinguishes itself from sibling tools like check_china_working_day and count_uk_working_days by naming the division-specific behavior and the pinned GOV.UK feed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool ('Use this when you need to know whether a 2024-2028 UK date is a Monday-Friday working day...'), and explicitly says when not to use it ('Do not use this when you need a local council, school, employer, financial-market, emergency-closure or non-UK calendar, or a date outside 2024-2028'). It also provides example user requests and a direct REST fallback, which is strong routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context: it computes full-term costs only, ignores the time value of money, assumes fixed-rate fully amortizing loans, and is informational rather than financial advice. No contradiction with annotations exists.

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 long, but well-structured and front-loaded with the core use case and exclusions. Every major section (what it computes, examples, inputs, outputs, formula, REST fallback) earns its place for a complex calculator. Minor redundancy exists with the schema examples and output list, so it is not perfectly concise.

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 7-parameter calculator with an output schema and full schema documentation, the description is exceptionally complete: it includes use cases, exclusions, formulas, output names, example JSON, a REST fallback, and docs URL. An agent has everything needed to select and invoke the tool 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 the baseline is 3. The description's 'Inputs' section restates parameter names and adds example JSON, but it does not add semantic detail beyond what the schema already provides for each parameter. This is adequate but not an extra source of parameter 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?

The description names a specific verb and resource ('compares two fixed-rate, fully amortizing loan offers') and clearly defines the scope: two loan quotes for the same amount with different rates, terms, or fees. It also distinguishes itself from nearby siblings by stating it covers payments, interest, fees, and total cost side by side.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool ('when you have two loan or mortgage quotes...') and gives explicit when-not-to-use conditions with named alternatives (refinance-break-even, loan-payment) and a behavioral caveat (early sale/repayment). This leaves no ambiguity about 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 mark readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context beyond that: it auto-detects the input format, reports detected_format, includes a direct REST fallback path, and explicitly notes 'Mathematics only; not gambling advice.' No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (when to use, when not, what it computes, inputs, examples, outputs, formula, fallback). It is front-loaded with usage context. The formulas and REST fallback are arguably beyond minimum needs but serve to eliminate ambiguity for a complex calculator with multiple outputs and auto-detection.

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

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

The description covers all essential aspects for correct invocation: exact input formats, auto-detection rules, output fields, a direct REST fallback, and alternative tool routing. Given the tool's complexity and presence of an output schema, the description fully equips an agent to call it correctly without guessing.

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 parameters are fully documented with types, defaults, and format auto-detection rules. The description adds value by providing two complete JSON argument examples and mapping each parameter to its role, plus formulas that connect parameters to outputs. This exceeds the baseline 3 for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb+resource: converts betting odds between American, decimal, and fractional formats, and computes implied probability and payout. It explicitly names three sibling tools it is not (parlay-odds, bet-expected-value, arbitrage-bet), clearly distinguishing it from related calculators.

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 explicitly states when to use ('when you have odds in one format and need the other two...') and when not to use, listing the alternative tool for each exclusion. It also instructs the agent to call the tool directly rather than deriving the answer from memory, leaving no ambiguity about invocation.

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?

Beyond annotations that already mark this as read-only and idempotent, the description adds rich behavioral context: it validates leap-month/day existence, explains the formula (JDN = start of month + day − 1), references the GB/T standard, and instructs the agent to call the tool instead of answering from memory. No contradiction with annotations.

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

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

The description is clearly sectioned with headers, front-loads the use case, and every section earns its place: examples, inputs, outputs, formula, fallback, docs. It is long but not bloated; the structure makes it easy to scan.

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

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

For a tool of this complexity, the description is complete: it covers when to use, what it computes, all inputs with examples, output fields, the underlying formula, a REST fallback, and documentation. Even with the output schema present, the description leaves no meaningful gap for 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?

The schema already covers all four parameters with descriptions and examples, so the baseline is 3. The description adds value by pairing Chinese examples (八月十五, 闰六月初一) with complete JSON argument examples, and by clarifying is_leap_month as 'optional' with a true/false usage. It reinforces the schema without being the only source of 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?

The description names a specific verb ('Converts') and resource ('Chinese lunar calendar date... to the Gregorian date'), and enumerates the computed outputs. It also explicitly distinguishes itself from reverse conversion ('Do not use this when you start from a Gregorian date') and from mass festival lookups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is an explicit 'Use this when...' condition with concrete example requests, and a 'Do not use this when...' section naming two alternative categories. This gives an agent clear selection criteria without needing to inspect sibling schemas.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds substantial context beyond these: default to today's date, full output field list, leap-month and ganzhi calculation formulas, and a direct REST fallback. This gives the agent a clear model of what happens when the tool is invoked.

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 long but well-organized with clear sections: usage, exclusions, computed fields, examples, inputs, outputs, formula, and fallback. While the formula section is more detailed than strictly necessary for invocation, the structure makes it digestible and every section serves a purpose.

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

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

For a complex lunisolar conversion tool, the description provides everything needed: when to use, what it returns (with output schema present), how it computes leap months and ganzhi, and a REST fallback URL with a warning not to guess other paths. Combined with annotations and schema, the usage context is fully covered.

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 already documents the single 'date' parameter, including its UTC+8 timezone, 1900–2100 range, and default of today. The description only repeats 'date (date, optional)' and 'defaults to today' without introducing new semantic detail, so it adds no value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: converts a Gregorian date to the Chinese lunisolar calendar and enumerates the exact computed values (lunar date, ganzhi, zodiac, solar terms). It distinguishes itself from convert_lunar_to_solar, find_chinese_zodiac, and astronomical moon-phase tools, leaving no doubt about this tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit 'use this when' section (need lunar date, ganzhi, zodiac, or solar term from a Gregorian date) and a 'do not use this when' section that names the exact alternative tools (lunar-to-solar, chinese-zodiac, moon-phase). It also instructs the agent to call the tool directly rather than deriving from memory.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: exact conversion formulas, rejection of values below absolute zero, output fields, and a direct REST fallback. No contradiction with annotations.

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

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

The description is longer than average but well-structured with labeled sections: use cases, exclusions, computation details, inputs, examples, outputs, formula, fallback, and docs. There is minor redundancy in repeating formulas, but most content 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 deterministic 3-parameter converter with full schema coverage, an output schema, and read-only annotations, the description supplies everything an agent needs: formulas, invalid-input rejection, complete JSON examples, fallback endpoint, and documentation link.

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 value, from_unit, and to_unit clearly. The description adds useful formula context and examples, but does not materially expand parameter meaning beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with concrete use cases (weather, cooking, body, laboratory) and names the exact operation: converting between Celsius, Fahrenheit, Kelvin, and Rankine. This clearly distinguishes it from generic convert_units and other calculator siblings.

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 explicitly states when to use the tool, instructs the agent to call it directly rather than computing from memory, and gives clear do-not-use conditions for temperature differences and heat energy. The reference to an energy alternative satisfies the when-not/alternatives requirement.

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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint all true/false appropriately), the description discloses pinned tzdb version (2026d), reporting of both offsets, UTC instant, date changes, source-time status, and candidate UTC instants for repeated hours. It also provides the exact formula and resolution policy handling, which adds significant behavioral context beyond what annotations convey.

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 comprehensive but well-structured with clear sections (when to use, when not, what it computes, examples, inputs, outputs, formula, fallback). It front-loads the core usage instruction and uses bullet-like formatting for clarity. There is some redundancy (examples repeated in prose and JSON), but overall it is efficient and readable.

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

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

The description covers all necessary aspects: purpose, usage conditions, behavior, parameters (with examples), outputs (enumerated), the underlying formula, and even a direct REST fallback for verification. It is complete for an agent to invoke the tool correctly without needing additional context.

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

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

Schema coverage is 100% with detailed descriptions for every parameter. The description adds value through complete JSON examples and clarifies the resolution_policy in the context of repeated hours (via behavioral description and formula). It doesn't repeat schema details but supplements with usage context, justifying a score above the baseline of 3.

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 explicitly states the tool converts wall-clock date/time between IANA zones on a specific date, with a clear verb ('converts') and resource ('time between zones'). It distinguishes from siblings by naming alternatives (world-clock, unix-timestamp, time-duration) and instructs the agent to call the tool directly rather than computing manually.

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 ('when you need to know what time an event scheduled in one city corresponds to in another') and when-not-to-use conditions with named alternatives ('Do not use this when you need the same instant in many zones at once (use world-clock)...'). Also instructs to call the tool directly and return its calculation, which is a clear directive.

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 with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral detail beyond those: accepted unit symbols/common names, the return contents (converted value, detected quantity, exact factor, conversion table), and the same-quantity constraint. This is meaningful but not exhaustive, e.g., no error behavior for unsupported units.

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 compact and front-loaded: the trigger appears first, followed by explicit exclusions and return behavior. Every sentence adds distinct information, and there is no filler or redundant restating of 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?

For a stateless, read-only conversion tool with full parameter schema coverage and an output schema, the description is complete. It specifies supported quantity classes, when not to use the tool, accepted input forms, and return contents. No critical selection or invocation information 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%, and the parameter descriptions already include examples like 'mi', 'miles', and '°C'. The description adds a general 'same physical quantity' constraint and notes that symbols/common names are accepted, but these are supplementary rather than essential given the schema already documents all three parameters.

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 action ('convert a numeric value between units of the same physical quantity') and explicitly enumerates the supported quantity types. It also distinguishes itself from other converters by excluding currency, live exchange rates, and density-dependent cross-quantity conversions, so an agent can tell when this tool applies.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear trigger condition ('Use this when the user asks to convert a numeric value between units of the same physical quantity') and explicit negative instructions ('Do not use this for currency, live exchange rates or cross-quantity conversions that require density'). It does not name sibling alternatives directly, but the when/when-not guidance is strong.

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 mark the tool as read-only, idempotent, and non-destructive. The description goes beyond this by disclosing the actual computation model: it uses 'State Council holiday periods and weekend makeup workdays rather than a simple Monday-Friday rule.' It also exposes the formula and notes that dates outside the coverage window are normalized and reported, giving the agent an accurate mental model of the tool's behavior.

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

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

The description is front-loaded with the most decision-relevant information: when to use it and when not to. It is longer than average because it includes examples, an output list, a formula, and a REST fallback, but each section has a clear purpose. The input and output lists are somewhat redundant with the schema and output schema, which keeps it from a perfect score.

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

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

Given the tool's moderate complexity (date range, holiday calendar, inclusive boundaries), the description is remarkably complete: it gives realistic user example requests, a full JSON invocation example, the output field names, the computation formula, a direct REST fallback URL, and a docs link. The presence of an output schema means the detailed output list is bonus rather than necessary, and nothing essential for selecting or invoking 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description's 'Inputs' line largely repeats what the schema says, but it does add a complete JSON example and ties the parameters to an inclusive-date semantics. That is helpful, but not a significant semantic gain over an already fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the exact purpose: 'number of official mainland China working days in a 2024-2026 date range.' It names the specific output resource and scope, and the geographic qualifier clearly separates it from siblings like count_uk_working_days and check_uk_working_day. It also tells the agent to 'call this tool directly and return its calculation,' which eliminates ambiguity about what action to take.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance ('for an SLA, payroll, project or delivery estimate') and explicit when-not-to-use guidance ('Do not use this when you need only elapsed calendar days, another jurisdiction, an industry-specific settlement calendar, or dates outside 2024-2026'). This directly orients the agent toward the correct tool and steers it away from common confusions.

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 mark the tool read-only, idempotent, and non-destructive. The description adds valuable behavior: it uses the official GOV.UK holiday list rather than a weekday-only approximation, normalizes endpoints, counts working/non-working days, and exposes dataset metadata. There is no contradiction with annotations.

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

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

The description is well-organized with front-loaded usage conditions and clear labeled sections. There is some redundancy with the schema and repetition of the core computation, but the structure makes it scannable and the extra detail is purposeful.

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

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

The description covers use cases, exclusions, inputs, complete JSON examples, output fields, the computation formula, a direct REST fallback, and documentation. Given the rich schema, annotations, and output schema, nothing essential is missing 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%, and the description's Inputs section largely restates the schema. The JSON examples are helpful but mostly duplicate examples already present in the schema, so the description adds little semantic meaning beyond the structured parameter definitions.

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: counting UK working days between dates using the official GOV.UK bank-holiday list, with division support for England and Wales, Scotland, or Northern Ireland. It also clearly differentiates this from single-date checkers and calendar-day tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance for UK SLA, payroll, project, or delivery-day counts and explicit when-not-to-use guidance for elapsed calendar days, non-UK jurisdictions, employer-specific calendars, and dates outside 2024-2028. It also tells the agent to call the tool directly instead of computing from memory.

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, and non-destructive hints. The description adds behavioral context beyond annotations: it is a constant-power estimate, mentions DC fast charging taper, and discloses the cost calculation. It does not contradict any 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?

The description is long but organized into clear sections: usage, exclusions, computed values, inputs, examples, outputs, formula, and REST fallback. The inputs list is redundant with the schema, but the rest earns its place. Front-loading the usage conditions is effective.

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 complex 7-parameter calculator with an output schema, the description covers everything an agent needs: when to use, what it computes, all parameters, example JSON, output names, the exact formula, a REST fallback, and a docs link. 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% and each parameter is already well-described. The description adds value by explaining the relationships between parameters (e.g., effective_power = min(charger_power_kw, max_onboard_charger_kw)) and the cost formula, which gives the agent a deeper understanding of how inputs affect outputs.

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 explicit use cases (home wallbox, AC post, DC fast charger) and states exactly what it computes (charging time, energy, cost). It distinguishes from sibling tools by name (battery-charge-time, ev-range-efficiency), leaving no ambiguity about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear when-to-use and when-not-to-use conditions, explicitly naming the alternative tools for battery charge time and driving range. It also warns about DC fast charging taper, which helps the agent select the tool appropriately.

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 mark it read-only, idempotent, and non-destructive. The description adds rich behavioral context: boundary selection rules, the exact year and ganzhi formula, the full set of computed fields, and a REST fallback path. There is no contradiction with 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.