geolens-mcp

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

With no annotations, the description carries the full disclosure burden and does so richly: it decodes the source_health enum (including the subtle inaccessible vs unknown distinction), clarifies that source_health_detail is a fixed reason code rather than provider text, distinguishes last_checked_at from last_refreshed_at, defines the advisory 'overdue' freshness rule, and confirms raw provider URLs and credentials are excluded.

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 opening sentence front-loads the purpose, and each subsequent sentence carries real semantic content about return fields rather than filler. It is dense and slightly long for a one-parameter read tool, but no sentence is redundant.

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, no annotations, and a minimal input schema, the description supplies everything an agent needs: what the call returns, how to interpret the trust/freshness fields, and when in the workflow to invoke it. Nothing material 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 parameter with 0% schema description coverage, so the description must compensate. It does, by annotating dataset_id with a concrete source ("e.g. from search_datasets"), which is exactly the guidance the bare string schema lacks.

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 a dataset's schema") and immediately enumerates the returned surface (columns, geometry type, CRS/SRID, feature count, extent, trust metadata), which makes it unmistakable what this tool does versus search_datasets, get_features, or query.

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 "Call this before writing spatial questions so you know both the available columns and whether the source may be stale," giving a clear triggering condition. It stops short of naming a specific alternative tool or a when-not-to-use case, so it does not reach the 5 bar.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the response shape (OGC-API FeatureCollection), a failure mode (raster datasets will error), pagination behavior (capped by limit, page with offset), and strict argument validation. It omits auth/permission requirements and whether results are ordered, which are the remaining behavioral gaps.

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?

Purpose and return type are front-loaded, followed by caveats and then the argument list, which is the right ordering. The "Only the arguments listed below are supported; anything else is rejected" line partially duplicates additionalProperties=false, a minor redundancy in an otherwise tight description.

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

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

With no output schema, the description correctly explains the return type (OGC-API FeatureCollection) and error conditions, and it documents all four parameters despite zero schema coverage. It is complete enough to call correctly; the main residual gap is that dataset_id's expected form (id vs. slug) is not clarified.

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 0%, so the description must compensate, and it does: it gives the units/format for bbox ("minx,miny,maxx,maxy", WGS84), the range and default for limit (1-200, default 10), and the paging role of offset. Only dataset_id ("Dataset id") stays a bare restatement, which is the one weak spot.

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

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

Specific verb+resource ("Get GeoJSON features for a dataset") with an explicit scope qualifier ("bounded") and a stated return format (OGC-API FeatureCollection). It clearly separates itself from a generic query tool, but it never names or contrasts a sibling (e.g. query) so the differentiation is implicit rather than explicit.

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 supplies real usage conditions: raster datasets have no features and will error, results are capped and must be paged with offset, and unsupported arguments are rejected. However, it never names an alternative tool or says when to prefer query/search_datasets over this one, so an agent is left to infer routing on its own.

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?

With no annotations, the description carries the full burden, and it does disclose that this is a read returning full metadata plus the specific configuration surface returned. It omits not-found behavior, permission requirements, and size limits, so it is useful but not complete.

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 single sentence that names the resource and its returned content, followed by a compact Args block. No filler sentences; every line 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?

For a single-parameter read with no output schema, the description covers purpose, payload contents, and id provenance, which is most of what an agent needs. Error and empty-result behavior remain undocumented.

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 0%, so the description must compensate. It explains what map_id is and where to obtain it (from list_maps), but gives no format, expected shape, or example value, leaving part of the gap unfilled.

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 one saved map's full metadata') and enumerates the payload (layers, view state, basemap, terrain). The contrast with list_maps is only implicit via the word 'one', 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?

Usage is implied by 'one saved map' versus the list-oriented sibling, and it helpfully notes the id can come from list_maps. However, there is no explicit when-to-use/when-not statement or guidance on what to do when map_id is unknown or invalid.

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?

