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

With all annotations set to false, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals preservation of locks/checkpoints/cutoffs/GAP, that it returns bounded canonical alternatives plus a private planning_report artifact, and that it never replaces sources, selects evidence, accesses Strava, or silently retries with permission. This goes well beyond the annotations and is directly useful for an agent deciding whether this tool has side effects.

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 dense but every sentence earns its place: purpose, defaulting behavior, preservation guarantees, prerequisites, permission requirements, return boundaries, and diagnostic follow-up. The structure front-loads the core purpose and then layers constraints and exclusions in a logical order without repetition.

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 tool with five parameters, two required IDs, experimental options, and important side-effect boundaries, the description covers prerequisites, defaults, permission semantics, output shape, and next steps for diagnostics. The existing output schema can carry return-value detail, so the description's level of contextual coverage is complete.

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 80%, so the baseline is 3, but the description enriches parameter meaning beyond the schema. It explains split_percent's inclusive range and default, clarifies that estimation_model v3 is experimental and must match the stored profile model, and adds that artifact IDs must be current v3 and that allow_profile_preparation never authorizes source replacement. This gives agents context the schema alone does not.

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 opens with a specific verb and resource: 'Compare all nine existing intensity/shape combinations without an elapsed goal.' This clearly distinguishes the tool from siblings like assess_finish_time_goal and compare_execution, and the closing caveats ('not an applied/exportable plan or chosen winner') further delimit its purpose.

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 usage context: it requires current v3 course and runner artifact IDs, defaults, and explicit approval conditions for experimental options. It also routes follow-up diagnostics to get_artifact with report_artifact_id. However, it does not explicitly name sibling tools or state when to prefer this over create_race_plan or compare_execution, though the exclusions strongly imply it.

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