DMEPOS order-readiness checklist (free)

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

Annotations already carry readOnly/idempotent/closed-world, but the description adds genuinely non-obvious behavior: it returns blank requirement definitions rather than a patient-specific determination, is PHI-free by construction, is free and needs no API key, and returns null for paRequired on state-phased items until a state is supplied. That null-semantics disclosure is the kind of edge case an agent would otherwise misread as a false negative.

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?

A single dense paragraph that front-loads the core definition and then tacks on scope, nullability, and cost facts — no wasted sentences. Minor redundancy: 'free' appears both in the title and again as 'Free, no API key required' at the end, which could be folded into one 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?

With no output schema, the description does the necessary work of telling the agent what comes back (SWO elements per 42 CFR 410.38(d), F2F/WOPD status, PA-list status) and even names one return field (paRequired). It stops short of describing the output shape or the other field names/types, which for a three-part checklist would help an agent consume the result.

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 and the schema already explains code, state enum, and the today default for dateOfService. The description still earns credit by explaining the conditional interaction between state and the returned paRequired field, which is the one parameter behavior the schema cannot express.

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 clause gives a specific verb and resource ('Blank pre-delivery checklist for a HCPCS DMEPOS code') and then enumerates the three things returned: SWO elements, F2F/WOPD list membership, and prior-authorization list membership. It is clear what the tool is, though it never names the overlapping sibling 'pa_required_check', so an agent must infer from the description alone that this is the broader multi-element checklist rather than the single PA boolean.

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?

Useful operational cues are present ('Requirement definitions only; it takes no patient data', 'Some items are phased in by state: for those, paRequired is null until a state is given', which implies supplying state matters). However, there is no explicit when-to-use vs. when-to-skip framing and no named alternative among the many PA siblings, so routing is implied rather than stated.

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