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 burden, and it does well by disclosing what is deliberately excluded (styling, popups, labels, column info, sample values) so the agent won't expect those fields. It also defines the semantics of dashboard_widget_count ('0 for none'). Missing only auth/permission and pagination context, which is minor for a single-record read.

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 purpose, followed by a compact field inventory and an explicit exclusion list. The layer-field catalog is a bit list-heavy but every item earns its place as return-shape documentation; no filler sentences.

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 describing return values is the description's job, and it does so thoroughly at both the top level and per-layer, plus calls out absent data. An agent can decide to call this and interpret the result without further sources.

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 single parameter has 0% schema description coverage, so the description must compensate: it documents map_id as a 'Map id' with provenance ('from list_maps'), which is meaningfully more than the bare type in the schema. It doesn't specify the ID format or null/failure behavior, keeping it from a 5.

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 summary of one saved map') and enumerates exactly what the summary contains (name, description, visibility, view state, basemap, terrain, layers). This clearly distinguishes it from list_maps, which is named as the source of map_id, and from dataset-oriented siblings.

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

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

Provides clear workflow context by telling the agent where map_id comes from ('e.g. from list_maps'), which implicitly scopes this tool to retrieving a single already-known map. It does not explicitly state when not to use it or contrast with get_dataset_schema, so it stops short of full when/when-not guidance.

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

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

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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: read-only enforcement, sandbox restrictions, 5-second timeout, self-join repetition cap, row limit, allowed functions, credential requirements, and rejection behavior are all disclosed. It also explains the return shape and geometry encoding.

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 sandbox behavior, and most sentences add operational value. It is longer than typical because of the exhaustive PostGIS function allowlist and detailed edge cases, but that detail is relevant for complex SQL generation rather than pure padding.

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, yet the description specifies the return object's fields, truncation behavior, and geometry encoding. It also covers credentials, table-scoping rules, query restrictions, and the prerequisite workflow, leaving little needed before an agent can 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 0%, so the description must compensate, and it does: sql is constrained to a single SELECT over data.* tables, restrict_tables requires non-empty table names without the data. prefix and must list every touched table, and row_limit is explained as max rows with a 1–1000 range and default 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?

The description opens with a precise verb and resource: 'Run one read-only SQL SELECT against accessible datasets.' It clearly distinguishes this tool as the SQL execution path, and the workflow references search_datasets and get_dataset_schema as prerequisite siblings.

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

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

It provides a clear end-to-end workflow: use search_datasets, then get_dataset_schema, then reference the table as data.<table_name> and list it in restrict_tables. However, it does not explicitly say when to use this instead of sibling tools like get_features or get_map, so it lacks full when-not/alternative guidance.

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

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

With no annotations, the description carries the full burden and does so well: it discloses semantic ranking, that no per-result detail request is made, that descriptions are truncated at 300 characters, the exact meaning of `due` vs `overdue` freshness (explicitly advisory, not proof of wrongness), null-field conditions for health metadata, and that raw provider URLs and credentials are never returned.

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 shape are front-loaded, and most sentences carry real information. The source-health paragraph is slightly bloated and discusses `source_health`, `last_checked_at`, and `last_refreshed_at` fields that are not even in the enumerated property list, which adds length without a clear payoff for a search call.

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 define the return shape, and it does: a compact FeatureCollection with `numberMatched`, `numberReturned`, and a full enumeration of each feature's properties. An agent has everything needed to call this and interpret the response without a follow-up tool call.

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 its Args block covers all three parameters: query as search text, limit as max results with the 1-200 range and default, and offset as the paging cursor. The coverage is adequate but terse; it does not clarify tokenization, empty-query behavior, or how offset interacts with ranked results.

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 immediately scopes what fields are matched. It also routes the agent onward ("Use the feature `id` as the dataset_id for the other tools; `get_dataset_schema` has the full detail"), which distinguishes it from the sibling that returns 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?

Clear context for when to use it (free-text discovery over the catalog) plus explicit hand-off guidance to `get_dataset_schema` for detail and trust metadata. It stops short of naming when *not* to use it versus siblings like `query`, `list_maps`, or `get_features`, so it is strong but not exhaustive.

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