weekly_training_report

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral context: the tool has an external dependency on querySleepData, expects the caller to normalize results, and then produces a seven-day report with comparison. This is valuable beyond the annotations, though the report's exact output/return shape is not disclosed.

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 a single dense sentence front-loaded with 'MANDATORY SLEEP ROUTING' and a clear two-step procedure. There is no filler or repetition, though some terms like 'required wake-up-date range' and 'COROS_MCP_2' are under-explained—this is a completeness concern rather than a conciseness problem.

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 a complex nested parameter and no output schema, the description gives the essential workflow but misses important details: how the wake-up-date range is derived from endDate, what 'normalized' means for the sleep records, and what the seven-day comparison should contain. An agent can attempt the call, but several details must be inferred or discovered from external schemas.

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 schema documents endDate, and the description adds that officialSleepRecords should be 'normalized results' from querySleepData, which is useful semantic context. However, schema description coverage is only 50%, and the many nested sleep-record fields still lack explicit field-level meanings or normalization rules, so the description only partially compensates.

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 identifies the tool's action: 'build the seven-day report and comparison' and ties it to 'MANDATORY SLEEP ROUTING'. It is specific enough about the resource and outcome, though it does not explicitly differentiate this from sibling reporting tools like daily_training_briefing or summarize_planned_load.

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?

It provides a strong invocation procedure: 'first call COROS_MCP_2 querySleepData for the required wake-up-date range and pass normalized results as officialSleepRecords', implying this tool should not be called without prepared sleep data. However, it gives no explicit guidance on when to prefer this tool over alternatives, and it references querySleepData rather than the available sibling get_sleep_data.

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