openchargemap-mcp-server

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

Beyond the annotations (readOnlyHint=true, openWorldHint=true), the description discloses important behaviors: the tool is coordinate-native and does not geocode, and results are paginated with a nextOffset. It also notes that results include 'registry operational status' and 'last-verified date', hinting at data freshness. While it doesn't explicitly warn about stale status data, that nuance appears in the schema for statustypeid, so the description carries sufficient 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 about 150 words and every sentence contributes: purpose, spatial modes, geocoding caveat, filter summary, ID resolution, result fields, and pagination. It is front-loaded with the main verb and well-structured. It is slightly longer than minimal but appropriate for the tool's complexity, with no 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?

Given the tool's complexity (15 params, nested objects, output schema), the description covers all critical aspects: search modes, spatial prerequisites, filter capabilities, how to resolve IDs, result content, and pagination. It also references sibling tools where needed. The schema handles detailed parameter constraints and the output schema covers return structure, so the description is complete for selection and 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?

The schema has 100% coverage with detailed per-parameter descriptions, so the baseline is 3. The description adds value by summarizing the filter categories ('connector type, minimum power (kW), operator/network, usage type, charge level, operational status, and minimum charge points') and by reinforcing how to resolve IDs with openchargemap_lookup_reference, including an example ('CCS' -> 33). This high-level orientation helps the agent reason about which parameters matter, even though the schema already has full detail.

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 what the tool does: 'Find EV charging stations from the global Open Charge Map registry near a point or within a bounding box.' It uses a specific verb (find) with a clear resource (EV charging stations) and scope (global registry, spatial search). It also distinguishes from sibling tools by focusing on search/listing, while siblings get a station, get comments, or look up references.

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 explicit guidance on when and how to use the tool: it requires prior geocoding ('does not geocode place names — resolve a place like "Ballard, Seattle" to coordinates with openstreetmap_geocode first'), and tells users to resolve filter IDs via openchargemap_lookup_reference. It also explains pagination ('repeat the same search with the reported nextOffset'). This goes beyond general context and gives actionable workflow steps.

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 annotations (read-only, open world, idempotent), the description discloses the comprehensive nature of the response (every connection, operator, restrictions, etc.) and warns about the potentially large unpaged response when includeComments is true. This adds valuable behavioral context.

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 composed of three focused sentences. The first states the core purpose, the second enumerates key return fields, and the third explains the optional parameter and its trade-off. Every sentence contributes meaning without 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?

With a detailed output schema present, the description still delivers a thorough overview of the returned data, the optional includeComments behavior, and a clear warning about response size. It is complete and self-sufficient for an agent to understand when and how to use this 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 coverage is 100%, and both parameters have detailed descriptions. The tool description adds minimal new parameter-level information beyond what the schema already provides, so the baseline 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 explicitly states 'Get the full record for one Open Charge Map station by its numeric OCM ID,' using a specific verb and resource that clearly distinguishes it from siblings like find_stations or get_station_comments. The scope 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 provides clear guidance for the includeComments option, explicitly recommending the alternative openchargemap_get_station_comments when a large volume of comments is expected. However, it does not explicitly contrast with find_stations, though the purpose makes the distinction obvious.

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 the tool as read-only and idempotent, so the description focuses on adding behavioral context: it discloses that results include driver-recorded outcomes and registry status, and it explains pagination behavior (page truncation and nextOffset continuation). This goes beyond what annotations state.

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 front-loaded sentences convey purpose, output contents, and pagination without fluff. Each sentence carries substantive information, making it appropriately compact for a tool of this complexity.

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 an output schema present and read-only annotations, the description covers the key usage context (what data is returned, how pagination works) without needing to repeat schema structures. It is complete enough for an agent to select and invoke the tool 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?

The input schema already describes all three parameters with 100% coverage, including offset's pagination use. The main description repeats the offset continuation pattern but adds no new parameter-level meaning 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?

The description opens with a precise verb-resource pairing ('Read community check-ins and comments for one Open Charge Map station') and immediately differentiates the tool as the 'real-world reliability signal beyond the operator-reported registry status', distinguishing it from siblings that find stations or fetch station 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?

The description positions the tool as the source for community-reported reliability, implying when to use it over get_station; it also provides explicit pagination instructions ('repeat the call with the reported nextOffset'). It doesn't explicitly name alternative tools or state exclusions, but the context 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 and idempotentHint, so the safety profile is known. The description adds valuable behavior: browsing when query is omitted, pagination via nextOffset, and category-specific ID mapping. This goes beyond the annotations without contradicting them.

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 three sentences, each earning its place: purpose, usage examples, and pagination behavior. It is front-loaded with the primary function and avoids redundancy or 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?

Given the complexity (4 params, 7 categories) and presence of an output schema, the description covers key usage context: browsing, paging, and ID mapping. It doesn't need to explain return format since the output schema exists. A minor gap is lack of explicit error/not-found behavior, but this is not essential.

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%, with each parameter already documented thoroughly. The description contributes a few illustrative examples (CCS, ChargePoint, France) and clarifies the pagination offset mechanism, but these reinforce rather than substantially extend the schema's semantics.

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+resource+outcome: 'Resolve Open Charge Map reference data to the integer IDs that openchargemap_find_stations filters require.' This clearly distinguishes it from siblings (get_station, find_stations, comments) by positioning it as a reference resolver feeding filter IDs.

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 communicates when to use the tool: whenever you need reference IDs for find_stations filters, as shown by the examples mapping names to IDs. It doesn't explicitly state when not to use it, but the context is unambiguous given the sibling tools.

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