Direct Garmin API request

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds value by specifying the method is GET, that it returns unshaped payloads, and that it is a direct raw API call. This goes beyond the structured hints and sets accurate expectations about the output format.

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 compact, front-loaded with the core behavior, and every sentence earns its place: scope, path format example, and the prefer-dedicated-tool guidance. There is no filler or repetition of schema details.

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 an open-ended escape-hatch tool with a single parameter and no output schema, this is nearly complete: it explains when to use it, what it returns (unshaped payloads), and gives a realistic path example. The only minor gap is not detailing exactly whether the full base URL must be included, but the example implies the path starts at the service root.

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 only one parameter (path) and 0% schema description coverage, the description compensates by showing a concrete path example with placeholder syntax and query string. It clearly conveys that the tool expects an arbitrary API path beginning with a service segment, even though it does not exhaustively document path construction rules.

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 states a specific verb and resource: 'Call any Garmin Connect API path directly (read-only GET)'. It clearly differentiates itself from the many dedicated sibling tools by explicitly saying it covers endpoints those tools do not, and mentions the alternative behavior of preferring a dedicated tool.

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 gives explicit when-to-use guidance: for endpoints the dedicated tools do not cover. It also tells the agent to prefer a dedicated tool when one exists, and restricts usage to read-only GET operations, which is a clear exclusion.

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