Bridges AI agents to OpenStreetMap tagging schema via MCP tools for validation, search, conversion, comparison, and preset/tag info.
Validate single tags and tag collections against OSM schema, including deprecation checks.
Search tags and presets by keyword, tags, or geometry.
Get preset details and all documented values for a tag key.
Convert between flat key=value text and JSON tag objects.
Compare two tag sets and show differences.
Suggest improvements for tag collections based on matching presets.
Serve over stdio or HTTP with health, ready, and version endpoints.
Provides tools for querying OpenStreetMap tagging schema, discovering presets, validating tags, checking for deprecated tags, and suggesting tag improvements using the official @openstreetmap/id-tagging-schema library.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenStreetMap Tagging Schema MCP Server what tags should I use for a public library building?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a Model Context Protocol (MCP) server designed specifically for AI agents and LLM applications. It acts as a bridge between artificial intelligence systems and the comprehensive OpenStreetMap tagging knowledge base provided by the official @openstreetmap/id-tagging-schema library.
Related MCP server: SkyFi MCP Server
This project is a Proof of Concept. It gives real value in some areas and has known gaps in others, both described honestly below.
It works with the latest tagging schema, @openstreetmap/id-tagging-schema v7.
A better replacement tool is being worked on. It will arrive later than originally planned, and no date is promised.
Bug reports and ideas: open an issue or start a discussion.
The server runs over stdio (default) or HTTP and exposes the tagging schema as MCP tools. Every tool reads the schema data shipped in @openstreetmap/id-tagging-schema (presets, fields, deprecated tags, translations) and answers from it deterministically. There is no network access to OSM and no AI inside the server: the AI agent calls the tools and interprets the results.
Validation checks a tag against the schema: known key, value allowed by the matching field, deprecated key/value with a suggested replacement.
The tool has limitations. Know what to expect before relying on it: it answers from the schema data only, and a part of the tags that exist in the wild or on the OSM wiki is not covered.
Tool | Works | Limitations |
| Popular tags accepted (100%), almost no false | Detects only ~20% of wiki-deprecated tags; typos and foreign values are accepted as valid (custom tags are allowed); |
| Consistent with | Same gaps as |
| Preset matched for 92% of popular tags | Typos and foreign values usually yield suggestions, not a problem report |
| 97% of taginfo values present; bad keys and limits rejected | A few taginfo values are missing from the lists |
| Finds 60% of keys by name | No typo tolerance despite the fuzzy-matching description; keys with a colon ( |
| Preset found for 69% of popular tags (56% in top 3) | Multi-word queries ( |
| Preset exists for 93% of popular tags; unknown ids always rejected | Some popular tags (e.g. |
| Matches local computation (100%); text and JSON input give identical output | Compares any tag sets, so it never says a tag is wrong; only malformed input is rejected |
| Lossless, including | Duplicate keys and control characters are accepted silently |
| Lossless round-trip (100%); bad input rejected | Keys are not sorted alphabetically, input order is kept |
Across all tools, invalid input never crashed the server: errors are readable or the result is an empty list.
Useful where deterministic logic is enough: format conversion, comparing tag sets, reading presets and values, validating popular tags. Weakest areas: deprecated tag detection and search (typos, multiple words, colon keys).
⚠️ Important clarifications:
Not a standalone application: This server requires integration with AI systems (like Claude Code or Claude Desktop) to be useful. It has no user interface or web frontend.
Not for direct human use: Without an AI agent as an intermediary, this tool provides no value to end users. It's designed exclusively for programmatic access by LLM applications.
If you're looking for a user-facing OSM tagging tool, consider iD editor or JOSM instead.
Add the server to Claude Code (stdio):
# npx
claude mcp add --transport stdio osm-tagging-schema -- npx -y @gander-tools/osm-tagging-schema-mcp
# Docker
claude mcp add --transport stdio osm-tagging-schema -- docker run -i --rm ghcr.io/gander-tools/osm-tagging-schema-mcp:lateststdio is the default. Set TRANSPORT=http to serve over HTTP (streamable, port 3000 in the Docker image):
Variable | Default | Meaning |
|
|
|
|
| HTTP port |
|
| HTTP bind address |
|
| Comma-separated allowed CORS origins |
|
|
|
docker run --rm -p 3000:3000 -e TRANSPORT=http ghcr.io/gander-tools/osm-tagging-schema-mcp:latestEndpoints: GET /health (liveness), GET /ready (schema loaded), GET /version.
GNU General Public License v3.0 - See LICENSE file for details.
Compare two sets of OpenStreetMap tags to identify differences, additions, deletions, and modifications. Performs detailed tag-level comparison showing which tags were added, removed, or changed between two versions. Provides human-readable names for all tags and values using the OSM tagging schema. Use this for reviewing tag changes, understanding feature modifications, analyzing tag history, or validating tag transformations. Returns structured diff with localized names for better readability.
| Name | Required | Description | Default |
|---|---|---|---|
| newTags | Yes | The new/updated set of tags to compare to. Accepts either JSON object format ({"amenity": "restaurant"}) or flat text format (amenity=restaurant\nname=New Name). This represents the "after" state in the comparison. | |
| oldTags | Yes | The original/old set of tags to compare from. Accepts either JSON object format ({"amenity": "cafe"}) or flat text format (amenity=cafe\nname=Old Name). This represents the "before" state in the comparison. | |
| options | No | Options to control comparison output: 'showUnchanged' includes unchanged tags in the output (default: false), 'format' controls output format. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: it performs a read-only comparison, provides human-readable names using OSM schema, and returns structured diff. It also explains options like diffFormat and showUnchanged, giving a clear picture of what the tool does and how its output can be controlled.
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 plus a list of use cases. It is front-loaded with the core purpose. While it could be slightly more concise, it efficiently conveys necessary information 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?
The tool has 3 parameters, nested objects, no output schema, and no annotations. The description covers purpose, usage, behavior, and parameter options. It mentions 'returns structured diff' but does not detail the exact structure; however, the options help infer the output. Most aspects are adequately addressed.
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 context about accepted formats (JSON or flat text) and diff formats, but these are already covered in the schema descriptions. The description does not introduce new parameter meaning beyond what's in 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?
The description clearly states the tool compares two sets of OSM tags and identifies differences, additions, deletions, and modifications. It specifies the verb 'compare' and the resource 'OpenStreetMap tags', and it is distinct from sibling tools like flat_to_json or validate_tag.
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 lists use cases: reviewing tag changes, understanding feature modifications, analyzing tag history, and validating tag transformations. However, it does not mention when not to use this tool or suggest alternative tools for other tag operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert OpenStreetMap tags from flat text format (key=value per line) to JSON object format. This is an INPUT CONVERTER for AI workflows - use it FIRST when you receive tags in flat text format and need to work with them as a JSON object. Handles various text formats including key=value pairs (one per line), whitespace variations, empty lines, and comments (lines starting with #). Returns a clean JSON object with all parsed tags. Essential for processing OSM data from text exports, iD editor output, or JOSM exports.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes | Tags in flat text format with key=value pairs, one per line (e.g., "amenity=restaurant\nname=Test Cafe\ncuisine=italian"). Empty lines and lines starting with # are ignored. Whitespace around keys and values is trimmed automatically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully covers behavioral traits: 'Handles various text formats including key=value pairs (one per line), whitespace variations, empty lines, and comments (lines starting with #). Returns a clean JSON object with all parsed tags.' It discloses input handling and output, but does not mention error handling or 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?
The description is a single paragraph of 4 sentences, front-loaded with the core purpose. It is informative without unnecessary words, though slightly more structure (e.g., bullet points) could improve readability.
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 converter with one parameter and full schema coverage, the description provides sufficient context: input format, handling of various text artifacts, and output. It could mention the JSON structure (e.g., object with keys/values), but it's mostly complete.
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 description adds meaning beyond the schema by explaining the expected format (key=value per line) and noting that empty lines, comments, and whitespace are handled. Since schema coverage is 100%, the description complements it well.
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 'Convert OpenStreetMap tags from flat text format... to JSON object format.' It uses specific verb 'Convert', specifies resource 'OpenStreetMap tags', and distinguishes itself as an input converter for AI workflows, differentiating from sibling tools like 'json_to_flat'.
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 says 'use it FIRST when you receive tags in flat text format and need to work with them as a JSON object.' It provides clear context for when to use the tool, though it does not explicitly mention when not to use it or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get complete detailed information about a specific OpenStreetMap preset. Presets are feature templates that define standard tagging patterns (e.g., the 'Restaurant' preset defines amenity=restaurant and lists fields like cuisine, outdoor_seating, etc.). Returns comprehensive preset information including: display name, all required and suggested tags, supported geometry types, complete list of fields, field types and options, and parent/child preset relationships. Use this to understand exactly how to tag a specific feature type, learn what fields are available for a preset, or get example values for proper tagging.
| Name | Required | Description | Default |
|---|---|---|---|
| presetId | Yes | The preset identifier to retrieve (e.g., 'amenity/restaurant', 'highway/residential', 'natural/tree'). Preset IDs follow the pattern 'key/value' corresponding to the primary tag. Use search_presets to find preset IDs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden, and it does disclose the return contents in detail (display name, required/suggested tags, geometry types, fields, field types/options, parent-child relationships). It does not mention failure behavior for an unknown preset ID or whether results are cached/static, which is the remaining gap for a read tool.
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, followed by a definition and an enumerated return list. The parenthetical 'Restaurant' example is a useful concrete anchor rather than filler, though the sentence is somewhat long.
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 must explain the return payload — and it enumerates exactly what comes back and why an agent would want it. Combined with the fully documented input parameter, 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 description coverage is 100% and the single parameter already documents the ID pattern and examples, so the description adds no parameter-level meaning beyond the schema. Per the baseline rule for high coverage, a 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 complete detailed information about a specific OpenStreetMap preset') and then defines the domain object itself, so an agent unfamiliar with OSM presets still understands what it retrieves. It is clearly distinguishable from search_presets, which returns IDs rather than full 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 three concrete use cases: understand how to tag a feature type, learn which fields a preset supports, and get example values for tagging. It does not state when NOT to use it or explicitly contrast against siblings like get_tag_values or search_presets, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all possible values for a specific OpenStreetMap tag key, with localized human-readable names for both the key and each value. This tool searches through the OSM tagging schema (both predefined field options and preset definitions) to find every documented value that can be used with the specified key. Returns four pieces of information: the normalized key name, localized key display name, a simple array of all values, and a detailed array with localized names for each value. Use this to discover what values are available for a tag (e.g., all amenity types), learn the proper terminology for values, or build UI selection lists. Essential for understanding OSM's controlled vocabularies.
| Name | Required | Description | Default |
|---|---|---|---|
| tagKey | Yes | The OpenStreetMap tag key to retrieve values for (e.g., 'amenity', 'building', 'highway', 'natural', 'shop'). Supports both simple keys and namespaced keys with colons (e.g., 'addr:street', 'name:en'). The tool will search both field definitions and preset tags to find all documented values. Case-sensitive, use lowercase for standard OSM keys. | |
| options | No | Options to control query output: 'limit' restricts the maximum number of values returned (useful for tags with many values like 'name'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavioral traits: it searches both predefined field options and preset definitions, supports simple and namespaced keys, is case-sensitive, and returns four specific pieces of information. This goes well beyond the basic operation, providing rich 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 information-dense and each sentence contributes value, starting with the primary action. It could be slightly shorter by removing redundant phrases like 'to find every documented value' after already stating the schema search, but overall it's well-structured and not excessively verbose.
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 absence of an output schema, the description thoroughly explains the return format (four pieces of information). It covers all important aspects: search scope, key types, case-sensitivity, and parameter usage. The parameter count and high schema coverage are fully leveraged, making the description self-sufficient.
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 value beyond schema by giving examples for tagKey (e.g., 'amenity', 'addr:street'), explaining case-sensitivity, and for options.limit, it clarifies purpose and performance benefit. This extra guidance elevates the score.
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 specific verb 'Retrieve' and resource 'all possible values for a specific OpenStreetMap tag key'. It differentiates from sibling tools like search_tags (which searches across tags) and get_preset_details (which focuses on presets) by focusing on enumerating all documented values for a single key, making its unique purpose 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 explicitly lists three use cases: discovering available values, learning terminology, and building UI lists. It also implies when to use it (e.g., 'Essential for understanding OSM's controlled vocabularies'). However, it does not provide explicit when-not-to-use scenarios or compare alternatives, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert OpenStreetMap tags from JSON object format to flat text format (key=value per line). This is an OUTPUT CONVERTER for AI workflows - use it LAST when you need to present tags in a human-readable text format or export them for use in other tools. Produces clean, consistent key=value format with one tag per line, sorted alphabetically by key. Use this for generating human-readable tag lists, exporting to OSM editors, or sharing tag collections. The output format is compatible with JOSM, iD editor imports, and other OSM tools that accept flat text tag format.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes | Tags as a JSON object (e.g., {"amenity": "restaurant", "name": "Test Cafe", "cuisine": "italian"}). All values must be strings. The output will be formatted as key=value pairs, one per line, sorted alphabetically. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the output: one tag per line, sorted alphabetically, in key=value format. States all values must be strings. Without annotations, this provides adequate behavioral context, though edge cases (e.g., empty tags) are not addressed.
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 purpose and provides necessary context in a few sentences. Slight redundancy (e.g., 'human-readable' repeated) but overall efficient.
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 low complexity (1 parameter, no output schema), the description covers the transformation, output format, and compatibility, making it self-sufficient for an agent 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% so baseline is 3. The main description does not add new parameter details beyond the schema; it focuses on usage. The schema description already covers the parameter 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 clearly states it converts JSON tags to flat text (key=value per line) and identifies itself as an output converter. It distinguishes from siblings like flat_to_json by specifying it's for final presentation/export.
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 to use it 'LAST' in workflows for human-readable or export purposes, and lists compatible OSM tools. However, it does not explicitly mention alternatives like flat_to_json or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for OpenStreetMap presets by name, tags, or geometry type. Presets are predefined feature templates that define how specific types of features should be tagged (e.g., 'Restaurant' preset defines standard tags for restaurants). Supports filtering by preset name keywords, specific tag filters, and geometry type (point/line/area/relation). Returns matching presets with their names, primary tags, geometry types, and match scores. Use this to find the correct preset for a feature type, discover how to tag specific features, or explore available feature templates in OSM.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | (Deprecated: use options.limit instead) Maximum number of preset results to return (optional, no default limit). Use this to get faster responses when you only need a few results, or to avoid overwhelming output when searching broad terms. Example: limit=10 returns only the first 10 matches. | |
| keyword | Yes | Optional keyword to search in preset names (e.g., 'restaurant', 'park', 'school'). Case-insensitive search that matches against preset display names. Leave empty to search by tags or geometry only. | |
| options | No | Options to control search behavior and output: 'limit' restricts the maximum number of results returned. | |
| geometry | No | (Deprecated: use options.geometry instead) Filter results to only presets that support a specific geometry type (optional). Valid values: 'point' (nodes/POIs), 'vertex' (nodes along ways), 'line' (open ways like roads/rivers), 'area' (closed ways/areas like buildings/parks), 'relation' (complex features). Example: geometry='area' returns only presets that can be applied to area features. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains the tool's behavior: it returns matching presets with names, primary tags, geometry types, and match scores. No destructive actions are indicated, and the output fields are disclosed.
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, front-loaded with the main purpose. It explains presets and usage efficiently without excessive wording. Minor redundancy could be tightened, but overall concise.
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 compensates by listing returned fields (names, primary tags, geometry types, match scores). It covers filtering by keyword, tags, and geometry. Adequate for a search tool with nested parameter.
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?
All parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds context like preset examples and use cases, but does not add significant new meaning beyond what the schema 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?
The description clearly states the tool searches for presets by name, tags, or geometry type, and provides examples like 'Restaurant'. It distinguishes from sibling tools like search_tags and get_preset_details by focusing on finding complete preset templates.
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 advises using the tool to find correct presets, discover tagging, or explore templates. It does not explicitly state when not to use it or point to alternatives, but the context of siblings implies appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for OpenStreetMap tags by single keyword or pattern. Searches across tag keys, tag values, and localized names to find matching tags. Supports fuzzy matching to find tags even with slight typos or variations. Returns matching tags with their keys, values, and human-readable names. Use this to discover tags related to a topic, find the correct tag when you know part of the name, or explore available tags in a category. For tag pair filtering (e.g., amenity=restaurant), use search_presets instead. Essential for learning OSM tagging vocabulary and discovering lesser-known tags.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | (Deprecated: use options.limit instead) Maximum total number of results to return across both keyMatches and valueMatches combined (default: 100). Use lower values for faster responses when you only need a few results. | |
| keyword | Yes | Single standalone keyword or pattern to search for in tag keys, values, and names (e.g., 'restaurant', 'bicycle', 'wheelchair'). The search is case-insensitive and supports partial matching. Will search across tag keys (e.g., 'amenity'), tag values (e.g., 'restaurant'), and localized display names. For tag pair filtering (e.g., amenity=restaurant), use search_presets instead. | |
| options | No | Options to control search behavior and output: 'limit' restricts the maximum number of results returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description discloses key behaviors: supports fuzzy matching, case-insensitive, partial matching, returns matching tags with keys, values, and names. It does not mention auth needs or rate limits, but overall transparent enough for a search tool.
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 paragraph but front-loaded with core functionality. Every sentence adds value, though it could be slightly more concise. Still very good.
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 3 params, no output schema, the description covers search behavior, fuzzy matching, case-insensitivity, return fields, and references sibling tool. It is complete for a search 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%, baseline 3. The description adds meaning beyond schema: keyword is described as single standalone keyword, case-insensitive, partial matching; limit described as max results with performance tip; options.limit described as default unlimited. This adds value.
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 searches for OpenStreetMap tags by keyword/pattern across keys, values, and localized names. It distinguishes from sibling search_presets by specifying that tag pair filtering should use search_presets instead.
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 tells when to use this tool: to discover tags, find correct tags, explore categories. It also tells when not to use it: for tag pair filtering, use search_presets. This provides clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze an OpenStreetMap tag collection and provide intelligent suggestions for improvements. Identifies the feature type from existing tags, finds the matching OSM preset, compares current tags against preset requirements, suggests missing required fields, recommends commonly used optional fields, and provides examples for suggested fields. Returns prioritized improvement suggestions with explanations and example values. Use this to enhance incomplete features, learn best practices for tagging specific feature types, or improve data quality of existing OSM data.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes | Current tags for the OSM feature to analyze. Accepts three formats: 1) JSON object ({"amenity": "restaurant", "name": "Example"}), 2) JSON string ('{"amenity":"parking"}'), or 3) flat text format (amenity=restaurant\nname=Example). The tool will analyze these tags to identify the feature type and suggest appropriate additional tags. | |
| options | No | Options to control suggestion output: 'summary' adds a human-readable summary, 'limit' restricts the number of suggestions returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It transparently discloses the analysis steps (identify feature type, match preset, compare tags, suggest missing fields) and implies a read-only operation. It does not mention side effects, permissions, or rate limits, but the context (analysis tool) makes destructive behavior unlikely. Slightly more explicit read-only confirmation would elevate the score.
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 dense paragraph that efficiently conveys the tool's functionality. It is front-loaded with the core action. While concise, it could benefit from bullet points or clearer separation of steps for even quicker scanning, but it is not overly verbose.
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 must explain return values. It mentions 'prioritized improvement suggestions with explanations and example values', but lacks specifics about the output structure (e.g., whether it returns an array of objects, fields like 'tag', 'reason', 'example'). Given the tool's complexity, more detailed return format expectations would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for both parameters (tags and options) with 100% coverage, so the description adds no additional parameter semantics. The baseline score of 3 is appropriate as the schema already explains parameter meaning and formats.
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 specific verbs ('analyze', 'provide suggestions', 'identifies', 'compares', 'suggests') and clearly defines the resource ('OpenStreetMap tag collection'). It distinguishes itself from siblings by describing a unique analysis workflow (finding matching OSM presets, comparing against requirements), which is not covered by other tools like validate_tag_collection or compare_tags.
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 use cases: 'enhance incomplete features, learn best practices, or improve data quality'. This provides clear when-to-use guidance. However, it does not mention when NOT to use the tool or alternatives for specific scenarios, which would strengthen the dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a single OpenStreetMap tag key-value pair against the OSM tagging schema. Performs comprehensive validation including: deprecation checking (identifies deprecated tags and suggests modern replacements), schema existence validation (verifies the tag key exists in the schema), option validation (checks if the value is in predefined options for that key), and field type checking (distinguishes between strict fields and combo fields that allow custom values). Returns detailed validation results with localized names and actionable messages. Use this for educational purposes, data quality checks, or validating individual tags before bulk operations.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | The OpenStreetMap tag key to validate (e.g., 'amenity', 'building', 'highway', 'natural'). Tag keys should use the standard OSM format with colons for namespaces (e.g., 'addr:street', 'name:en'). Case-sensitive. | |
| value | Yes | The OpenStreetMap tag value to validate against the specified key (e.g., 'restaurant', 'yes', 'residential', 'park'). Values are checked against predefined options if the field has them. Case-sensitive in most cases, though some fields may accept case-insensitive values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly describes the validation steps and what results include (localized names, actionable messages), implying a read-only, non-destructive operation. It does not explicitly state idempotency, but that is reasonable for a validation tool.
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 paragraphs with clear structure: purpose in first sentence, bullet-like list of validations, and use cases. Every sentence adds value, no redundant text.
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 no output schema, the description sufficiently covers return value content (detailed results, localized names, messages). It addresses input parameters adequately and fits within the context of sibling tools. Could be more specific about output structure, but overall complete.
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 valuable context about OSM formatting (colons for namespaces), case sensitivity for keys and values, and value checking against options. This enhances understanding beyond the schema 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 explicitly states it validates a single OSM tag key-value pair against the schema, listing specific validations (deprecation, schema existence, option validation, field type checking). It distinguishes from siblings like validate_tag_collection and compare_tags by focusing on individual tags.
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 recommends use for educational purposes, data quality checks, or before bulk operations, indicating when to use it. It implicitly contrasts with validate_tag_collection for multiple tags, but doesn't explicitly exclude other scenarios or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a complete collection of OpenStreetMap tags (e.g., all tags for a feature) against the OSM tagging schema. Performs batch validation of multiple tag pairs, checks for deprecated tags across the entire collection, identifies conflicting or incompatible tags, and validates tag combinations. Returns comprehensive validation results for all tags with individual validation status, deprecation warnings, and collection-level issues. Use this to validate complete features before uploading to OSM or for data quality analysis of existing features.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | Yes | A collection of OpenStreetMap tags to validate. Accepts three formats: 1) JSON object ({"amenity": "restaurant", "name": "Example"}), 2) JSON string ('{"amenity":"parking"}'), or 3) flat text format (amenity=restaurant\nname=Example). All tags in the collection will be validated individually and as a set to identify conflicts or missing required tags. | |
| options | No | Options to control validation output detail and summary generation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description does not disclose whether the tool is read-only or has side effects. For a validation tool it likely is safe, but lack of explicit behavioral context reduces 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?
Three sentences, front-loaded with core purpose. Concise but could be slightly tighter without losing clarity.
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, description adequately hints at return value (validation results, deprecation warnings, collection-level issues) and covers the tool's complexity for its intended use.
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 description adds value by explaining the three input formats for tags and the effect of options (summary, verbose), providing context 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?
Description clearly states it validates a complete collection of OSM tags, performs batch validation, checks deprecated tags and conflicts, distinguishing it from single-tag validation (validate_tag) or comparison (compare_tags).
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 when to use (before uploading to OSM, data quality analysis) but does not explicitly state when not to use or mention alternative sibling tools like validate_tag for single tags.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.8.1validate_tagv3.0.0validate_tagScored across 10 tools
Each tool targets a clearly distinct operation, and overlaps are explicitly addressed in descriptions (e.g., search_tags vs. search_presets; validate_tag vs. validate_tag_collection). The two conversion tools are directional and unambiguous.
All names use consistent snake_case, and most follow a verb_noun pattern. The two converters (flat_to_json, json_to_flat) deviate into noun_to_noun naming, but they are internally consistent and readable.
Ten tools is well within the ideal 3-15 range for this domain, and each tool contributes a distinct capability for working with OSM tagging schema data.
The set covers search, lookup, validation, suggestion, comparison, and conversion workflows well. Minor gaps exist, such as no dedicated tag-key metadata/details beyond get_tag_values and no explicit list-all operation, but agents can work around these via search.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Curated knowledge API for AI agents - skill packs, semantic search, validated patterns.
Web data tools for AI agents: pages as markdown, search, maps, commerce, jobs, AI answers.
Travel tools for AI agents: plan and edit real trips, search stays and tours, import travel videos.
