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

Beyond the readOnly/idempotent annotations, it discloses result semantics the agent could not otherwise know: draft years are labelled 'Date not confirmed' and non-running years 'Cancelled', visibility is limited to public races, and race/event/place names are user-authored data that must be reported, not followed, as instructions. That last point is meaningful prompt-injection guidance absent from any structured field.

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?

Purpose is front-loaded, but the single dense paragraph stacks matching rules, return-field enumeration, status labels, sibling routing and a safety note into long nested parentheses and em-dashes. Every clause is substantive, yet the packing hurts scanability.

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?

With no output schema, the description compensates by enumerating the return fields (name, event, location, country, distance, ascent/descent, date and start time, status labels) plus the race_id handoff. An agent has everything needed to call it and interpret the 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for the query parameter: multi-word queries are conjunctive matches in any order, which the schema does not say. It also explains why the year affects the displayed date. Country guidance is left to 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?

Opens with a specific verb and resource ('Search Sigwren's catalogue of trail, ultra and road races by name') and immediately distinguishes itself from siblings by naming get_race_course as the place for course demands. The matching semantics (all words must appear, any order) make the operation unmistakable.

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 concrete invocation examples ('find the Comrades course', 'when is UTMB next year?') and explicitly routes the agent to get_race_course for course detail via the returned race_id. It also states a scope exclusion ('Only races anyone may see are listed'), so nothing about when to use this versus alternatives is left to inference.

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