Roamward MCP

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world) with no contradiction. The description adds value beyond them: it discloses the return payload (ranked stops, detour minutes, nearby drives, planning link) and, unusually, licensing/attribution constraints for bulk extraction. No auth or rate-limit detail, but the addition is substantive.

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 lead sentence is promotional coverage statistics ('50 published drives today; strongest in the West and Southwest') that do not help an agent select or call the tool, and it occupies the front-loaded position. The genuinely useful content — return shape, slug source, license — is pushed behind it.

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 no output schema, the description carries the return-value burden and does so adequately (ranked stops, detour minutes, related drives, continue-planning link). A single required param is fully documented in the schema. The main gap is sibling differentiation, which belongs to purpose/usage rather than completeness.

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 one parameter and 100% schema coverage, baseline is 3. The description goes beyond the schema by stating the slug must originate from list_drives, which is provenance information the schema's 'Published /drives slug.' does not convey.

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 operative sentence is 'Find stops along a published road-trip route,' which names a plausible action but not the one implied by the title ('Get one published Roamward drive') — the framing blurs into the sibling search_stops. It never states which single drive is being retrieved or how it differs from list_drives or search_stops. Purpose is inferable, not crisp.

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?

'Use a slug returned by list_drives' gives an explicit prerequisite and names the upstream sibling, which is genuine when-to-use guidance. It also states usage terms (individual-assistant use with attribution; license required for bulk/commercial use). It stops short of exclusions versus search_stops or plan_drive.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, and the description adds genuinely non-annotated context: what the response contains and a licensing restriction on bulk extraction, redistribution, and commercial dataset use. It still says nothing about result volume, pagination, or geographic completeness beyond '50 published drives today'.

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 front-loaded with coverage/marketing prose ('strongest in the West and Southwest, with coverage growing in waves') before stating the actual purpose, which pushes the actionable sentence to second position. The licensing sentence earns its place, but the coverage framing is marginal.

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 no input parameters and no output schema, the description carries the burden of describing the return shape, which it does by enumerating endpoints, distance, driving time, stop counts, and links. Coverage breadth and the legal usage constraint are also stated, leaving little an agent needs that is missing.

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 tool takes zero parameters, so the baseline is 4. There is nothing for parameter semantics to obscure, and the description correctly avoids inventing filter arguments.

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 names a specific verb+resource ('Discover published U.S. road trips and drives') and lists what the result contains (endpoints, distance, driving time, stop counts, links), so an agent can tell this is a discovery/listing tool. It does not explicitly contrast itself with get_drive or search_stops, which keeps it out of 5 territory.

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 call this versus get_drive, plan_drive, or search_stops. The only scoping statement is a licensing/attribution constraint ('For individual-assistant use with attribution'), which governs usage rights rather than tool selection.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the bar is lower, yet the description adds real behavior: published endpoint pairs use stored routes while other pairs fall back to a bounded live lookup or published alternatives, and results are planning links, not bookings/navigation. Licensing and attribution constraints are also disclosed. Only rate-limit or latency details are absent.

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?

Information-dense and largely free of filler; the licensing sentence is long but earns its place as a constraint. The main structural weakness is that a coverage/limitations caveat leads the description, pushing the actual purpose statement into the second sentence rather than front-loading it.

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 no output schema, the description correctly explains what is returned (planning links, not bookings or live navigation), and it covers coverage scope, fallback behavior, and licensing. It is complete enough to call the tool correctly, missing only input-format hints for the required endpoints.

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 0% schema description coverage, the description must carry the parameter burden and largely does: it explains the detour budget values (15/30/60 minutes), the optional exclusion of stop categories (hideKinds), and implies from/to as trip endpoints. It does not specify acceptable input formats for from/to (city, address, coordinates), leaving a gap.

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+resource ("Plan a U.S. road trip") and names the differentiating capability (detour-aware stops within a 15/30/60 minute budget), which clearly separates it from get_drive, list_drives, and search_stops. It stops short of explicitly naming or contrasting those siblings, so it falls just below a 5.

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?

Usage is implied rather than stated: the agent learns the tool is for U.S. trip planning and that it returns planning links rather than bookings or navigation. Coverage guidance ("strongest in the West and Southwest") helps the agent judge applicability, but no explicit when-not conditions or alternative-tool routing are given.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful context beyond them: a 10-result cap, the fact that opening hours and closures are not verified, and geographic coverage limits. This is meaningful disclosure the annotations do not provide.

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 core purpose sentence is efficient, but it is preceded by a coverage/marketing sentence and followed by a licensing paragraph, so the operative information is not front-loaded. Roughly half the text is geographic framing and legal terms rather than invocation guidance.

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 no output schema, the description usefully states the return shape (up to 10 catalog matches with descriptions and links) and the key caveat about unverified hours. For a two-parameter search tool, this is close to complete, missing only query-matching behavior.

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 50% (only `state` is documented). The description partially compensates by clarifying that `query` accepts names or categories and that `state` is optional, but it adds no format or matching-behavior detail for `query` beyond what the schema already implies, so the baseline 3 applies.

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?

"Find road-trip stops by name or category, optionally within a U.S. state" gives a specific verb (find/search) and resource (stops) with the two filtering dimensions. It is clearly the search tool among the drive-oriented siblings, though it never explicitly contrasts itself with get_drive/list_drives/plan_drive.

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?

Usage is implied by "by name or category, optionally within a U.S. state," and the licensing paragraph effectively states a when-not-to-use condition (bulk extraction/redistribution). However, there is no explicit guidance on when to prefer this over the sibling drive tools or how to handle a query that returns nothing.

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