national-parks-mcp-server

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

Annotations already declare readOnly and openWorld. Description adds caveat about empty results not being an error, which clarifies behavior beyond annotations. No contradictions. Does not discuss rate limits or pagination, but schema covers start/limit.

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 covering purpose, content, and a caveat. Front-loaded with action and output type. No filler, but the example question adds slight verbosity without major cost.

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?

Comprehensive for a query tool: describes return fields, dependency on park codes, edge case of empty results. Output schema exists, so return structure is further specified. Missing explicit pagination behavior but schema provides start/limit fields.

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 parameters are already documented. Description adds example use of query ('river', 'group', 'rv') and reminds to get park codes from another tool, but does not deepen semantic meaning beyond schema. Meets baseline for high coverage.

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?

Clear verb+resource: 'find campgrounds'. States exact fields returned (amenities, site counts, fees) and answers a concrete user question ('where can I camp at Zion, and can I get an RV hookup?'). Distinct from siblings like events or alerts; references nps_find_parks as prerequisite.

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?

Describes context of use (campground search) and explicitly points to nps_find_parks for codes. Warns that some parks return lodging/backcountry permits instead, so empty results expected. Does not name alternative tools to switch to, but the dependency is clear.

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=true and openWorldHint=true, so the read-only nature is covered. The description adds valuable non-obvious behavior: pagination is by page number (not offset), and the feed is sparse/inconsistent with empty results being normal. This beyond-annotation context helps an agent set expectations and handle responses correctly.

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 yet dense with information, front-loading the purpose and example before technical caveats. Each sentence serves a distinct purpose: what it does, what it returns, cross-reference to park codes, pagination behavior, and data quality warning. No wasted words.

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 an output schema exists, the description need not explain return values. It covers all critical call-time concerns: how to specify parks/states, date range usage, pagination method, empty-result semantics, and cross-tool references. For a tool with 7 optional parameters and a mutual-exclusivity constraint, this is complete for correct invocation.

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 each parameter documented, so the baseline is 3. The description adds extra meaning beyond the schema: it clarifies the mutual exclusivity of parkCode and stateCode ('Provide parkCode or stateCode') and explains pagination semantics ('paginates by page number, not offset'). This directly aids correct invocation.

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 finds scheduled events at a park within a date range, specifying event types (ranger programs, festivals, tours, interpretive events) and the exact answer it provides ('what's happening at Yellowstone this weekend?'). It distinguishes itself from sibling tools like alerts and campgrounds by the data it returns (title, dates, location, category, fee, registration links).

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 provides clear context for when to use the tool (e.g., 'what's happening at this park this weekend?') and explicitly instructs to get park codes from nps_find_parks. It also notes the events feed is sparser than alerts or campgrounds, implying alternative tools for those use cases, but does not explicitly say 'use nps_get_alerts for alerts' – leaving the differentiation slightly implicit.

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 and openWorldHint=true, which are generic. The description adds significant behavioral detail: local re-ranking for exact matches, that NPS returns results in alphabetical-by-code order with no relevance ranking, that the activity filter is a local substring match (the API has no activity param), and that totalCount reflects true matches across all parks. It also clarifies pagination semantics and coverage scope. These are exactly the behaviors an agent needs to interpret results correctly.

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 packed but efficient. The first sentence establishes purpose and the required-first-step role, then bullet-like details enumerate return contents, then a compact coverage clause. No wasted words; every sentence carries functional information. For an entry-point tool with five optional parameters, this length is justified and well-front-loaded.

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 complexity (5 optional params, no required, local filtering, re-ranking, ~470 sites) and the presence of an output schema, the description covers all critical usage scenarios: parameter combinations, edge cases (no query/stateCode), pagination behavior, and the relationship to detail tools. Nothing an agent needs to call this 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%, so each parameter already has a description. The description goes further: it explains the re-ranking nuance for query, the local filtering and totalCount semantics for activity, and the pagination behavior for start/limit. It also warns against paging through all sites with limit and suggests narrowing with query/stateCode. This adds genuine value 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 a specific verb ('Resolve') with a clear resource ('place name, US state, or free-text query to National Park Service parks') and immediately positions it as 'the required first step before the detail tools.' It lists exactly what is returned (parkCode, trip-planning summary) and explicitly names the sibling tools that depend on it, making differentiation trivial.

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 declares when to use this tool ('first step before the detail tools'), when to omit parameters ('Omit to browse by state'), and what happens with no parameters ('returns the first page of all ~470 NPS sites'). It also states exclusions ('not state parks and not Forest Service or BLM land') and recommends using at least one of query or stateCode. No ambiguity about usage 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 and openWorldHint, but the description adds value by explicitly stating the open-world behavior ('Not every park has a curated list; an empty result is not an error') and clarifying the curated vs. raw distinction. It does not contradict annotations and provides useful context beyond the structured fields.

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 dense but every sentence earns its place. It front-loads the core purpose and content, then clarifies the distinction, input constraints, and edge-case behavior. No redundancy or 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?

Given the tool has 5 params and an output schema, the description covers the key aspects: purpose, input requirements, empty-result behavior, and differentiation from a sibling. It does not clarify what happens if both parkCode and stateCode are provided (though schema implies 'or'), nor does it describe the output format in detail, but the output schema covers that. Overall, it's quite complete for an agent to use 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 description coverage is 100%, so baseline is 3. The description adds extra meaning: it emphasizes that parkCode is a single code (not a list), specifies that at least one of parkCode/stateCode is required, and cross-references nps_find_parks for obtaining park codes. These details go beyond the schema's descriptions, justifying a 4.

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 (returns curated activities) with a concrete use case ('what should I do at Acadia?') and lists the content fields. It explicitly differentiates from the sibling nps_get_park by noting the curated list vs. raw activity tags, making it easy for an agent to select the right tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the alternative (nps_get_park) and the condition that selects it (raw tags vs. curated list), and explicitly states the input requirement ('at least one is required' for parkCode/stateCode). It also sets expectations for empty results ('an empty result is not an error'), giving clear when-to-use and when-not-to-use guidance.

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 (readOnlyHint=true, openWorldHint=true) already establish the safety profile; the description goes well beyond this. It discloses ordering ('most-recent-first'), the exact semantics of empty results vs. empty pages ('An empty page with a non-zero totalCount only means start ran past the end'), the local-filter behavior of category, and a real-world caveat ('Closures and road conditions change daily — re-check before departure'). No contradiction with annotations — the read-only, open-world hints align perfectly with the described behavior.

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 main purpose is front-loaded in the first sentence with the key use-case poised as a question. The three sentences each earn their place: purpose+recency priority, usage routing, and output semantics. Dense but not bloated for a 6-parameter tool with non-trivial pagination and filtering semantics. Slightly compresses the category-local-filter detail into the schema, which keeps the main description lean.

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?

An output schema exists, so no obligation to explain return values. The description covers purpose, input routing (park vs. state, service-wide fallback), result interpretation (empty = good news vs. empty page = pagination overrun), recency ordering, and a freshness warning. For a tool with this complexity — 6 params, pagination, local filtering, cross-tool dependency — 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% (all 6 params described in schema with enums and defaults), so baseline is 3. The description adds real value beyond schema: it ranks category values ('Danger' and 'Park Closure' are the high-priority ones), explains that category filtering is applied locally vs. API-native, explains the meaning of totalCount under local filtering, and provides the nps_find_parks cross-reference for parkCode. This meaningful interpretation pushes it above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('get alerts') + resource (NPS alerts) + explicit scope ('for a park or a whole state') with the alert types enumerated (closures, hazards, caution notices, information). The sibling set (campgrounds, events, parks, activities) contains no alert tool, so the domain is auto-differentiated, and the description reinforces this by naming the exact resource. No ambiguity in what this tool does.

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?

Provides clear when-to-use context: 'Get park codes from nps_find_parks, or pass a stateCode for a statewide sweep' names the concrete alternative for obtaining input. It also tells the agent how to interpret outcomes ('an empty result with totalCount 0 means... good news, not an error'), which guides decision-making. It doesn't explicitly state when NOT to use this tool versus an alternative, but sibling domains are separated so cleanly by topic that explicit exclusions would be redundant.

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=true and openWorldHint=true, lowering the burden. The description adds value beyond annotations: single-request batching up to ten codes, the always-present core-field set vs. optional sections, and a pointer to the NPS page for anything not covered. No contradiction with annotations; 'get' aligns with the read-only hint.

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?

A single dense paragraph where every sentence earns its place: content list, code source, batching limit, and payload trimming. It is slightly longer than the leanest ideal but sharply front-loaded with the purpose and scoping guidance, with no filler or redundancy.

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 output schema documents return values and annotations cover safety, the description supplies the remaining operational context: content scope, batching, code acquisition, payload control, and a fallback pointer to the NPS page. A minor gap is behavior for invalid/unknown codes, but overall the 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% and both parameters are thoroughly documented: parkCode specifies format, examples, count range and batching; fields lists all enum values and the omit-for-all behavior. The description largely reiterates what the schema already states ('Get codes from nps_find_parks', 'single request'), adding little new semantic meaning beyond the structured definitions.

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-resource pair (get park detail by parkCode) and enumerates the full content sections returned (description, activities, topics, fees, hours, contacts, directions, weather, images, NPS page). This fully differentiates it from siblings like nps_get_alerts and nps_get_activities without needing to inspect their 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?

Provides concrete usage context: how to obtain valid codes (from nps_find_parks), that up to ten codes fetch in one request, and that the fields parameter trims payloads. It does not name explicit when-not-to-use conditions or alternative siblings for cases like current alerts, but the cross-tool routing to nps_find_parks is clear and actionable.

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