Business-day check

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

Annotations already declare readOnly, idempotent, and non-open-world behavior, so the safety profile is covered. The description adds genuinely useful non-schema context: per-call pricing after a free tier and x402 payment. However, it omits operational details such as rate-limit behavior at the paywall boundary or what happens when country data is out of the 2000–2050 range.

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

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

The core question and the returned values are front-loaded, and the use-case and customization clauses follow logically. The pricing sentence is slightly tacked-on but carries real decision value, so little is wasted.

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

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

With an output schema present, the description needn't enumerate return fields, and it instead covers the capability surface (checks, neighbors, counts), holiday sources, custom workweeks, and cost. It is complete enough to invoke correctly; only sibling differentiation 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 75% and the parameters already carry descriptions, including country holiday exclusion and the workdays weekday encoding. The description echoes these with extra examples (Sun–Thu, Mon–Sat) but adds no format or interaction semantics beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a direct question form ('Is a date a business day?') and then enumerates the concrete outputs: reason for non-business day, next/previous business day, month count, first/last business day. The resource and operations are unambiguous. It stops short of distinguishing itself from siblings like public_holidays or working_hours_overlap, which a reader must infer from the feature list.

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 supplies explicit usage contexts — 'office-open checks, shipping cut-offs, settlement dates' — which tells an agent when this tool is the right pick. There are no stated exclusions or named alternatives, so an agent choosing between this and public_holidays still has to reason it out.

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