create_reservation

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

No annotations are provided, so the description carries the full burden of behavioral disclosure - and it does so well. It discloses that this is a state-changing operation consuming real capacity, explains default behaviors (template/region default to first available, start defaults to now, days defaults to 2 and may be policy-capped), and specifies the return value and follow-up polling. It's strong given zero annotation support, though it could mention idempotency or permission/authentication requirements.

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 description is genuinely dense but compact - a single paragraph that front-loads the critical side-effect warning before anything else. Every sentence adds value: safety warning, prerequisite validation, parameter defaults, and post-call behavior. Slightly long but warranted given the state-changing nature and 8 parameters; the warning is appropriately first.

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 complex mutation tool with 8 parameters, 0% schema coverage, and no annotations, the description is thorough. It covers prerequisites (reservable vs umbrella collection), all default behaviors, the success return, and the verification workflow (poll get_reservation). An output schema exists, so return details are partly covered there. It doesn't address error conditions or what happens on failure, leaving a small gap for a state-changing 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 description coverage is 0%, so the description must compensate, and it substantially does. It explains the meaning and data sources for template (deployment variant), region_name (region), start (ISO timestamp), and days (duration/cap). It doesn't explain collection_id, name, purpose, or description in depth, but since collection_id/name are self-evident and tied to required fields, this is a solid compensation for the 0% schema coverage.

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 clearly states the tool creates a reservation from a collection, with a specific verb (create), resource (reservation), and source (collection). It distinguishes from siblings like list_reservations and get_reservation by making the mutating/write nature explicit. However, the purpose is somewhat intertwined with behavioral caveats rather than being a crisp standalone purpose 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?

Excellent when/when-not guidance: explicitly warns it changes state and consumes real capacity, instructs to always confirm collection/name/region/duration with the user first. Also differentiates from alternatives by noting get_collection is the upstream source and get_reservation is the downstream poll target. This is clear usage context with explicit exclusions (umbrella collections are called out).

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