MapTiler MCP by usefulapi

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

Annotations only declare readOnlyHint=true; the description goes beyond that by disclosing the return contract (an ordered JSON array of GeoJSON FeatureCollections, one per query) and the underlying endpoint. It omits other relevant behavior such as plan/quota restrictions for batch geocoding, which keeps it short of a 5.

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 short sentences with the core capability front-loaded, followed by the return shape and endpoint. Nothing is padded or buried.

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 specifies the return structure, and the schema itself covers all parameters. Only error/partial-failure behavior and plan-gating for large batches are unaddressed, so it is nearly but not fully 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 description coverage is 100%, so all seven parameters are already documented in the schema. The description only restates the 50-query ceiling and adds no syntax, format, or interaction detail (e.g. how types/country combine across the batch), matching the baseline 3.

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 ('forward-geocode ... queries'), plus the distinguishing scope ('up to 50 queries in one request') that separates it from the single-query sibling maptiler_geocode. An agent can identify it as the batch variant without opening any 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 batch framing implies when to use it (many queries at once), but the description never says so explicitly nor names maptiler_geocode as the alternative for single lookups. Usage is inferable 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully adds the output shape (GeoJSON features) and the underlying endpoint, but says nothing about rate limits, error/no-match behavior, or result ordering/bias semantics.

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 short sentences, front-loaded with the purpose and reinforced by examples. The trailing 'API: GET /geocoding/{query}.json' is somewhat redundant with the schema's note that query goes in the URL path, but it is compact and harmless.

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 an 11-parameter read tool with no output schema, the description supplies the key missing piece (results are GeoJSON features), and the schema fully documents the many filters. It stops short of covering result ordering or no-match behavior, which a geocoder consumer might need.

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 all 11 parameters are already documented in the schema (bbox, types, excludeTypes inversion, proximity, worldview, etc.). The description adds no parameter-level meaning beyond noting the query goes in the URL path, which the schema also states. Baseline 3 is correct.

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 (search/geocode) and resource (place, address, POI by name) and gives concrete query examples plus the return format (GeoJSON features). It implies forward-vs-reverse distinction through 'by name' but never names reverse_geocode or batch_geocode as the alternatives, so sibling differentiation is left to inference.

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 implied: use this to turn a name/address into coordinates. There is no explicit statement of when to prefer maptiler_reverse_geocode, maptiler_batch_geocode, or maptiler_geolocate_ip, and no mention of autocomplete-vs-full-search selection despite an autocomplete parameter.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and delivers a genuinely important caveat: from a hosted Worker the returned location is the server's egress IP, not the end-user's, which materially affects how an agent should interpret results. It does not describe the payload shape (lat/lon, accuracy, etc.), leaving a modest 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?

Two tight sentences, front-loaded with the action and the caveat before the API detail. The endpoint reference is slightly developer-facing and not strictly needed for tool selection, keeping it just short of perfect.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter tool with no output schema, the description omits what is actually returned (coordinates, location fields, elevation flag effect), which is the main thing an agent cannot look up elsewhere. The behavioral caveat is well covered, but return-value context 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?

There is a single optional parameter and schema description coverage is 100%, so the schema fully documents 'elevation'. The description adds no additional meaning about the parameter (default behavior when omitted, cost/response implications), so 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 ('geolocates the IP address making the request') and even names the underlying endpoint, which makes it trivially distinguishable from geocode/reverse_geocode siblings. The caveat about which IP is being resolved is precise scope-setting, not filler.

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 implied by the semantics ('the IP address making the request'), so an agent can infer this is for locating the caller's own IP rather than an arbitrary location. However, there is no explicit when-to-use/when-not guidance, no mention of alternatives such as maptiler_reverse_geocode for locating a known point, and no prerequisites.

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, so the safety profile is covered. The description adds the return shape ('GeoJSON FeatureCollection') and the underlying REST endpoint, which is useful, but says nothing about pagination, response size, or authentication requirements for a hosted dataset.

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 short sentences, zero filler, with the operation and return type front-loaded and the endpoint given as a compact trailing 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?

For a single-parameter read tool with no output schema, the description compensates by naming the exact return type (GeoJSON FeatureCollection). The absence of pagination/error behavior is a minor residual gap given the tool's simplicity.

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 only one parameter, so the schema already documents dataId as a MapTiler dataset id. The description's phrase 'by its data id' adds no meaning beyond that; 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 ('Fetch') and a precise resource ('GeoJSON FeatureCollection of a MapTiler-hosted dataset by its data id'), which is clearly distinguishable from the geocoding/elevation/coordinate siblings. It stops short of explicitly naming any sibling or exclusion, so it is clear but not differentiated in prose.

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 when-to-use guidance, no prerequisites (e.g. a valid MapTiler Cloud dataset must exist), and no mention of alternatives. Usage is only inferable from the resource 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 only declare readOnlyHint=true, so the description adds real value: it discloses the 50-coordinate cap, the exact return structure ([lng, lat, elevation] triples), and the underlying API path. It does not mention rate limits or error behavior, but for a simple read-only lookup this is solid disclosure 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?

