get_zones_by_activity_id

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

With no annotations, the description carries the burden. It explicitly states 'Read-only operation' and lists required scopes, which is useful. However, it does not describe the response structure, error cases, or any Summit-specific limitations. The 'Summit Feature' hint is present but underdeveloped.

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 organized with endpoint, purpose, and scopes. It is front-loaded with the purpose and avoids fluff. The structure is clear and compact, though it could be tightened by merging the endpoint with the description.

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 simple GET with one parameter and no output schema, the description covers the basics. It lacks response shape details and any caveats about Summit availability. Given the low complexity, it is adequate but not comprehensive; an agent might need to fetch the activity to understand zones.

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% and the parameter 'id' is described as 'The identifier of the activity.' The description reinforces this by referencing 'a given activity' but adds no new semantic detail. Baseline of 3 is appropriate since the schema handles it.

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 'Returns the zones of a given activity' and names the endpoint. It is distinct from sibling tools like get_laps_by_activity_id, though it does not explicitly contrast them. The 'Summit Feature' label adds context. Clear verb+resource, but could be more explicit about what zones are.

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?

There is no guidance on when to use this tool versus alternatives. It provides access requirements (activity:read vs activity:read_all) but not usage context or exclusions. The description does not mention sibling tools or when to prefer another endpoint.

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