podyx_v1_get_booking

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description does add real domain behavior beyond that: blocking slots are dropped from mixed purchases, original payment status covers only the first linked payment, and money can be null for historical or unpriced records. That is useful but narrower than it looks, and nothing is said about not-found handling or response shape for a tool declared openWorldHint=true.

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 verb and resource are front-loaded and the whole block is compact, but it degenerates into an undifferentiated run of caveats. The trailing quote-and-pagination sentence does not belong to a single-resource read and dilutes the sentences that do.

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 one nested parameter, no output schema and no parameter descriptions, the description carries the burden of explaining the returned booking. It covers the trickiest fields (money nullability, payment status scoping, omitted blocking slots) but leaves the rest of the booking object and error behavior undocumented.

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?

Only one parameter (path.id), and its uuid format is already conveyed by the schema, so the schema does most of the work despite 0% description coverage. The description echoes the path template but adds no meaning about which booking ids are valid or what happens when an id refers to an excluded calendar/blocker record.

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 and resource ('getBooking GET /api/v1/bookings/{id}') and then scopes what a booking record actually is ('Active session purchases, excluding calendar records and manual blocker-only records'). That scope statement implicitly separates it from podyx_v1_list_bookings, though it never names the sibling outright.

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?

There is no explicit 'use this when...' guidance and no comparison to podyx_v1_list_bookings or podyx_v1_get_session, which an agent must distinguish this from. 'Follow all pagination; a quote does not reserve a slot or lock a price' reads like boilerplate for a quote tool and does not tell the agent when to pick this endpoint.

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