Three short sentences, zero filler, with the core purpose and the return format front-loaded. 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?

There is no output schema, and the description compensates by specifying the return shape and coordinate ordering. Combined with the readOnlyHint annotation and a fully documented schema, an agent has nearly everything needed to call and interpret this tool correctly; only rate-limit/pagination behavior is 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 coverage is 100% and both parameters (locations, unit) are already documented in the schema, including the lat/lng order and bounds. The description repeats the 50-coordinate limit without adding format or syntax detail 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 ('Look up ground elevation') plus a scope constraint (up to 50 coordinates). The domain is unique among siblings (geocode, reverse_geocode, transform_coordinates), so an agent can identify it without confusion, though it never explicitly contrasts itself with any sibling.

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?

No guidance on when to use this versus alternatives, and no prerequisites or exclusions are stated. The description only says what it does and the API shape; all usage context must be inferred from the 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=true, so the safety profile is covered. The description adds that results come back as GeoJSON features and names the underlying GET endpoint, but discloses nothing about auth requirements, rate limits, or result ordering. Moderate added value over annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler; the core purpose is front-loaded and the API detail is secondary. 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?

There is no output schema, so the description usefully notes the GeoJSON feature return shape. With full schema coverage and a read-only annotation, this is nearly complete, though it omits any mention of auth, limits, or the worldview/type filtering behavior.

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 every parameter (limit, types, language, lat/long bounds, worldview, excludeTypes) is already documented in the schema. The description adds no parameter-level meaning beyond reiterating longitude/latitude, matching the baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Find the place(s) at a given longitude/latitude'), which clearly distinguishes reverse geocoding from the forward-geocoding sibling maptiler_geocode. It stops short of explicitly naming the sibling or stating the contrast, so it is clear but not fully differentiated.

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 'place at coordinates' framing implies the use case (turn a lat/long into a place), and the API line signals this is a lookup call. However, there is no explicit when-to-use, when-not, or reference to alternatives such as maptiler_geocode or maptiler_batch_geocode.

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

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

The readOnlyHint annotation already establishes this is a safe read, and the description reinforces it by disclosing the underlying GET endpoint. It adds nothing about rate limits, auth requirements, or how the 'exports'/'transformations' flags affect payload size or latency.

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 compact sentences, with the search semantics and filter examples front-loaded before the incidental API path. Zero 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?

No output schema exists, so the description could ideally say a bit about result shape (e.g. codes, names, WKT when exports=true). Still, for a straightforward filtered search with full schema coverage and a readOnly annotation, it is close to 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 description coverage is 100% and every parameter is documented in-schema, including the filter syntax the description merely repeats. Baseline 3 is appropriate: the description adds no meaning beyond the schema.

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

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

The description gives a specific verb ('Search') and resource ('MapTiler's CRS/EPSG database'), and the filter examples ('code:4326', 'kind:CRS-PROJCRS') make the scope concrete. It is implicitly distinct from the geocoding/transform siblings but never names or contrasts them.

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 explains *how* to query (free text or key:value filters) and gives an example, but never states when to reach for this tool versus maptiler_transform_coordinates or the geocoding siblings. Usage is implied rather than guided.

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, so the safety profile is covered. The description adds the meaningful constraint of 'up to 50 coordinate pairs' and the GET endpoint, but says nothing about error behavior for invalid/reprojection-failing pairs or how the transformation path is chosen when 'ops' is absent.

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 front-loaded sentence covering verb, resource, and limit — efficient. The trailing 'API: GET /coordinates/transform/{coordinates}.json' is operational detail that adds little for an agent selecting a tool, but the overall text is short and wastes no space.

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 would ideally describe what comes back (transformed coordinate pairs, ordering, precision) — it does not. Combined with the absent guidance on obtaining valid EPSG codes, the definition is adequate for a straightforward read-only transform but leaves the response contract to inference.

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 params and their defaults (4326/WGS84) are already documented in the schema; baseline 3 applies. The description only restates the EPSGCode nature of s_srs/t_srs and the 50-pair cap, which duplicates the schema's maxItems and adds no interpretation of the 'ops' force-path parameter.

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 ('Transform') and resource ('coordinate pairs ... between coordinate reference systems'), with concrete scope boundaries (up to 50 pairs, EPSG codes). No sibling tool (geocode, reverse_geocode, get_elevation, search_coordinate_systems) does coordinate transformation, so the function is unambiguous even without naming an alternative.

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 when-to-use guidance, no prerequisites, and no reference to the sibling maptiler_search_coordinate_systems, which is exactly the tool an agent would need to resolve EPSG codes before calling this one. The only usage hint is the parenthetical '(EPSG codes)', which implicitly signals that numeric codes are required inputs.

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