trmnl_end_room_booking

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true; the description adds the concrete consequence — the booking terminates immediately at the current time and the room is freed — and warns it changes remote state. It remains silent on failure modes (already-ended booking, non-TRMNL booking) and on what the response contains.

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?

Effect and precondition are front-loaded in the first two lines, with the endpoint and the authorization caution at the end. The trailing 'Changes remote state or starts work. Run only within the user-authorized scope.' is somewhat boilerplate, but it is short and reinforces the destructive hint.

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 destructive, non-idempotent mutation with no output schema, the description covers what changes, when it may be used, and the remote-state/authorization caveat. Missing only edge-case behavior (what happens if the booking already ended) and any expectation for 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 50%, and the description adds only the endpoint template PATCH /api/apps/room_booking/{installation_id}/calendars/{id}/bookings/{booking_id}/end, which implicitly confirms how the three path identifiers are used. The 'profile' parameter is never mentioned, so the description does not fully compensate for the coverage gap; baseline 3.

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?

States a specific verb and resource ('End a booking in progress now') plus the effect ('Frees the room: the booking ends at the current time'). The precondition 'Only a booking made through TRMNL that is in progress' scopes it, but it never names the obvious sibling trmnl_cancel_room_booking, so the end-vs-cancel distinction must be inferred.

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?

Gives a clear applicability condition: the booking must be in progress and must have been created through TRMNL. That is real routing guidance, but there are no explicit exclusions and no named alternative for out-of-scope cases (e.g. future or externally-created bookings).

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