Resolve a race event course and its synced geometry

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

With no annotations, the description carries the full behavioral burden and does well: it discloses that absent geometry produces an explicit caveat to prevent stale reuse, and that the result reports whether geometry was synced. It does not explicitly state read-only behavior or error handling, but the 'resolve and return' framing plus the safety caveat is meaningfully 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?

Three dense sentences deliver the result, the safety caveat, the optional diff behavior, and the prerequisite. There is no filler or repetition of the title; every sentence earns its place.

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?

The description covers inputs, high-level outputs, the stale-geometry caveat, and the prerequisite data source. The lack of an output schema means the description is responsible for return semantics, and it provides the key return elements (courseId, sync status, caveat) even if it does not detail the exact shape or the diff output structure.

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 description coverage is 0%, and the description fully compensates: eventId is identified as a Garmin/Intervals eventId, pastActivityId is explained as the activity to diff against, and athleteId is explained as a required value from list_athletes. Every parameter gains meaning beyond the raw schema types.

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 ('resolve'), a specific resource (race event course), and the exact result (courseId plus sync status). It is clearly distinct from all sibling tools, which focus on recovery, hydration, or data analysis rather than event course resolution.

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 clear invocation context: pass a Garmin/Intervals eventId, optionally pass pastActivityId for a diff, and obtain athleteId from list_athletes. It does not name explicit alternatives or when-not-to-use cases, but the prerequisite and scenario are concrete enough for an agent to select this tool appropriately.

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