With no annotations, the description carries the full burden and does disclose the key trait: this is a read-only metadata listing and it enumerates exactly what is returned (id, name, visibility, layer count). It omits auth/permission requirements and whether search is case-insensitive or substring-based, which keeps it out of the top band.

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

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

One front-loaded summary sentence plus a compact, clearly labelled arg list. Every line carries information and nothing is padded.

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, zero-required-param read tool with no output schema and no annotations, the description covers purpose, all three params, and the returned fields, so an agent can call it correctly. The only real gap is the absence of routing guidance relative to get_map and search_datasets.

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 0%, so the description must compensate and largely does: it explains that search filters on name/description (the schema only says string), states limit is 1-200 with default 50, and identifies offset as paging. Limit/offset are conventional enough that no further explanation is needed.

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

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

States a specific verb and resource ('List saved maps') and scopes the return to metadata (id, name, visibility, layer count), which clearly separates it from the single-map sibling get_map. It does not name any sibling explicitly, so it stops just short of full differentiation.

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

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

Usage is only implied: listing 'saved maps' suggests browsing rather than fetching a specific map, but there is no explicit when-to-use, when-not-to-use, or pointer to get_map/search_datasets. An agent must infer the routing from the resource name alone.

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?

No annotations are provided, so the description carries the full burden and does so thoroughly: hardened sandbox, allowlisted function set, server-side time budget, self-join repetition cap, row_limit truncation, the exact return shape {columns, rows, row_count, truncated}, and the AI-chat permission requirement with anonymous configs excluded.

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

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

Front-loads the core purpose and constraints effectively, but the trailing Args block restates details already conveyed in prose (row_limit's range, restrict_tables' requiredness), producing mild redundancy rather than wasted 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?

Despite no output schema, the description specifies the return payload, the credential prerequisite, the sandbox limits, and the required call sequence, leaving nothing an agent needs in order to invoke 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 0%, but the description fully compensates: sql is defined as a single SELECT over data.* tables, restrict_tables is declared required, non-empty, and prefix-free, and row_limit is given its 1-1000 range and default of 100.

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 ('Run one read-only SQL SELECT against accessible datasets') and implicitly distinguishes itself from siblings like search_datasets and get_dataset_schema, which are named as earlier steps in the workflow rather than substitutes.

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 an explicit multi-step workflow (search_datasets -> get_dataset_schema -> query) and states the constraint that every touched table must appear in restrict_tables and that scope can only narrow existing credential visibility. Writes, other schemas, and unlisted functions are explicitly excluded.

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?

With no annotations, the description carries the full burden and does well: it discloses the return type (GeoJSON FeatureCollection), that no per-result detail request is made, when trust fields are null, that freshness is advisory rather than proof of bad content, and that credentials/provider URLs are never exposed. It omits auth requirements, rate limits, and whether paging returns totals, which keeps it from 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?

Front-loaded with the core action and return shape, followed by supporting detail about source fields, nulls, and freshness. The freshness and null paragraphs are long but each carries information an agent needs; a small amount of the enumeration could be tightened.

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, and the description compensates well by naming the return container, the feature id's role as dataset_id, and the meanings of source_origin, source_freshness, and the null trust fields. Remaining gaps are paging behavior beyond the offset argument and permission/auth requirements.

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 0%, so the description must compensate, and it does document all three parameters (query, limit, offset) in the Args block. However, the entries largely restate what the schema's own bounds and defaults already show ('limit: Max results (1-200, default 10)') and add little semantic meaning beyond 'free text' and 'for paging'.

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 ('Search the GeoLens catalog for datasets by free text') and names the exact fields matched (title, description, keywords). It also routes onward ('use the feature `id` as the dataset_id for the other tools'), which makes the boundary with siblings like get_dataset_schema and list_maps 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?

Gives clear usage context: free-text discovery, with semantic ranking applied when enabled, and explicitly routes the agent to get_dataset_schema when it needs populated trust metadata. It does not state explicit when-not-to-use conditions or contrast against `query`/list_maps, so it stops short of a 5.

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