search_players

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

With no annotations, the description carries full responsibility for behavior, and it is exceptionally transparent. It discloses the 500-row maximum, absence of pagination, the truncated flag, the intentional mismatch between limit and total_found, and a concrete performance hazard. This goes well beyond what a typical description provides.

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 well-structured: a one-sentence purpose statement followed by compact, dense operational paragraphs. Every sentence earns its place by conveying a distinct fact; there is no repetition or filler.

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?

Even without an output schema, the description covers the essential context: required input, response size limits, truncation behavior, interpretation of result fields, and disambiguation guidance. An agent has enough information to invoke the tool correctly and interpret its response.

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?

The input schema has no descriptions, so the description must compensate. It does: name is explained as a required surname or partial-name matcher, and limit is specified as shortening only the players list while total_found remains the true page count. Both parameters receive meaningful, non-obvious semantics.

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: it searches for players by surname or partial name. This clearly differentiates it from sibling tools like search_tournaments and get_head_to_head, and from get_player, which implies retrieving one specific player.

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 gives strong operational guidance: name is required or the site returns a huge 6.7 MB list, queries must be narrowed when truncated is true, and namesakes should be disambiguated by city and rating. It does not explicitly name alternative tools, but the context is clear and actionable.

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