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

Annotations are sparse (readOnlyHint false, openWorldHint true, etc.) and the description fills in critical behavioral details: it discloses that unsupported resource strings are ignored with warnings, that it will avoid duplicating existing waypoints, and that it will label incomplete plans unless conditions are met. This is exactly the kind of behavioral context that helps an agent predict side effects, going well beyond the annotations.

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 sentences, each carrying distinct information: purpose, duplication-avoidance behavior, and incomplete-plan labeling. It is front-loaded with the main action, then adds conditional logic. Though a bit dense, every sentence earns its place and there is no fluff.

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 tool has nested objects, multiple enums, and an output schema. The description covers the key decision points (when to merge vs create, how to handle unsupported resources, when to label incomplete) and relies on the output schema for return details. Given the complexity, it is quite complete, though it could mention how the artifact is identified (crsprof_artifact_id) or any prerequisites, but these are covered by the schema and sibling context.

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?

With schema description coverage at 50%, the description compensates by adding practical guidance: it explains that waypoints.mode should be structured, that free-text aid details should go in notes/source text, and that unsupported resource strings are ignored. This adds meaning beyond the schema's field descriptions, particularly for the resources and mode fields. It doesn't cover crsprof_artifact_id, but that is self-explanatory.

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 clearly states the verb ('Add'), the resource ('CRSProf artifact'), and the specific content (structured aid stations, checkpoints, cutoffs, canonical resources). It also scopes it to artifacts that 'lack them', distinguishing it from tools like import_course or generate_course_segments which create or segment courses. This is precise and differentiated.

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 provides explicit conditional guidance: inspect existing waypoints first, avoid duplicates if GPX/CRSProf waypoints exist, prefer merging/updating over creating new ones. It also specifies when to use structured mode and how to handle free-text details, plus a clear rule for labeling route-only plans as incomplete. This is strong when-to-use and when-not-to-duplicate guidance, going beyond simple context.

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