Raw Garmin API request

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that responses are returned as-is with no processing, and provides path format guidance, which is useful context beyond the annotations. It doesn't cover error handling or rate limits, but those are less critical given the annotation safety profile.

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, front-loaded with purpose, then usage guidance and an example. Every sentence earns its place with no redundancy or 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?

With full parameter schema coverage, strong annotations, and a clear escape-hatch role, the description covers the essential context: what it does, when to use it, and what to expect in the response. No output schema is needed because the response is intentionally raw, and the description explicitly says so.

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?

Input schema covers all 3 parameters with detailed descriptions and examples, so the description doesn't need to repeat them. It reinforces the path format with an example, but the main semantic payload already lives in the schema, so the description adds little beyond a baseline.

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 'Call any Garmin Connect API path directly' and clarifies its role as the escape hatch for ~130 endpoints without a dedicated tool, listing example data types. This clearly distinguishes it from the sibling-specific tools, which each target a single resource.

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?

Explicitly instructs to prefer a dedicated tool when one exists, citing easier-to-read output and validated arguments. It also gives a concrete example path and notes the response is raw, making the when-to-use decision unambiguous.

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