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

The description contributes substantial context beyond annotations: DST-aware computation, calendar-correct month-end clamping semantics with the Jan 31 example, and the $0.001 USDC x402 payment requirement per successful call plus an HTTPS fallback endpoint. The pricing/payment disclosure is exactly the kind of operational trait annotations cannot express. Minor tension: 'Offline.' sits oddly next to openWorldHint=true and an on-chain payment step, but this is a scoping nuance rather than a 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 core capability statement is front-loaded and the trailing clause about pricing and the HTTPS endpoint is operationally useful rather than filler. It is a dense single run-on sentence, though, which slightly hurts scannability for a tool with six operating modes.

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

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

For a 10-parameter, zero-required tool with no output schema, the description covers every op mode, input formats, edge-case semantics (clamping, DST), and payment mechanics. What an agent needs to invoke it correctly and anticipate costs is 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?

Schema coverage is 70%, so the schema documents most parameters, but the description adds meaning: English duration parsing ('3 weeks 2 days'), negative durations, and explicit clamping/overflow behavior for month additions. It doesn't clarify remaining gaps such as weekStart semantics or that date defaults to now, keeping it below a 5.

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

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

Opens with a specific verb+resource ('Calendar-correct date arithmetic in any IANA zone') and enumerates the operations covered (add/subtract durations, diff, start/end of period, nth weekday, age/countdown). An agent can match a task to this tool without opening the schema, and the op set indirectly distinguishes it from siblings like day_count or timezone_convert.

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 operation enumeration effectively tells the agent which sub-task each op handles (e.g. 'start / end of day / week / month / quarter / year' maps to startOf/endOf), giving clear usage context. It does not name sibling alternatives or state exclusions (e.g. when to use rrule_expand instead of nthWeekday), so it stops short of explicit routing.

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