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

With no annotations provided, the description carries full behavioral burden. It discloses extensive details: optional providerId with auto-assignment strategy, titular provider preference, default public agenda, retroactive behavior (skips slot validation, sets status to completed, tags self_declared provenance, max 365 days), autoCharge effect, and auto-detection of past dates. This is exceptionally transparent.

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 dense but structured, with preconditions, usage guidance, and specialized behavior clearly stated in separate sentences. It is longer than average but every sentence adds value. Slight loss for being somewhat lengthy, but justified by the tool's complexity.

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 tool with 14 parameters, no output schema, and no annotations, the description covers most critical behavioral context: preconditions, slot validation, retroactive logic, and provider assignment. It falls short by not describing the return value or side effects like notifications, and it omits several parameter semantics. Overall, it is quite complete for a complex booking 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 coverage is 0%, so the description must compensate. It explains key non-obvious parameters: providerId, publicAgendaId, retroactive, autoCharge, and retroactiveStatus (implied via 'completed by default'). However, it does not mention duration, modalidad, notes, or idempotencyKey, leaving some parameters semantically undocumented. Still, it adds substantial meaning beyond the schema.

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 opens with a specific verb+resource: 'Create a new session/appointment for a client.' It immediately distinguishes this from sibling tools by detailing unique behaviors such as provider auto-assignment, agenda selection, and retroactive booking. The scope is clear and unambiguous.

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?

The description explicitly names preconditions and related tools: 'Use availability_get_slots to find valid time slots before calling this' and 'client must exist (use client_create first).' It also explains when to use retroactive and autoCharge flags. This gives concrete guidance on when and how to invoke the tool.

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