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

The readOnlyHint annotation already establishes safety, and the description adds meaningful non-obvious behavior beyond it: the dual-mode response (directory vs actual items), the default-to-signed-in-user behavior, and the slim-versus-full projection switch. No contradiction with the annotation.

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 compact sentences, front-loaded with the purpose, with every sentence earning its place (purpose, target resolution, dual-mode behavior, projection behavior). No fluff or repetition of schema content.

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 5-parameter tool with no output schema, the description covers the essential decision points: how to select a feed, how to target a user, and how the view parameter changes the response. Combined with the 100% schema coverage, an agent has what it needs to invoke correctly.

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 every parameter carries a description, so the baseline is 3. The tool description does add connective value by explaining the feed omission-to-directory behavior and the view projection default, but the schema already documents the enum values and response shapes in detail, so the description adds limited extra meaning.

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 a specific verb-plus-resource statement ('Get an AllTrails user's activity feed (recorded hikes and posts)') that clearly delimits the scope. It additionally clarifies the target resolution (signed-in user vs userId), which helps distinguish it from the sibling trail/GPX/list tools, though it never names an alternative explicitly.

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?

The description gives explicit conditional invocation context: omitting 'feed' returns the feed directory, passing 'feed' returns items, and userId defaults to the signed-in user. This is clear usage context with no ambiguity, though it offers no exclusions or named alternatives among the sibling tools.

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?

readOnlyHint already covers the read-only safety profile, and the description adds valuable behavioral facts beyond annotations: sparse item shape, default sort by curator order, compact vs full view semantics, and the explicit warning that trail details are not included. No contradiction with annotations.

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 the core action and input provenance, then gives the sparse-reference warning and return shape. Each sentence carries essential information with no filler or repetition.

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 read-only list-fetch tool with no output schema, the description adequately covers input provenance, output shape, default ordering, the full-view option, and the correct hydration path for trail details. Pagination is not mentioned, but the tool's simplicity makes that non-material.

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%, so the baseline is 3. The description adds meaning by explaining where listId comes from and that compact is the default view with slim sorted output. However, the view parameter's full behavior is already thoroughly documented in the schema, so the additional semantic value is moderate.

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 ('Get the trails saved in an AllTrails list'), identifies the required numeric list id and its source, and explicitly distinguishes the returned sparse items from trail details, pointing to alltrails_get_trail for hydration. This clearly separates it from sibling tools.

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 tells the agent when to use the tool: after obtaining a list id from alltrails_list_user_lists or a public list from alltrails_search. It also warns that items are not trail details and names alltrails_get_trail as the hydration alternative, so the tool selection versus siblings is explicit.

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?

Beyond the readOnlyHint annotation, the description adds the exact API endpoint and authentication requirement, which provides useful behavioral context. It does not detail any side effects or output format, but given the simplicity, it is adequate.

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 extremely concise with two sentences: the first states the action and resource, and the second adds authentication. No superfluous information.

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?

Given the tool has no parameters and no output schema, the description provides all necessary context: what it does, the underlying API, and a prerequisite. It is fully sufficient for an agent to decide when and how to invoke it.

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?

There are no parameters, and the schema coverage is 100%. The description does not need to add parameter info, but it does mention the endpoint, which aids understanding. A score of 4 is appropriate for a parameterless tool with sufficient context.

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 it gets the signed-in user profile using a specific verb ('Get') and resource ('user profile'). It distinguishes from sibling tools like alltrails_get_activity_feed and alltrails_get_trail, which are about different resources.

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?

The description includes a prerequisite ('Requires a signed-in session'), which guides when the tool can be used. It does not explicitly list alternative tools or when not to use it, but the context is clear and no sibling tool serves the same purpose.

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 mark readOnlyHint=true, and the description adds meaningful behavior beyond that: it explains default slim projection, how to request full records, and that geometry depends on higher detail levels. This gives an agent a clear picture of what the tool returns without over-explaining.

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?

Two sentences, front-loaded with the core purpose, then concise detail about default vs full output. Every sentence earns its place; no filler or redundant restatement.

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 enumerates the main return fields and distinguishes compact vs full responses. It is complete enough for a simple read-by-id tool, though the relationship between view:full and detail:offline for geometry is slightly clearer in the schema than in the description.

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 description coverage is 100%, so the schema already documents all three parameters and their enums. The description restates the default projection and the role of view/full, but does not add substantial semantic value beyond what the schema already provides.

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?

States a specific verb and resource: get details for a single AllTrails trail by numeric trail id. Clearly distinguishes this from siblings like alltrails_search and alltrails_get_trail_reviews by emphasizing a single trail identified by id.

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?

The description makes clear this is the right tool when you already have a numeric trail id and want trail details. It does not explicitly name alternatives or say when not to use it, but the by-id framing provides enough context to route an agent correctly.

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 declare readOnlyHint=true, and the description adds meaningful behavioral detail: the output is raw GPX XML, built from offline-detail route geometry, with per-point elevation. This goes beyond the annotation without contradicting it.

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 two sentences with no filler. It front-loads the core action and output format, then adds useful context about the document's content and intended use.

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 single-parameter, read-only export tool with no output schema, the description fully covers what the tool returns and how it can be used. Nothing essential is missing for an agent to invoke and interpret the result.

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%, with trailId already described as 'Numeric AllTrails trail id'. The description does not add parameter-level detail beyond the schema, so the baseline score of 3 is appropriate.

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 uses a specific verb ('Export') with a clear resource ('an AllTrails trail's route') and a concrete output ('GPX 1.1 document'). It clearly differentiates this tool from siblings like alltrails_get_trail or alltrails_get_trail_photos, as the GPX export purpose is unambiguous.

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?

The description clearly states the intended use case: obtaining a trail route as GPX for saving or importing into navigation apps. It does not explicitly name alternatives or exclusions, but the context is strong enough that an agent can infer when this tool is appropriate.

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 only declare readOnlyHint=true, which the description matches. The description adds real behavioral context: the default compact shape, that url is derived/signed and absent from 'full' mode, and that compact drops fields. This goes beyond what annotations alone convey.

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?

Two sentences, purpose first, with no filler. The return-shape detail earns its place since there is no output schema, though 'the whole records' is slightly vague.

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?

No output schema exists, so the description must own the return contract — it details the compact shape and the derived-url caveat, and the schema's view parameter fills in the 'full' semantics. Combined, an agent has enough information to call it correctly.

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% (both trailId and view are fully documented), so the baseline is 3. The description restates the numeric-id requirement and the view toggle but adds little semantic value beyond what the schema's view description already covers.

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?

States a specific verb ('Get'), resource ('photos'), and identifier ('numeric trail id'). The resource is clearly distinct from siblings like alltrails_get_trail, alltrails_get_trail_reviews, and alltrails_get_trail_gpx, so an agent can select it correctly without opening other schemas.

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?

The view parameter explicitly excludes route geometry and names the alternative ('No route geometry either way — that is alltrails_get_trail'), giving a concrete when-not-to-use signal. It doesn't cover when to choose this over sibling photo-adjacent tools, but the one stated exclusion is precise and actionable.

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?

The readOnlyHint annotation already covers safety, and the description adds valuable behavioral scope: returns compact { user, rating, comment } by default, view:"full" for whole records. It also clarifies what is NOT returned in the schema note. This goes beyond the annotation without contradicting it.

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?

Two tightly written sentences, front-loaded with the tool's purpose and followed by the essential response-shape distinction. No filler or repetition of schema content.

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 read-only tool with no output schema, the description supplies the default response shape, the full variant, and a sibling exclusion. The schema documents all parameters. Minor missing details like rating representation or empty-result behavior are not material for a simple review-list tool.

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 description coverage is 100%, so the schema already documents all three parameters. The description's mention of 'view:"full"' adds no meaning beyond the enum description. Baseline 3 is appropriate when schema does the heavy lifting.

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?

States a specific verb and resource: 'Get user reviews for an AllTrails trail by its numeric trail id.' It is clearly distinct from siblings like alltrails_get_trail_photos, alltrails_get_trail_weather, and alltrails_get_trail.

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?

The main description doesn't give broad when-to-use guidance, but the view parameter explicitly excludes route geometry: 'No route geometry either way — that is alltrails_get_trail.' This redirects agents to the correct sibling for geometry. Combined with the focused tool name, selection is clear enough.

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?

The readOnlyHint annotation already covers side-effect safety, but the description adds little behavioral context beyond restating the purpose. It does not mention what the weather overview includes, units, freshness, or availability, so an agent gets minimal extra transparency.

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 front-loaded sentence with no filler. It states the verb, resource, and input requirement clearly, achieving maximum efficiency.

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 one-parameter, read-only tool, the description provides the required identifier and the general return topic. Without an output schema, slightly more detail about what a 'weather overview' contains would be useful, but all information needed to make the call is present.

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 input schema already documents trailId as 'Numeric AllTrails trail id' with 100% coverage. The description repeats 'numeric trail id' without adding new semantic details such as how to obtain the id, valid ranges, or formatting constraints. 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?

The description names a specific verb (Get), a concrete resource (weather overview), and the key input (numeric trail id). It clearly distinguishes this tool from siblings like alltrails_get_trail_gpx or alltrails_get_trail_reviews by focusing on weather.

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?

The description makes the usage context clear: call this tool when you need the weather overview for a trail identified by numeric id. It doesn't explicitly name alternatives or exclusions, but the purpose is unambiguous enough for correct routing.

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 mark read-only and idempotent, and the description goes further by detailing exactly what the tool does externally: it fetches a small public URL through the bridge and reports bridge role, port, version, extension-link state, elapsed time, and a plain-English failure-mode hint. It also explicitly states 'Read-only, no auth required,' matching the annotations without contradiction.

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 the core action, then enumerates the diagnostic outputs, and closes with a clear usage directive. Every sentence adds necessary context for selecting and invoking the tool; there is no filler or redundancy beyond the helpful read-only/auth note.

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 zero-parameter healthcheck with no output schema, the description is remarkably complete: it names the exact URL being tested, lists the returned diagnostics, explains the failure-mode hint, and states the intended use case. An agent has enough context to invoke the tool and interpret its result without additional documentation.

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 input schema has zero parameters, so the baseline for this dimension is 4. The description correctly implies no input is needed by showing the fixed URL and the diagnostic nature of the tool, adding no irrelevant parameter guidance.

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 precise verb and resource: it 'round-trips a small public www.alltrails.com URL through the fetchproxy bridge' and returns diagnostics. This clearly distinguishes the healthcheck from sibling data-retrieval tools like alltrails_get_trail or alltrails_search.

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?

The description gives an explicit trigger: 'Call this when a real tool fails and you want to know which hop broke.' It also notes it is read-only and requires no auth, which clarifies safe invocation. It does not explicitly enumerate when not to use it, but the diagnostic purpose is unambiguous.

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?

The annotation readOnlyHint=true signals this is a read-only operation, so the description doesn't need to restate that. The description adds a subtle nuance: it says 'Defaults to the signed-in user; pass a userId to target a specific public profile,' which implies authentication might be needed for the default, but it doesn't clarify permission requirements (e.g., might fail for private profiles). This is minor additional context beyond the annotation, but it doesn't disclose potential errors or limits (e.g., pagination, rate limits), so a 3 is appropriate.

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, well-structured sentence that front-loads the core purpose and then adds the optional parameter context. It is concise with no fluff, though it could be slightly more compact by combining clauses. Overall, it earns its place.

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?

Given the tool's low complexity (single optional parameter), a high-coverage schema, and a read-only hint, the description is nearly complete. It explains the default behavior and how to target other users, which is essential for correct invocation. It doesn't cover potential edge cases like empty results or auth failures, but those are not strictly needed for a simple list tool.

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 already documents the userId parameter fully (100% coverage), including its type and default behavior. The description echoes this but doesn't add much new semantic value—it just restates the default. Since schema coverage is high, the baseline is 3, and the description meets it without going beyond.

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 the tool's purpose: listing trails marked as completed by an AllTrails user. It specifies the main resource ('trails'), the action ('List'), and the modifier ('completed'). It also distinguishes the default behavior (signed-in user) from an optional override (specific user ID), which helps differentiate it from sibling tools that list other user content (e.g., alltrails_list_user_lists) or fetch single trails (alltrails_get_trail).

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?

The description provides clear context on when to use the tool: to list completed trails for a user. It notes the default behavior (signed-in user) and when to pass a userId (to target a specific public profile). However, it does not explicitly state when NOT to use it or mention alternatives, such as using alltrails_list_user_lists for user-created lists, but the sibling list and tool names make the distinction inferable.

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?

The readOnlyHint annotation already indicates a safe read operation. The description adds useful context about favorites/custom lists and that userId targets a public profile, but does not describe return shape or pagination. No contradiction with annotations.

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?

Two concise sentences front-load the action and object, then provide the only necessary scope detail. There is no filler or redundant information.

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 read-only operation with one optional parameterachment, the description covers purpose, scope, and target-user selection. Return value details are not providedhol, but they are reasonably inferable for a list operation and no output schema exists to clarify further.

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 userId parameter description already states that it defaults to the signed-in user. The tool description reinforces this and adds the 'specific public profile' detail, but does not add substantial meaning beyond the schema.

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?

States the specific verb 'List' and the resource 'an AllTrails user's saved lists', with a parenthetical clarifying that it includes favorites and custom lists. This is distinct from siblings like alltrails_get_list_items, which operates on the contents of a single list.

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?

The description clearly explains the default behavior for the signed-in user and how to target a specific public profile by passing userId. It does not explicitly name alternatives or state when not to use this tool, but the context is sufficient for basic 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?

The readOnlyHint annotation already establishes safety, so the description needed to add behavioral nuance beyond that. It adds the critical caveat that the returned id is an Algolia search id, not the trail-listing id, and reveals what fields are returned (kind, coordinates, slug, disambiguation label). This is meaningful behavioral context beyond the annotation, though it does not detail error cases or coordinate formatting.

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 and well-structured: the core function and outputs come first, followed by a practical use case, then a critical caveat. Every sentence earns its place and none are redundant with the schema or annotations.

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 adequately explains what the tool returns: location records with kind, coordinates, URL slug, and disambiguation label. It also covers the most important integration gotcha (the Algolia id) and directs the agent to the correct next step for trail lookup. The parameter behavior is already fully documented in the schema, so nothing critical 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?

Schema descriptions cover all three parameters at 100%, so the baseline is 3. The description adds value beyond the schema by explaining the disambiguation use case ('which Oregon') and by clarifying that query results are location records rather than trail records. This helps an agent understand query intent more deeply than the schema alone.

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: 'Resolve a place name to AllTrails location records,' and enumerates the kinds of locations included (country/state/city/area/POI) plus returned fields. It clearly distinguishes this tool from trail-listing tools by noting the returned id is not the id those tools accept. This is unambiguous and differentiates from siblings like alltrails_search and alltrails_get_trail.

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?

The description explicitly states when the tool is useful, such as disambiguating 'Oregon' or fetching coordinates/slug. It also gives a direct routing instruction: feed the resolved name back into alltrails_search to find trails. This is strong practical guidance that tells an agent when to use this tool versus alternatives.

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 only declare readOnlyHint=true, so the description carries the behavioral burden and fully delivers. It discloses that lat/lng are ignored, geo-bias applies, the fallback behavior depends on signed-in account, and that results are capped client-side by default — all non-obvious behaviors the agent could not infer from schema or annotations.

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 the core purpose and each subsequent sentence earns its place by explaining a distinct behavioral nuance. Though it is detailed, it remains tightly organized with no redundant 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?

For a read-only search tool with no output schema and six optional parameters, the description covers all relevant behaviors: query semantics, type filtering, fallback, parameter deprecations, geo-bias, result shape, and default limits. Nothing an agent needs to call it correctly 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?

Schema coverage is 100%, but the description adds meaningful per-parameter semantics beyond the schema: lat/ng verified ignored, types only applied when query is provided and silently ignored on fallback, view affects response fullness, and limit is honored. This directly helps an agent choose parameter values correctly.

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 begins with a specific verb-resource pair, 'Search AllTrails by name,' and clearly differentiates this free-text search tool from sibling get/resolve/list tools. It explains the underlying suggestions endpoint and the result set can mix record types, making the tool's scope unmistakable.

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?

The description gives clear context on when to use the tool, such as when a free-text query is needed, and explains how to narrow results with types. It also documents the no-query fallback behavior, but it does not explicitly name sibling alternatives or state when not to use this tool in favor of, say, alltrails_get_trail or alltrails_resolve_location.

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