Book a call with a lead

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

Goes well beyond the annotations: discloses the pre-flight availability check, the fallback of returning open slots when the requested one is taken, the idempotencyKey exception that skips the check, and the downstream effects ('moves the lead to booked and notifies the coach's webhook subscribers'). That is exactly the side-effect detail destructiveHint=true and openWorldHint=true only gesture at.

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?

Front-loaded with the most decision-critical constraint (no calendar event, no invite), then availability semantics, then confirm gating, then a concrete example. Dense but every clause carries operational weight; the example at the end is the only mildly expendable part.

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, open-world mutation with 8 parameters and a real output schema, the description covers side effects, preconditions, failure behavior, retry semantics and confirmation. There is no gap an agent would need to guess at.

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 baseline is 3, but the description adds real meaning: why provider matters for the availability read, that bookingTypeId must be an active google_calendar type, and how idempotencyKey changes retry behavior. It stops short of restating leadId/slotAt formats, which is fine because the schema covers them.

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?

Names a specific verb and resource ('Record a booked call for a lead in Luca') and immediately draws the boundary against what it is not: it does not create a calendar event or send an invite. An agent can distinguish it from bookkeeping siblings like luca_bookings_create without opening the schema.

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?

Explicitly states the precondition path ('book the call with the provider too, or have the lead book through the coach's booking link') and the confirm-gating rule ('pass confirm: true only after the coach approves this exact slot'). What is missing is any routing against the near-siblings luca_bookings_create, luca_bookings_availability and luca_reschedule_call, which an agent could easily confuse this with.

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