Zovo Per Diem Calculator

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

Annotations already declare a safe, idempotent, closed-world read; the description adds substantive behavior beyond them: hard caps (10 trips, 10 stops, 92 days, 400 day rows), the deduction logic for furnished vs. common-carrier vs. complimentary breakfasts, the >12-hour same-day-travel rule, and the 'no times are taken' constraint. These are exactly the non-obvious traits an agent needs before calling.

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

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

Front-loaded with the trigger and the output, then layered with scope limits and exclusions; every sentence carries an operational constraint. Slightly marred by keyword-stuffed duplication in the opening ('per diem calculator, gsa per diem calculator, or travel per diem calculator') that could be trimmed to one phrase.

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

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

With an output schema present, the description need not explain return values and correctly doesn't. It covers rate vintage, geographic scope, all hard limits, deduction rules, and exclusions – nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already carries field-level meaning and the baseline is 3. The description still adds real value by defining which meals count as deductions ('government or registration meals reduce allowances; common-carrier meals and complimentary hotel breakfasts are not'), which disambiguates the meals_provided booleans, and by clarifying that no times are accepted.

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

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

States a specific verb (calculate) and resource (per diem) with the concrete output ('downloadable XLSX/CSV expense worksheet'), so an agent knows exactly what it produces. It does not, however, name or contrast itself with the sibling find_per_diem_rates, so differentiation is inferred rather than explicit.

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

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

Opens with an explicit trigger ('Use this when the user wants...'), enumerates the paraphrase variants that should route here, and closes with explicit exclusions ('Do not use for OCONUS, lodging taxes, agency policies or FY2028'). That is a complete when/when-not statement.

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/closedWorld, and the description adds substantial context beyond them: the data is a bundled snapshot (CONUS FY2026/FY2027), the fiscal year defaults using today in America/New_York, and ambiguous ZIPs yield a per-item error rather than a global failure. That error-shape detail is exactly the kind of behavior annotations cannot 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?

Front-loaded with the user intent that triggers the tool, then scope, then constraints. Every sentence carries a distinct fact (scope, cardinality, default, error handling, exclusions) with no restatement of the name or 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?

An output schema exists so return values need not be explained, and the annotations carry the safety profile; the description covers the remaining gaps an agent needs — data vintage, year bounds, cardinality, and ambiguous-input behavior — leaving nothing material unstated for a two-parameter lookup tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the 1-to-25 cardinality bound for locations and, more importantly, the defaulting rule for the optional fiscal_year (today in America/New_York). It stops short of explaining accepted location formats beyond what the schema already shows.

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 ('looks up GSA per diem rates') scoped to ZIP or City, ST locations in bundled CONUS FY2026/FY2027 tables. It distinguishes itself from the sibling by naming calculate_per_diem as the disambiguation path, so an agent can route without opening either schema.

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

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

Explicit trigger language ('Use this when the user wants gsa per diem rates, federal per diem rates, per diem rates 2027 or m&ie rates by month') plus explicit exclusions ('Do not use for OCONUS or FY2028') and a named alternative for the ambiguous-ZIP case. When-to-use, when-not-to-use, and the fallback are all present.

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