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

Beyond the annotations, the description discloses that the tool is stateless, returns the prior state with scores filled in, and does not save, publish or change a live tournament. It also sets output expectations (show time, court, pairs and who rests) and warns that future pairings cannot be known in advance, which is behaviorally important for a 'generate' tool marked read-only.

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 definition is front-loaded with the mandatory precondition and then proceeds through usage, output expectations and configuration advice. It is dense and long, but most sentences carry necessary routing or behavioral information; a few sentences, such as the example clarification, could be tightened without losing meaning.

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 stateless, multi-round tool with nested config and no output schema, the description covers the full calling contract: when to call, what to ask first, how to chain prior rounds, what to display in the returned round, and how to handle rests. An agent has enough information to invoke it correctly and avoid the common failure of inferring sport or format.

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 67%, and the description adds useful semantic guidance on key config choices: when to offer config.ranking=average, how to suggest a round count for equal rests, and setting config.restMinutes for breaks. It also explains the priorRounds workflow, though several schema-described fields such as seed, pointsPerMatch and startTime receive no additional description-level treatment.

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 states a specific verb and resource: generating a PADEL Mexicano round. It explicitly distinguishes itself from Americano and routes the agent to get_supported_tournament_options when sport or format is missing, so an agent can select it confidently among its siblings.

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?

It gives explicit preconditions (sport and format confirmed for this tournament), concrete when-not-to-call instructions (ask instead of inferring from player/court counts or defaults), and names the alternative discovery tool. It also covers ambiguous individuals versus fixed teams and when to suggest ranking or restMinutes, leaving little to inference.

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