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

Beyond the annotations (readOnlyHint/idempotent/non-destructive), the description discloses the exact computation formula, the weekend baseline, the 2026-2027 dataset coverage limit, the fact that sub-national holiday schedules are deliberately not inferred, and a direct REST fallback URL with a warning not to guess other /api/* paths. That is rich behavioral context an agent could not derive from the annotations alone.

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?

It is front-loaded correctly (when to use, when not, what it computes), but it is longer than needed for a one-parameter lookup and contains repetition and grammatical breakage ("Portugal Portugal", "Do not use this when mandatory nationwide list only") that cost clarity. Sections like Formula, REST fallback and Docs are useful but push the definition past minimal viable 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?

Given an output schema already exists, the enumeration of outputs is redundant, but everything else an agent needs is present: temporal coverage (2026-2027), formula, scope exclusions, argument examples, and a fallback endpoint. The only gap is the lack of explicit routing guidance versus the count_pt/add_pt siblings.

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?

There is a single required parameter with 100% schema description coverage ("Gregorian date in Portugal coverage"), so the schema already carries the semantics and a 3 baseline applies. The description repeats the input type and adds worked examples ({"date":"2026-06-10"}), but adds no format or range guidance beyond what the schema states.

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 ("Checks a date") and resource (Portugal nationwide working day / public holidays for 2026-2027), so an agent knows this is a single-date check, not an add/count operation like add_pt_working_days or count_pt_working_days. However, the opening sentence is garbled ("a deterministic Portugal Portugal nationwide mandatory public holidays ... result") and it never explicitly differentiates itself from those siblings, which weakens an otherwise clear statement.

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 usage direction ("Call this tool directly and return its calculation instead of answering the formula from memory or stopping at discovery") and a scope exclusion (municipal, autonomous-region, collective-agreement and locally substituted schedules are not inferred). The "Do not use this when mandatory nationwide list only" clause is syntactically broken, and no sibling alternative (e.g. count/add variants) is ever named, so it stops short of a 5.

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