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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered. The description adds genuinely non-obvious behavior: that a missing feed argument returns a DIRECTORY rather than items, and that output is slim by default with an opt-in to full records. It does not mention permissions or rate limits, which is a minor gap.

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 front-loaded sentences with no filler: identity/scope first, then the userId and feed branching, then the view default. Each sentence carries a distinct decision the caller must make.

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 steps in to explain the two possible return shapes (directory vs items) and the compact/full projection. Pagination via cursor and maxItems is left to the schema, which is adequate, though a top-level note on paging would fully close the loop.

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 schema descriptions already explain feed values, the omit-to-list-feeds behavior, view compact/full shapes, and user id defaults. The description largely restates those semantics rather than adding new detail, 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?

States a specific verb+resource ('Get an AllTrails user's activity feed') and immediately scopes it to 'recorded hikes and posts'. It is clearly distinguishable from siblings like get_profile, list_completed_trails, and list_user_lists.

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?

Gives explicit selection rules: omit userId to use the signed-in user, pass it to target a public profile, omit feed to get the directory and pass feed to get items. It doesn't name alternative sibling tools for related data, but the in-tool branching guidance is strong.

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 readOnly/idempotent/openWorld, so the bar is lower. The description adds real context beyond them: items are sparse references rather than trail details, entries are sorted by curator order by default, and view:"full" returns raw records in arrival order. It does not mention pagination or item-count limits.

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?

Front-loaded with the core action and id source, then the return-shape caveat. Two dense sentences with little waste, though the view explanation overlaps the schema's own 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?

With no output schema, the description steps in to describe the returned fields, their sparsity, and sorting. An agent has enough to call it correctly and know it must hydrate trail details separately.

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 view enum is thoroughly documented in the schema itself, so the description's summary of compact/full largely restates it. Baseline 3 is appropriate when the schema carries the parameter burden.

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+resource ('get the trails saved in an AllTrails list') with the keying input (numeric list id). It explicitly differentiates from siblings by naming alltrails_list_user_lists and alltrails_search as id sources and alltrails_get_trail as the hydration path for trail details.

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?

Gives clear provenance for the list id and a routing rule ('hydrate with alltrails_get_trail'), plus when to switch to view:"full". It stops short of an explicit when-not-to-use statement, but the alternative-tool routing is concrete.

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 readOnlyHint, idempotentHint and openWorldHint, so safety is covered. The description adds genuinely useful context beyond them: the auth requirement, the default response scope, and the fact that the full view exposes email and account settings (a sensitive-data disclosure the annotations don't 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?

Three sentences, front-loaded with the action and endpoint, followed by the precondition and the return-value/parameter detail. No filler and nothing repeated unnecessarily.

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 by enumerating the default identity fields and noting what the full view adds. Auth requirement, default behavior and the single parameter's effect are all covered, so an agent has everything needed 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%, so the baseline is 3, but the description goes further by tying the enum choice to concrete output differences: compact yields only the listed identity fields while full returns email and settings. This makes the practical consequence of the parameter clear even without opening 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 a specific verb (get) and resource (the signed-in AllTrails user profile), and even names the backing endpoint (/api/alltrails/me). No sibling tool touches the user profile, so an agent can distinguish it immediately from the trail/list/feed 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?

Explicitly states the precondition (requires a signed-in session) and when to choose the non-default behavior (pass view:"full" for the whole record). There is no competing sibling to name as an alternative, so the only missing piece is an explicit when-not-to-use clause.

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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description goes beyond them by disclosing that the response is a slim projection by default, what exactly that projection contains, and that route geometry is only fetched when both view:"full" and detail:"offline" are set — a genuinely useful behavioral detail. It does not cover error behavior for invalid ids.

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 verb and resource, and appropriately sized. There is minor redundancy: the field list appears twice (once as the general return set, once again as the compact projection), which costs a few words without adding 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?

There is no output schema, but the description compensates by naming the returned fields and explaining the compact/full shapes and the geometry dependency, which is enough for an agent to call and interpret this read-only tool. Missing only edge-case behavior (invalid or unknown trail ids).

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 trailId, view and detail in detail. The description largely restates the default projection and the view:"full" behavior that the view parameter's own schema text already specifies, adding only a mild emphasis on the view+detail interaction for geometry. Baseline 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?

States a specific verb and resource ("Get details for a single AllTrails trail by its numeric trail id") and enumerates the returned field set, which cleanly separates it from siblings like alltrails_get_trail_gpx, alltrails_get_trail_reviews, alltrails_get_trail_photos and alltrails_get_trail_weather. An agent can identify this as the canonical trail-detail call without opening any other schema.

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 explains when to choose view:"full" over the default projection, which is useful parameter-level guidance, but it never states when to call this tool instead of, or in addition to, its many siblings, nor any prerequisites (e.g. resolving a trail id first via alltrails_search). Usage is implied by the tool name rather than stated.

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 (readOnlyHint, idempotentHint, openWorldHint). The description adds real behavioral context beyond them: the data is built from offline-detail route geometry, contains track points with per-point elevation, and returns raw XML rather than a JSON envelope. It stops short of noting failure modes (e.g., trails lacking route geometry) or payload size.

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 tight sentences with no filler. Purpose and format come first, the provenance detail second, and the return-value note last — a well front-loaded structure for the reader.

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 carries the burden of describing the return value (raw GPX XML, track points with elevation) and its intended destination. It is nearly complete; only edge cases like trails without geometry or output size limits are unaddressed.

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% and there is a single required parameter (trailId, numeric string). The description adds no syntax or format detail beyond what the schema already documents, 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?

States a specific verb (export), resource (AllTrails trail's route), and output format (GPX 1.1 document with per-point elevation). This distinguishes it cleanly from sibling alltrails_get_trail, which serves structured trail data; the format-specific framing makes the boundary obvious.

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 phrase 'suitable for saving to a .gpx file or importing into navigation apps' implies downstream usage, but there is no explicit when-to-use-this-vs-alltrails_get_trail guidance or exclusion criteria. Usage is implied rather than stated.

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 readOnly/idempotent/openWorld, so the bar is lower, and the description still adds real behavior: the default shape is trimmed, and the 'url' is a derived/signed field that 'full' records do not contain. It stops short of stating auth needs or rate limits, but the response-shape nuance is valuable.

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 action and identifier, then the response-shape caveat. No filler, though the second sentence is slightly run-on and mixes return format with parameter 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 carries the return-value burden and does so by naming the per-photo fields returned by default. It omits pagination or the enclosing count structure that the schema mentions, but an agent has enough to call 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% and the enum is already documented in the schema, so baseline is 3. The description does clarify that 'url' serves the actual image and that 'full' returns whole records, but this largely restates what the schema's view description already says.

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 photos for an AllTrails trail') plus the identifier needed ('by its numeric trail id'). The resource is unambiguous against siblings like alltrails_get_trail_reviews or alltrails_get_trail_weather, but the description itself never names an alternative to route the agent.

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?

Implies usage by describing the default response and when to switch to view:"full", but gives no when-to-use / when-not-to-use framing or pointer to sibling tools for adjacent data (reviews, gpx, weather). The agent must infer context from the tool name.

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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds default-vs-full response behavior, but no auth requirements, rate limits, pagination behavior, or failure modes beyond that, and the response detail it gives is already present in the schema's view description.

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, zero filler, and the core action plus return format are front-loaded. Nothing in the description is padding, even if the second clause partly mirrors the schema.

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?

There is no output schema, so the description does useful work by naming the default per-review fields and the view:'full' alternative. It omits the wrapping 'count' field and any note on default limit/pagination, which a caller iterating over results would want.

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% and the view enum is fully documented in the schema, including the compact field list and the note that no route geometry is returned. The description's restatement of the compact shape adds little beyond the schema, 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?

States a specific verb and resource ('Get user reviews for an AllTrails trail') and keys it to a numeric trail id. The resource ('reviews') is clearly distinct from siblings like alltrails_get_trail_photos or alltrails_get_trail_weather, though no sibling is named 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?

Usage is only implied: it says to supply a numeric trail id. There is no statement of when to prefer this over alltrails_get_trail or how it relates to other trail-fetching siblings, so the agent must infer the selection context.

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 readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds nothing behavioral beyond that: no indication of whether the weather is current conditions or a forecast, what time horizon or units apply, or how fresh the data is. For a data-fetch tool with no output schema, this leaves a real gap.

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?

One sentence, front-loaded with the verb and resource, with zero filler. It is efficient, though arguably too terse to carry the missing behavioral detail.

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?

The tool is simple (one required parameter, no nesting) and annotations cover the safety profile, so the definition is minimally sufficient. However, with no output schema and no statement of what the weather overview contains (current vs. forecast, units, horizon), the agent cannot predict the response shape.

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% and the single trailId parameter is fully documented in the schema with a numeric pattern. The description's phrase 'by its numeric trail id' merely echoes the schema, so baseline 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 states a specific verb and resource ('Get the weather overview for an AllTrails trail') and pins the identifier format to a numeric trail id. It is clearly distinct from sibling readers like get_trail_reviews or get_trail_photos, though it never explicitly differentiates itself from them or from 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?

There is no guidance on when to call this versus alltrails_get_trail or the other trail sub-resource tools, and no prerequisites or exclusions are stated. The only usage signal an agent can infer is from the tool name itself.

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 cover readOnly/openWorld/idempotent, and the description adds real value on top: 'Read-only, no auth required,' the enumerated diagnostic outputs (role, port, version, extension link states, elapsed time, hint), and the four failure modes the hint distinguishes. With no output schema, this disclosure is exactly what the agent needs.

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?

Front-loaded with the action and endpoint, then the return payload and trigger condition. It is a single very long sentence with nested parentheticals, which is dense to parse, but nearly every clause carries 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?

A zero-parameter diagnostic tool with no output schema, yet the description fully describes the return payload and the meaning of each diagnostic state. Nothing needed to call or interpret it 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, which is the baseline-4 case. The description correctly signals no inputs are needed, though there is nothing further to specify.

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 ('Round-trips a small public URL through ContextMint Bridge') plus the exact endpoint used and the diagnostics it produces. It is unmistakably a connectivity/diagnostic tool and cannot be confused with any of the alltrails_* data siblings.

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 says when to call it: 'Call this when a real tool fails and you want to know which hop broke.' The condition that selects this tool over the data-retrieval siblings 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?

Annotations already cover readOnly/idempotent/openWorld, so the bar is lower. The description adds real behavioral context: default response is slim summaries (name, length, elevation, difficulty, rating) and view:"full" returns whole records. It does not cover pagination or result limits for a potentially long completion history.

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 tight sentences with zero filler, front-loading the core action, then targeting rule, then return-shape control. Every sentence 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?

With no output schema, the description usefully pre-announces the return shape (slim summary fields vs full records) and the default user scoping, which is enough for correct invocation. Minor gap: no mention of pagination or how the trailing result set is bounded.

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 both view and userId are already well documented (enum values, compact vs full shapes, numeric userId pattern). The description restates the userId default and view:'full' behavior but adds no syntax or format detail beyond the schema. 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?

States a specific verb+resource: 'List the trails an AllTrails user has marked completed.' This is clearly distinguishable from siblings like alltrails_search (discovery), alltrails_get_list_items (user lists), and alltrails_get_trail (single trail detail).

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?

Gives clear selection context: defaults to the signed-in user, or pass a userId to target a specific public profile. It does not explicitly name an alternative tool or state when not to use this one (e.g., vs. alltrails_get_activity_feed), but the targeting rule 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?

Annotations already declare readOnlyHint, openWorldHint and idempotentHint, so safety is covered; the description adds real value on top by specifying the default response shape (slim { id, name, itemCount, visibility }) and that userId only resolves public profiles. It does not cover pagination or rate-limit behavior for a feed-style list, leaving a minor gap.

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 tight sentences with the core purpose, targeting rule, and return-shape choice front-loaded in that order. Every clause carries information the agent needs and none is padding.

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 takes on the burden of explaining return values and does so for both view modes, while annotations handle safety. The only unaddressed element is pagination/limits for potentially long list sets, which keeps it from a 5.

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 baseline is 3; the description earns an extra point by adding the 'public profile' constraint on userId and by restating the compact-vs-full tradeoff in terms of the actual returned fields. It repeats the default values the schema already documents but adds a genuine targeting restriction.

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 ('List an AllTrails user's saved lists') and immediately scopes it with examples ('favorites, custom lists'). It clearly separates itself from alltrails_get_list_items, which it points to for the item-level detail rather than duplicating.

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?

Gives clear selection context: omit userId for the signed-in user, pass userId to target a public profile, and use alltrails_get_list_items if you need the contents of a returned id. It stops short of stating any exclusion or when-not-to-use case, so it falls just under the 'explicit when/when-not' bar.

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 readOnly, idempotent, and open-world, so safety is covered. The description adds genuinely non-obvious behavioral context: the returned id is an Algolia search id and is NOT accepted by the trail-listing tools. It omits pagination/result-count behavior, which the limit param partly implies.

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?

Front-loads the core action and return shape, then adds the disambiguation use case and the critical id caveat as a compact NOTE. No redundant or filler sentences.

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 contract (kind, coordinates, URL slug, disambiguation label) and warns about the misleading id field. That covers everything an agent needs to call it and correctly consume 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%, so query, kinds, and limit are fully documented in the schema with examples and defaults. The description restates the kinds set but adds no syntax or format detail beyond it, so the baseline of 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?

Specific verb+resource (resolve a place name to AllTrails location records) with the returned fields enumerated and the place kinds named. It clearly separates itself from alltrails_search, which handles trails rather than place resolution.

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?

States when it is useful (disambiguating which 'Oregon', fetching coordinates/slug) and explicitly routes the agent elsewhere for trail lookup ('feed the resolved name back into alltrails_search'). Both the when and the alternative are named.

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 read-only/open-world/idempotent safety, yet the description adds material behavior beyond them: lat/lng are verified ignored by the API with a date-stamped verification, results carry an implicit account/IP geo bias instead, the no-query path falls back to legacy explore anchored to the signed-in account's location, and results are capped client-side. These are exactly the non-obvious traits an agent needs.

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 front-loaded with the core search behavior before the caveats, and every clause carries real content (endpoint identity, type narrowing, deprecation, fallback, view modes). It is a single long block with em-dash-heavy nesting, which costs some scannability but no sentence is filler.

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 present, the description steps up and describes return shape (slim per-result summaries capped at limit, or full AllTrails records under view:"full"). Combined with the fallback and geo-bias disclosures, an agent has everything needed to call this correctly given the tool's complexity.

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 baseline is 3, but the description goes further by explaining that lat/lng are backward-compatibility only and effectively no-ops, and that the account/IP geo bias substitutes for them. The types-only-applied-with-query rule is largely mirrored in the schema, so the net gain over structured data is moderate rather than decisive.

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?

Opens with a specific verb+resource ("Search AllTrails by name") and immediately names the mechanism (the suggestions endpoint the site's own search box uses). This is clearly distinguishable from siblings like alltrails_get_trail, alltrails_resolve_location, or alltrails_list_user_lists, which are retrieval/filter tools rather than free-text 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?

Gives clear operative guidance: pass types=["trail"] to narrow mixed record types, and pass view:"full" for whole records. It also explains the no-query fallback behavior, which tells the agent when the tool behaves differently. It does not, however, route the agent to a sibling alternative (e.g. resolve_location or get_trail), so the comparative guidance is incomplete.

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