Geobble

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds useful context about what the returned accounts represent (owners of projects, datasets, maps, collections) and why the handle matters, though it says nothing about ordering or completeness of the list.

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 sentence that front-loads the action and result, with the em-dash aside delivering the caller-relevant detail. No wasted wording.

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?

An output schema and annotations carry the return-value and safety details, so the description only needs to frame the resource and its use, which it does. Minor gap: no note on whether the full list is always returned or whether empty-account cases occur.

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 tool takes zero parameters, so there is nothing for the description to clarify; baseline is 4. The prose correctly implies a no-argument call.

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 (list) and resource (personal and organization accounts), and scopes it to accounts that can own new geospatial work. Distinguishes itself from create-type siblings by explaining the returned handle is what those tools require.

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 clause 'including the handle the create tools require' tells the agent when to call this: as a discovery step before create tools. It does not explicitly state exclusions or name an alternative lookup tool, but no obvious sibling serves that role.

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 description says "Preview changing" the profile, which implies a read-only dry-run, while annotations declare readOnlyHint=false. This is a direct behavioral contradiction: an agent cannot tell whether invoking the tool mutates the account or merely previews the change.

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 definition is a single compact sentence with no wasted text, and the account scope is front-loaded. The ambiguity comes from word choice and behavioral contradiction, not from verbosity or poor structure.

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 non-read-only profile mutation tool with no output schema and 0% schema description coverage, the description should clarify whether changes are applied, what accountId means, and what happens on success. It covers the general scope but leaves the core mutation behavior ambiguous.

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 maps three parameters to editable fields (name, about, phone) but never explains the required accountId parameter, despite schema description coverage being 0%. It also adds no semantics for constraints such as lengths or UUID format, so it only partially compensates for the schema's lack of descriptions.

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 names specific editable fields (display name, about text, phone number) and the account scope (own profile or organization administered), which clearly distinguishes it from general profile-reading siblings. However, the opening word "Preview" makes the core purpose ambiguous: it is unclear whether this tool actually updates the profile or only previews a change.

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 gives clear usage context: the account must be one the caller administers, either their own profile or an organization where they are an admin or owner. It also explicitly excludes handles from editability here, though it does not name an alternative tool for handle changes.

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 mark it as a mutation (readOnlyHint=false), idempotent, and non-destructive; the description adds the key behavioral fact that the underlying action will NOT be carried out, which annotations cannot express. It stops short of describing the state of the confirmation afterward or error behavior for invalid IDs.

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 sentence that front-loads the verb and effect with no filler. Nothing is wasted 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?

For a one-parameter mutation with no output schema, the description covers the essential effect but omits what a successful cancellation returns or how failures (unknown/expired/already-executed confirmation) manifest. Adequate, not 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 schema has 0% description coverage on the single required parameter, and the description says nothing about confirmationId — no format, no indication that it comes from a previously staged confirmation. With one undocumented parameter, the description should compensate and does not.

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 ('Invalidate') and resource ('a pending Geobble confirmation'), and the phrase 'without executing the underlying action' implicitly contrasts it with the confirm_action sibling. The purpose is unmistakable, though the sibling is never named.

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?

By describing the effect on a pending confirmation, the description implies when to use it (rejecting a staged action). It does not state prerequisites, what happens if the confirmation was already executed or expired, or name confirm_action as the alternative path.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds no behavioral context beyond that — no statement of whether results are tool listings or prose, though an output schema exists to carry the return shape.

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 with the verb and scope up front and the domain enumeration as the payload. No filler, no restatement of the title.

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-parameter, read-only discovery tool with an output schema and full annotation coverage, the description gives enough to call it correctly. It could note whether output enumerates tools or capability areas, but the output schema reasonably owns that detail.

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 tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly implies a parameterless call.

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 ("Describe") and resource ("this server's geospatial capabilities") and then enumerates the covered domains: authoring/editing projects and maps, spatial analysis, publishing web maps, and data movement. That enumeration maps directly onto the sibling families (project_*, map_*, source_*), so an agent can tell this is the umbrella/orientation tool rather than any single operation.

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: an agent can infer this is a discovery/orientation call, but the description never says when to call it (e.g., first, before choosing a sibling) or when it is unnecessary. No alternatives or exclusions are named.

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 annotations already declare this is a non-read-only, non-destructive, closed-world mutation. The description adds that the collection belongs to an accessible account, which gives some ownership context, but it does not disclose duplicate-slug behavior, visibility defaults, or permission requirements.

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 efficient sentence with the verb and core resource front-loaded. It avoids repetition, though for a complex nested-create tool the extreme brevity leaves important behavior unstated.

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 a nested input object with many fields, no field descriptions, and no output schema. The description does not compensate by explaining the shape of the collection object, required identifiers, or what is returned after creation.

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% and the nested collection object contains many fields, none of which are explained in the description. The phrase 'under an accessible account' loosely hints at ownerHandle, but the collection fields like slug, title, about, licence, and review metadata remain semantically opaque.

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 and resource: create a collection, and defines it as a curated group of geospatial datasets. It distinguishes creation from the sibling collection_update_metadata implicitly, though it does not explicitly name the 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 guidance on when to create a new collection versus using an existing one or updating metadata. The phrase 'under an accessible account' hints at an ownership precondition but does not explain prerequisites or exclusions.

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 annotations already disclose that this is a non-read-only, idempotent, non-destructive write operation. The description adds little beyond restating that metadata is updated; it does not explain partial-patch semantics, how null values clear fields, whether omitted fields remain unchanged, or what 'visibility' means given that no visibility field exists in the schema.

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 front-loaded sentence with no wasted words. Its brevity is structurally clean, though it leaves too much unsaid rather than being 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 a complex nested patch object, low schema description coverage, and no output schema, the description is substantially incomplete. It does not explain the patch structure, supported fields, null-clearing behavior, or what changes are returned or confirmed after the update.

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%, and the nested patch object contains many more fields than the description mentions. The description names only title, description, and visibility, while omitting patch semantics and nearly all supported metadata fields. It also references a visibility field not present in the schema, adding confusion rather than 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 states a specific verb and resource ('Update ... metadata of a geospatial collection'), so the general purpose is clear. However, it scopes the tool to title, description, and visibility, while the schema exposes many more fields and contains no visibility property at all. That mismatch can lead an agent to underestimate or misunderstand the tool's actual capabilities.

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 guidance on when to use this tool versus relevant siblings such as collection_create, resource_change_visibility, or source_update_metadata. It also does not mention prerequisites like required permissions or ownership. The agent is left to infer usage from the 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?

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so safety profile is covered. The description adds real value by explaining that the action is already fixed server-side and is not re-specified by the caller, which is why the payload is only a reference. It does not disclose irreversibility, permission requirements, or confirmation expiry behavior, which matters for a destructive operation.

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 sentence, front-loaded with the core action, with examples appended rather than leading. Zero wasted phrasing and nothing needed is 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?

For a single-parameter tool whose annotations and schema cover most structured detail, this is close to sufficient. However, with no output schema and a destructive effect, the description leaves open what happens on success (is the resulting resource returned?), on an expired or already-consumed confirmation, and whether idempotent replay returns the same result.

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 single confirmationId parameter has no structured documentation at all. The description partially compensates by indicating the ID originates from a confirmation_required response, which tells the agent where the value comes from. It says nothing about constraints (32-128 chars), expiry, or reuse, which the schema cannot convey either.

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 ('Execute') on a specific resource ('the exact server-stored action from a confirmation_required response') and gives concrete examples (publishing a map, granting access). An agent can distinguish this from direct mutation tools like map_publish or resource_share_grant, since those are the actions this one confirms. It does not name the counterpart cancel_action, so sibling differentiation is implied 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?

The trigger condition is precise: only call this with an action carried in a confirmation_required response. That is a clear usage context an agent can act on. It does not say when to decline in favor of cancel_action, nor what to do if the confirmation is stale, so it stops short of full alternative routing.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds only that the resource must be 'accessible,' hinting at permission scoping, but does not address not-found behavior, identifier expectations, or return shape.

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 with zero waste. The resource-kind enumeration is compact and directly useful.

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 two-parameter read tool whose annotations cover safety, the description is adequate at a high level. However, with no output schema and no identifier semantics, an agent lacks enough detail about the expected identifier and return value.

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 clarifies the kind enum by mapping map to 'published map' and source to 'dataset,' but says nothing about the identifier parameter's expected format or 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 a specific verb (get) and resource scope, enumerating the four supported resource kinds. It does not explicitly distinguish this generic getter from sibling tools like map_get or resource_view, so it falls short of a 5.

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 gives no guidance on when to use this generic getter versus siblings such as map_get, resource_view, or search. It implies usage but provides no alternatives or exclusions.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. Beyond that, the description discloses conditional output behavior — iframe embed markup is only present when public embedding is enabled, and the publication data reflects the active publication — which is genuinely useful and not in any structured field.

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 sentence, front-loaded with the verb and resource, with the conditional return nuance trailing rather than buried. No 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?

For a one-param read tool with full annotation coverage, the definition is nearly sufficient, and it partially substitutes for the missing output schema by naming the returned fields. It falls short only on error/not-found behavior and on how a caller discovers mapId, which siblings like search or get presumably provide.

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 should compensate, and it never mentions mapId. In practice the single uuid-formatted mapId is self-explanatory and the schema carries its type and pattern, but nothing in the description clarifies which map identifier is expected (e.g. that it must be a published map's id) or what happens for an unpublished or unknown id.

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 a published interactive map") plus an enumeration of exactly what is returned: active publication, canonical URL, iframe embed markup. It does not distinguish itself from closely-named siblings like map_view, map_publication_list, or get, which an agent may hesitate between.

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 word "published" and the conditional "when public embedding is enabled" imply it applies to already-published maps, and by inference map_publish activates publication. But there is no explicit when-to-use, no named alternative, and no guidance on whether map_view or map_publication_list should be preferred for publication details.

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=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context: the export is asynchronous and the output is a PNG, and 'create or reuse' explains the idempotent behavior in practical terms. It does not say what is returned (a job/export identifier), how long it takes, or that the result must be fetched separately, which is the key behavioral fact for an async 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?

One front-loaded sentence with zero padding, which is efficient. It is arguably under-sized for a tool whose schema contains a large nested options object, but nothing in the sentence is wasted.

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 no annotation covering return shape, so the description should explain what an export request yields (an export/job id) and how to retrieve the finished PNG. Combined with a deeply nested options object that has zero parameter documentation, the single sentence is not sufficient for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across all three parameters, and the nested 'options' object exposes roughly ten sub-fields (view, scale, theme, title, width, height, legend, compass, hiddenLayerIds) that are entirely undocumented. 'A project map or published map' loosely maps to the resourceType enum values project/map, but that is the only semantic contribution; resourceId format, view modes (static vs bounds), and all rendering options are left to the agent to reverse-engineer.

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 a specific verb pair ('create or reuse') and names the concrete artifact (an asynchronous PNG image export) and its inputs (a project map or published map). It implicitly separates itself from the sibling map_image_export_status via the word 'asynchronous', but never names that sibling, so differentiation is inferential 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?

There is no statement of when to call this versus map_image_export_status or map_publication_activate, no prerequisites (e.g. the map must be published or validated first), and no follow-up guidance on polling the status tool. The only hint is the adjective 'asynchronous', which the agent must interpret 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The phrase 'once the PNG is rendered' adds the useful readiness/async nuance, but the description never explains the not-ready case — does it error, return a pending status, or block? That is the key behavioral unknown for a polling 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?

A single front-loaded sentence with zero filler; the verb, target, and eventual result are all in the first clause.

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 return value burden falls on the description, and 'return a download capability' is underspecified — expiry, pending/ready distinction, and polling cadence are all missing. Adequate for a simple status check but with clear gaps.

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?

One parameter (exportId) with 0% schema description coverage — the schema only gives a UUID format and pattern, no meaning. The description never mentions exportId or where it comes from (presumably the export-prepare call), so it fails to compensate for the coverage gap.

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: 'poll a map image export' and returns a download capability for the PNG. Clearly a status-check companion to map_image_export_prepare, but the description does not name that sibling explicitly, so differentiation is inferred rather than stated.

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?

'Poll' implies repeated invocation after an export is prepared, but the description never says when to call it (only after map_image_export_prepare?), how often to poll, or when to stop. Usage is implied 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?

Annotations declare readOnlyHint=false and the name says 'activate', but the description describes a 'Preview' — implying a no-side-effect read. With no mention of permission requirements, reversibility, or what happens to the current live publication when rolling back, the description actively misleads rather than informs.

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 short, front-loaded sentence with no padding. Its problem is under-specification, not verbosity, so structure itself is fine.

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 four-required-parameter mutation with no output schema and no parameter documentation, the description supplies no information an agent needs: no concurrency contract, no idempotency behavior, no indication of what the 'preview' returns or whether a second call commits the change.

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% across four required parameters, and the description explains none of them. In particular, 'expectedCurrentPublicationId' (an optimistic-concurrency guard) and 'idempotencyKey' are critical to calling the tool correctly, and neither is mentioned.

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 sentence names a resource ('map publication revision') and a directionality ('forward or back'), but the verb is 'Preview', which contradicts the tool name and title ('Activate'). An agent reading the description would reasonably conclude it is a dry-run, which is not what the name promises. The action it actually performs is never stated unambiguously.

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 guidance on when to call this versus its obvious siblings (map_publish, map_publication_list, confirm_action, cancel_action). The word 'Preview' even implies a two-phase confirm flow that is never explained, leaving the agent unable to tell whether a follow-up activation call is needed.

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, idempotentHint=true, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds only one behavioral trait beyond that — that revisions are immutable and one is marked live — with no detail on ordering, pagination, or behavior for a map with no publications.

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 sentence that front-loads the verb and resource and adds the 'live revision' detail without any filler. Nothing could be removed without losing 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, and the description partially compensates by saying the result includes revisions plus the live indicator. However, it omits return shape details (what a revision record contains, ordering, empty-list behavior) and leaves the sole parameter unexplained, so it is only minimally complete for a read 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 description coverage is 0% for the single mapId parameter, which has only a UUID pattern and no prose. The description implies the scope ('of a map') but never explains that mapId selects the map or what happens if it refers to a non-existent or unpublished map.

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 the immutable publication revisions of a map') and names the distinguishing output ('which revision is live'). This clearly separates it from map_publish and map_publication_activate, though it doesn't explicitly name those 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?

Usage is only implied: an agent can infer this is the inspection step before calling map_publication_activate, but the description never states when to use it, when not to, or names the alternative tools. No prerequisites or preconditions are given.

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 the safety profile (not read-only, not destructive, not idempotent, closed-world), so the description only needs to add context. It contributes the notion that the produced revision is immutable, which is useful, but it omits key behavior: whether the publication goes live immediately or requires a separate activation step, and what happens on a stale expectedCurrentPublicationId.

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 with no filler, and the republish instruction is placed after the primary purpose statement. The only structural weakness is that the ambiguous word 'Preview' sits in the most prominent position.

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, no-output-schema mutation tool, the description is far too thin. It does not explain the concurrency contract implied by expectedSpecVersion/expectedCurrentPublicationId, the role of idempotencyKey, or the relationship to map_publication_activate, leaving the agent to guess at correct usage.

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% across 11 parameters, so the description carries the full explanatory burden and largely fails it. It explains only targetMapId and expectedCurrentPublicationId; projectId, expectedSpecVersion (an optimistic-concurrency guard), idempotencyKey, ownerHandle, visibility, slug, title, and embedEnabled are left undocumented anywhere.

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 names a verb and resource ('publishing a project as a new immutable map revision'), so the agent can tell it is a publish operation on maps. However, the leading word 'Preview' is ambiguous for a tool whose annotations declare readOnlyHint=false: an agent could read this as a dry-run that changes nothing, when it actually creates a revision. The sibling set also contains geobble_map_publication_activate, and the description never clarifies how publish differs from activate.

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 second sentence gives an explicit conditional trigger: set targetMapId and expectedCurrentPublicationId to republish rather than create a new map, which tells the agent how to select republish mode. It stops short of naming alternatives or exclusions (e.g., when to use map_publication_activate or map_publication_list instead), so it is clear context without full routing.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds that it produces a preview, delivery state, and canonical link, which is useful return-shape context, but it does not explain auth needs, the meaning of 'accessible', or any behavioral 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?

A single well-formed sentence with the verb front-loaded and no wasted words. It could be slightly more informative for its brevity, but it is tight and readable.

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 read tool whose annotations cover safety, the description is adequate and even names the returned elements. Gaps remain around the 'accessible' vs 'published' distinction, the meaning of the canonical link, and the absence of output schema/calling details.

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 one required parameter (mapId) with 0% schema description coverage, so the description technically carries the burden but says nothing about it. However, mapId is a single self-evident UUID identifier, so the semantic gap is minor rather than severe; a 3 reflects the small missing clarification over the obvious identifier.

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 (Render) and resource (accessible published map) and enumerates what the render includes (preview, delivery state, canonical link). It is clear what the tool does, but it does not explicitly differentiate from close siblings like map_get or map_publication_list, leaving the agent to infer the distinction.

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 explicit when-to-use guidance or mention of alternatives. The word 'published' implicitly scopes it to published maps, but the agent is not told why it would pick map_view over map_get, map_publication_list, or search_view. No exclusions or prerequisites are 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the useful fact that it always targets the currently connected account rather than a parameterized one, but says nothing about behavior when no account is connected or on auth failure.

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 with zero waste: the first front-loads what is returned, the second front-loads the use case. No filler, no repetition of the title.

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

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

With an output schema present, the description need not explain return values, and with zero params there is no input surface to document. The only missing piece is the unauthenticated/disconnected-account behavior, a minor gap for a trivially simple read 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the description correctly signals the implicit "current session" targeting rather than implying any filter input.

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 and resource ("Return the connected Geobble account") and enumerates the payload fields (identity, display name, email, handle). It implicitly distinguishes itself from account_list by emphasizing the *connected* account, but never names that sibling, so the 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?

It states a clear usage context: "Use it to confirm which geospatial workspace is connected." No exclusions or alternatives (account_list, account_update_profile) are mentioned, which is the main gap, but the positive guidance is unambiguous.

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 non-read-only, non-idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: expectedSpecVersion gates the write to prevent stale-write races. It stops short of saying what happens on a version mismatch or whether the spec version is bumped afterward.

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 sentences, zero filler, and the core action is front-loaded before the concurrency constraint. Every sentence carries distinct information an agent needs.

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 mutation tool with a very deep nested layer schema and no output schema, the description leaves real gaps: it never says what the call returns (new spec version? the layer id?), nor that callers must re-read the project to obtain a fresh expectedSpecVersion for subsequent writes. Adequate but not complete for the complexity involved.

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?

Top-level schema coverage is 0%, so the description must compensate — and it does for the one non-obvious parameter, explaining WHY expectedSpecVersion is required rather than just that it is. projectId is self-evident by format, and title/position carry their own schema descriptions, so the remaining gap is small.

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 ("Add a map layer to a project") plus the accepted origins (dataset, collection, or map in context), so the agent knows exactly what the tool does. It does not distinguish itself from near siblings like project_duplicate_layer or studio_add_layer, which keeps it out of 5 territory.

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 phrase "from a dataset, collection, or map already present in its context" — the caller can infer this is for introducing a new layer rather than modifying an existing one. There is no explicit when-to-use versus project_duplicate_layer, studio_add_layer, or project_create_theme, and no stated preconditions beyond the version field.

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=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds two genuinely useful traits beyond that: 'provider-backed' (an external routing provider is called, implying quota/cost/network dependency) and 'Queue' (the work is enqueued rather than returned inline). It still omits what a queued call returns (a job handle?), how to poll, and any rate/point 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?

A single front-loaded sentence with zero filler; every clause (queue, provider-backed, the five operation families) earns its place. It is not padded, though the terseness trades away information that the next dimensions penalize.

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 high-complexity tool — five mutually exclusive nested operation shapes, 500-point origin arrays, H3 vs contour output, no output schema, no schema field descriptions — one sentence is far from complete. The async lifecycle (job handle, status polling), preview vs materialize semantics, and per-operation input expectations are all 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?

Schema description coverage is 0% and the input is a deeply nested discriminated union, so the description carries real weight — and it does helpfully name the five operation families the `operation.type` const values encode. But it leaves the most consequential top-level fields unexplained: `mode` (preview vs materialize), `attachToProject`, `title`, and `profile` (driving/walking/cycling/truck) get no mention at all.

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?

A specific verb ('Queue') plus resource ('mobility analysis') and an enumeration of the five analysis families (routing, reachability/isochrones, nearest, travel-time metrics, map-matching) that maps onto the schema's operation discriminator. An agent can immediately tell what the tool computes, though it never names or contrasts itself with project_mobility_analysis_status, the status/polling counterpart.

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 when-to-use / when-not guidance and no prerequisites are stated. The word 'Queue' hints at an async submission pattern, but the description never says to poll project_mobility_analysis_status afterwards, nor when to prefer preview over materialize, nor when to reach for project_run_spatial_operation instead.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuinely useful context the annotations cannot convey: expectedSpecVersion exists to prevent stale writes, revealing optimistic-concurrency semantics. It still omits what happens on a version mismatch (error? retry?) and whether the supplied bubble config replaces or merges with existing bubbles.

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 sentences, no filler, with the core action front-loaded and the concurrency constraint second. Nothing could be cut without losing signal.

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?

This is a nested-object mutation tool with no output schema and 0% top-level schema coverage, so the description carries real burden. It leaves unstated whether the config replaces existing bubbles, what the response contains, and what an agent should do when the spec version is rejected.

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?

Top-level schema description coverage is 0%, so the description must compensate and only partly does: it explains expectedSpecVersion's purpose but says nothing about projectId. The nested 'input' object is well annotated in the schema itself (layerId, bubble, linkFilter, artifactsLayer), so the description is not the only source for those.

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 names a specific verb and resource ('Configure bubble interactions for a project map'), so an agent knows it mutates bubble configuration. It does not distinguish itself from adjacent configuration siblings such as project_configure_popup or project_configure_legend, which also 'configure' map presentation.

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 statement of when to use this tool versus project_configure_popup or project_update_layer_style, and no prerequisites or exclusions are given. The only usage-adjacent sentence is about expectedSpecVersion, which is a parameter requirement rather than routing 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?

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation in a closed world. The description adds useful behavioural context by stating that expectedSpecVersion prevents stale writes, but it does not explain the mutation's effects, permission requirements, or what a successful configuration changes.

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 tightly written sentences with no wasted language. The purpose is front-loaded, followed immediately by the critical concurrency prerequisite.

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?

This is a complex nested mutation tool with three required parameters and no output schema, so the description carries more burden. It omits what camera interaction behaviour covers, how the input object is structured, and what the tool returns, leaving significant gaps beyond the safety hints in annotations.

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?

Given the reported 0% schema description coverage, the description should compensate for parameter ambiguity, but it only explains expectedSpecVersion's stale-write guard. It does not explain projectId or the nested input structure, including layerId, title, and camera configuration, so most parameter meaning is left to 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 states a specific verb and resource: configuring camera interaction behaviour for a project map. It clearly distinguishes this from siblings like project_configure_popup or project_configure_legend, though it does not explicitly contrast with adjacent view-related tools such as project_set_view or project_set_layer_zoom_range.

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 implies when to use the tool by naming camera interaction configuration for a project map. However, it provides no explicit when-to-use, when-not-to-use, or alternative-tool guidance, and the expectedSpecVersion note is more of a prerequisite than usage routing.

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 this is a non-readonly, non-destructive, non-idempotent mutation. The description adds useful context that expectedSpecVersion prevents stale writes, but it does not explain the replacement semantics of the computed map, what happens to existing computed fields, or the effect of passing null.

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 sentences with no waste: the purpose is front-loaded and the concurrency guard follows immediately. The description is appropriately sized for a tool definition.

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 a complex nested expression schema, no output schema, and minimal annotation detail. The description identifies the purpose and stale-write guard but leaves major gaps around expression syntax, computed map replacement behavior, null removal, and parameter usage.

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 reported as 0%, so the description needs to compensate but largely does not. It explains only why expectedSpecVersion is required; projectId, layerId, and especially the computed expression map format and keyed variable semantics are not clarified beyond the schema structure.

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 and resource: configuring computed feature fields and expressions for a project map. This clearly distinguishes it from sibling configuration tools such as project_configure_popup, project_configure_legend, and project_configure_search, though it does not explicitly call out those alternatives.

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 implies the tool is for configuring computed expressions on a project map, but gives no explicit when-to-use, when-not-to-use, or alternative guidance. The note about expectedSpecVersion is a parameter constraint rather than usage 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?

Annotations declare a non-readOnly, non-idempotent, non-destructive mutation. The description adds genuinely useful context beyond that: expectedSpecVersion exists to prevent stale writes, telling the agent this is an optimistic-concurrency write. However, it does not say whether configuring a legend replaces or merges existing legend entries, or what happens when legend is null.

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 action and followed by the one non-obvious constraint. No filler and nothing needs to be reordered.

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?

This is a non-idempotent mutation with a deeply nested legend payload and no output schema, yet the description omits replace-vs-merge semantics for entries, per-type requirements (item type must match layer geometry), and whether a null legend disables the legend entirely. Those are the details most likely to cause a wrong 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?

Top-level schema description coverage is 0%, and the description explains only one of three required parameters: the purpose of expectedSpecVersion (stale-write prevention), which the schema alone does not convey. It says nothing about the shape of `input`, layerId, or projectId beyond what the nested schema documents.

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: configuring a project map's legend and its entries. It is clearly distinct from the styling/popup siblings, though it never explicitly contrasts itself with project_update_layer_style or project_configure_popup, so the differentiation is implicit.

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 sibling tools such as project_update_layer_style or project_configure_popup, and no exclusions or prerequisites. The only usage-adjacent statement is the concurrency note, which is a requirement rather than routing 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?

The annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation. The description usefully adds that expectedSpecVersion is required to prevent stale writes, which explains optimistic concurrency behavior. It does not explain whether the popup config replaces existing settings or what errors occur on version mismatch.

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: the purpose is front-loaded and the concurrency requirement follows immediately. There is no boilerplate or wasted wording.

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 mutation tool with a complex nested schema and no output schema, the description covers the high-level purpose and the version prerequisite. It leaves out replacement semantics, error behavior on stale versions, and when to use it instead of related popup/bubble tools, so it is only minimally 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 reported as 0% at the top level, though nested fields have some documentation. The description only adds meaning for expectedSpecVersion, explaining its stale-write prevention role; it does not clarify projectId, layerId, or the nested input structure beyond what the schema already contains.

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 and resource: configuring popup presentation and feature attributes in a project map. It is clear what the tool does, but it does not explicitly distinguish itself from siblings like studio_set_basic_popup or project_configure_bubbles.

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 does not say when to choose this tool over studio_set_basic_popup or project_configure_bubbles, nor does it describe prerequisites beyond the expectedSpecVersion concurrency requirement. Usage is only implied by the tool name and purpose statement.

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 disclose that this is a non-readOnly, non-destructive, non-idempotent mutation. The description adds useful behavioral context by explaining that expectedSpecVersion prevents stale writes, but it does not clarify replacement-versus-partial-update semantics or other side effects.

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 with no wasted language. The core purpose is front-loaded, and the concurrency constraint follows immediately.

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 non-idempotent mutation with a nested input object and no output schema, the description is too thin. It omits how the search configuration is applied, what layerId and title require, and what behavior to expect when search is replaced or disabled.

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 reported as 0%, so the description needs to compensate for the three required parameters. It only explains expectedSpecVersion as a stale-write guard and says nothing substantive about projectId or the nested input object.

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 a specific verb and resource: 'Configure how search behaves in a project map.' This clearly distinguishes it from search tools like search and search_view, though it does not explicitly name those alternatives.

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 states that the tool configures project-map search but gives no guidance on when to use it instead of search, search_view, project_update_settings, or other project_configure_* siblings. The only usage-relevant detail is the expectedSpecVersion staleness guard.

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 a non-destructive, non-open-world write, and the description adds two real behavioral facts: the new project starts empty and is private by default, and it requires account-level create permission. It says nothing about duplicate-title behavior, quotas, or what identifier comes back, so the added context is useful but thin for a creation 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?

A single front-loaded sentence with the action first and the definitional parenthetical after it; nothing is redundant. It is dense but every clause (empty, private, permission-gated) carries information an agent needs.

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, no parameter descriptions, and no annotations explaining the response, the description should say what a successful call yields (project id/handle) and what happens if basemap IDs are omitted. Neither is covered, leaving gaps an agent would hit on its first invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across four parameters, so the description must carry the load — but it only obliquely covers ownerHandle ('under an account') and never mentions title, basemapIdDark, or basemapIdLight. The two basemap UUID parameters and any default behavior when they are omitted are entirely undocumented.

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 ('Create an empty private project') and immediately defines what a project is — a geospatial workspace holding map layers, datasets, styles, and analysis results. The scoping words 'empty' and 'private' separate this from the many project_* siblings that mutate an existing project, so an agent can identify it without opening the 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?

Gives a clear precondition — the caller must have create rights on the target account ('under an account where the caller can create') — which tells the agent when the call is valid. It stops short of naming exclusions or pointing at an alternative when the account lacks permission (e.g., a request/approval flow), so it falls just short of explicit 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?

Annotations already declare readOnly=false, destructive=false, idempotent=false, and openWorld=false, so the safety profile is carried by structured data. The description adds useful context: the theme is owned by the project account and gets attached to the project. What it omits matters, though — idempotentHint=false means repeated calls likely create duplicate themes, and no warning or duplicate-title behavior is given.

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 tightly written sentence with no filler, and the core verb+resource is front-loaded. The ownership and attachment clauses earn their place. There is no structure beyond the single sentence, which is fine for a two-parameter tool.

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 should ideally say what is returned (the created theme identifier, for instance) so the agent can chain it into a later update call. It also leaves the nested input wrapper unexplained. For a create-with-nested-payload tool, this is adequate but has clear gaps.

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?

Top-level schema description coverage is 0%: projectId carries no description anywhere and the input object itself is undocumented. The nested fields (title, type, colors, description) are described in the schema, so the description could have compensated by explaining the projectId requirement or the input wrapper. It says nothing about parameters at all, adding zero semantic value 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?

States a specific verb (Create) and a precise resource (cartographic colour theme), plus two behavioral facts: it is owned by the project account and attached to the project. It is distinguishable from every sibling because none of them touch themes. It stops short of naming a sibling to contrast with, but the uniqueness of the resource makes that less necessary.

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 explicit when-to-use guidance, no prerequisites, and no stated conditions for creating a new theme versus reusing an existing one. The word 'reusable' hints at intent but the agent is left to infer the trigger. 'Attach it to the project' implies the theme is created in a project context but does not clarify whether an existing theme can be attached separately.

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 establish this is a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds real context beyond them: duplication preserves canonical GMS validity and uses optimistic concurrency via expectedSpecVersion. It does not disclose what is copied (style, filters, visibility) or how failures/stale version errors surface.

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 the core action front-loaded and the version precondition immediately after. No padding or repetition.

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 nested-input mutation with no output schema and three required parameters, the description covers the action and the version guard but omits what the duplicated layer inherits and what the response contains. Adequate but with clear gaps an agent would want filled.

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 low: title and layerId are described in the nested schema, but projectId and expectedSpecVersion are not. The description usefully explains that expectedSpecVersion guards against stale writes, adding meaning the schema lacks. However, it leaves projectId and the relationship between title and the duplicate's name undescribed.

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 names a specific verb and resource: duplicate a map layer. That makes its difference from siblings like project_add_layer or project_update_layer_style evident, but it does not explicitly state how it relates to those siblings. The purpose is clear, but it lacks sibling 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?

The description offers no guidance on when to duplicate a layer versus using project_add_layer or project_update_layer_style. It only notes that expectedSpecVersion is required to prevent stale writes, which is precondition guidance rather than usage routing.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds nothing further: it doesn't say what 'inspect' yields, whether results are truncated, or how large collections behave, all of which matter given the limit parameter exists to prevent huge responses.

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 with no filler, which is efficient. That brevity, however, tips into under-specification rather than economy — there is no second sentence carrying the guidance the tool needs.

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

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

With a nested input object, two required parameters, 0% schema description coverage and no output schema, the definition should explain the input shape and roughly what is returned. Instead it leaves the agent to reverse-engineer the nested payload and result format from the schema alone.

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 reported as 0% and the description mentions neither projectId nor the nested input object, so nothing clarifies how collectionId and limit are supplied. The pagination cap (default 50, max 100) is a key semantic the description could reinforce but does not.

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 pair ('list and inspect') and a concrete resource ('geospatial datasets in a collection attached to the project'), so the agent knows the operation is a scoped read of collection contents. It does not name or distinguish itself from near siblings like project_inspect_source or search_view, which is what a 5 would require.

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 and no mention of alternatives, despite many sibling tools that also read project/source data (project_inspect_source, search_view, resource_view). The agent must infer selection criteria from names 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the useful nuance that inspection surfaces provenance and freshness metadata plus a bounded sample, but it does not mention that sampling only applies to queryable sources or what happens for non-queryable ones.

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 with zero filler; the four inspected facets are packed efficiently. It is arguably too terse for a tool with a nested input object, but nothing in it is wasted.

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 does the minimum by enumerating what is returned (schema, provenance, freshness, sample). It omits when to prefer this over other read tools and any caveats about sources that are not queryable, leaving meaningful gaps for a two-parameter nested-input 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?

The schema itself carries strong descriptions for both parameters (namespaced sourceId format, sampleRows default 5 / max 20 / 'use 0 for schema-only inspection'). The description's phrase 'a small sample of features' is consistent with that but adds no syntax or behavioral detail the 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?

The description uses a specific verb ('Inspect') and enumerates the concrete facets returned: attribute schema, provenance, freshness, and sample features. That clearly separates it from sibling mutators like source_update_metadata or source_import_url, though it does not explicitly name a sibling 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 statement of when to call this versus alternatives such as project_query_database, resource_view, or source_update_metadata. The agent must infer from the name that this is a pre-flight/preview inspection step, which is exactly the guidance the description should supply.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the returned basemap categories, which is useful context, but it does not explain project scoping, authorization needs, or return shape, leaving meaningful 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?

A single, front-loaded sentence with no wasted text. It states the verb, resource, and valid values immediately.

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 listing tool with full schema coverage and rich safety annotations, the description is mostly sufficient. However, it never explains how the 'project' is identified when there is no project parameter, and with no output schema it could better indicate what the response contains beyond the category names.

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 both parameters are enums with documented values, so the schema carries the parameter burden. The description's list of light, dark, vector, raster, and DEM loosely maps to those enum filters but adds little 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 uses a specific verb ('List') and resource ('valid basemaps available to a project') and enumerates the categories returned. It clearly tells an agent what the tool does, though it does not explicitly contrast with the obvious sibling project_set_basemap.

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 read-only listing purpose, but the description gives no explicit when-to-use, when-not-to-use, or alternative (e.g., project_set_basemap) guidance. An agent must infer that this is a discovery call.

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 readOnly=false, idempotent=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds real value by describing the effect of an add (visibility to project layer and query tools), but it is silent on what a remove actually does — whether the underlying resource is deleted or merely detached — which is exactly the ambiguity destructiveHint=false is trying to settle.

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 stated first and the operational consequence second. Nothing to trim and nothing 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?

For a 5-parameter mutation with no output schema, the description covers the primary effect but leaves a meaningful hole: the semantics of removal and the purpose of the optional 'title' field. Annotations pick up the safety and idempotency slack, so it is adequate rather than deficient.

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 carries the burden, and it only partially does: it names the resourceType values (source, collection, symbol_set, theme) and implies the add/remove action, but those mirror enum values already in the schema. The fifth parameter, 'title', is never mentioned anywhere, and there is no note on resourceId needing to correspond to the chosen resourceType.

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 pair (add/remove) plus a precisely scoped resource (a project context) and an enumeration of the four manageable resource types. Clear enough to distinguish from layer-editing siblings, though it never explicitly contrasts itself with project_add_layer / project_remove_layers, which an agent could plausibly confuse it with.

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 sentence 'Adding a resource makes it available to project layer and query tools' implies a use case (call this before layer/query tooling), but the guidance is only implicit. There are no exclusions, no prerequisites (must the resource already exist? must the agent have share rights?), and no mention of when removal is appropriate.

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 description explicitly says the tool can delete layer groups, but the annotations declare destructiveHint=false. That is a direct contradiction for a tool whose stated scope includes deletion. The expectedSpecVersion note adds useful stale-write context, but the annotation conflict is a serious transparency problem.

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 sentences, both front-loaded and free of filler. The action scope comes first, followed by the only non-obvious constraint.

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 description covers the tool's multi-action purpose and the versioning guard, but a mutation tool with a delete action and no output schema would benefit from clearer action-specific consequences. It is minimally adequate given the rich nested schema.

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 reported as 0%, but the nested schema properties do document action, group fields, title, and layerIds. The description adds meaningful semantics only for expectedSpecVersion (stale-write prevention), while projectId and action-specific requirements remain largely schema-defined.

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 and a clear resource: "Create, update, delete, or assign layer groups in a project map." That distinguishes it from sibling tools like project_add_layer or project_reorder_layers, though it does not explicitly name 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?

The description implies usage through the action list and explains that expectedSpecVersion prevents stale writes, but it does not say when to choose this tool over related siblings such as project_add_layer or project_remove_layers, nor does it state exclusions or preconditions.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that the job was 'queued' and that a result may be returned, without disclosing possible status values, whether a result is partial until completion, or any retention/expiry behavior.

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 with zero filler, well matched to the simplicity of a two-parameter read. Nothing is padded and nothing is front-loaded after the point.

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 carries the burden of describing return content, and 'status and result' is the extent of it — no enumeration of states or shape of the result payload. Adequate to call correctly, not adequate to interpret the response.

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% and the description mentions neither parameter. Crucially it never states that runId is the job identifier returned by the submission call (or that it is a UUID), which is the one piece of semantics an agent could get wrong on a status-polling tool.

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 (Read) plus specific resource (status and result of a queued mobility analysis job), and the word 'queued' links it to project_analyze_mobility as the submitter. It stops short of naming that sibling explicitly, so an agent must infer the pair rather than being told.

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?

'Queued ... job' implies this is the polling counterpart of project_analyze_mobility, so the usage is inferable. But there is no explicit statement of when to call it, how often to poll, whether to stop on a terminal status, or which alternative to use for starting a job instead.

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 declare readOnlyHint=false with destructiveHint=false, and the description usefully explains that tension: query execution is read-only but 'materialisation of derived datasets' creates a new source, which is real added context beyond the annotations. It does not disclose cost/row limits, permission requirements, or whether materialising is persisted permanently, and openWorldHint=false/idempotentHint=false go unaddressed. Not a contradiction, but incomplete for a tool that can write.

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: operation, engine, data domain, and mode all appear before any embellishment, with no wasted clauses. It is dense to the point of being slightly compressed (two em-dash asides), but nothing repeats the title or name.

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 tool with a nested input object, a mode toggle, and no output schema, the description leaves the agent guessing what 'preview' returns (row shape? row cap? column metadata?) and what a materialised derived source looks like afterwards. The SQL dialect and data domain are covered, but return and side-effect expectations are not.

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 reported as 0%, and the top-level projectId has no description at all, so the description is expected to compensate — it does not. It says nothing about what projectId selects, that 'title' is required when action=materialize, or anything about the DuckDB table-naming convention, all of which are only discoverable by reading the nested 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?

States a specific verb and resource: run read-only DuckDB SQL over the project's GeoParquet data, and enumerates the operations (filter, aggregate, join, measure) plus the optional materialisation mode. It clearly differs from configuration-style siblings like project_update_layer_style, but never contrasts itself with the nearest analytical alternatives such as project_run_spatial_operation or project_analyze_mobility.

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 when-to-use or when-not-to-use guidance, and no named alternatives. The only mode distinction (preview vs materialize) lives in the schema, not the description, so the agent must infer from the phrase 'optional materialisation' when to switch modes or when to reach for a different analytical tool.

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 destructiveHint=true and idempotentHint=false, so the agent knows this is a permanent mutation. The description adds a valuable, non-obvious behavioral detail: expectedSpecVersion guards against stale writes, implying optimistic concurrency and possible rejection. It does not state whether removal is reversible or what happens to layer data, which is a gap for a destructive operation.

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, no filler, and the destructive action is stated first followed by the critical precondition. 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?

For a destructive, nested-parameter mutation with no output schema, the description covers the main action and one key constraint, and annotations cover the safety profile. It still leaves the version-conflict behavior and the source of expectedSpecVersion unexplained, which an agent needs in order to call this reliably.

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?

Top-level schema coverage is 0%: projectId and expectedSpecVersion have no schema descriptions. The description compensates for exactly one of these by explaining the purpose of expectedSpecVersion (stale-write prevention), which is real added meaning beyond the bare integer constraint. It says nothing extra about projectId, and layerIds' semantics live only in the nested 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?

States a specific verb ('Remove') and resource ('one or more layers from a project map'), which is unambiguous on its own. It does not explicitly differentiate from siblings like project_add_layer or project_reorder_layers, but the destructive/additive distinction is obvious from the verb.

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 second sentence implies a precondition for use (a valid expectedSpecVersion to avoid stale writes), which hints at the concurrency workflow. However, there is no guidance on when to choose this over sibling layer tools, nor what to do when the version is stale or where the version comes from.

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=false, destructiveHint=false, idempotentHint=false, so the write/safety profile is covered structurally. The description adds genuinely new behavioral context: the optimistic-locking contract via expectedSpecVersion preventing stale writes. It omits the failure mode (e.g., conflict error on version mismatch), whether the reorder is atomic, and that the operation overwrites the entire existing order.

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 sentences, purpose front-loaded, followed by the one non-obvious constraint. No filler, no restating of the title, no wasted words.

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 3-required-parameter mutation with a nested input object and no output schema, the description covers the purpose and the concurrency guard but leaves out error/conflict behavior, permission requirements, and the destructive-replacement semantics of the full ordered list. Adequate but with clear gaps for a write tool whose annotations say idempotentHint=false.

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?

Top-level schema description coverage is 0%, but the description supplies the single most important semantic: expectedSpecVersion exists as a stale-write guard, which the schema alone does not convey. The nested layerIds and title fields are documented in the schema, but projectId and the consequences of an incomplete layerIds list are not explained anywhere — leaving a compensating gap.

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: 'Change the draw order of layers in a project map.' This is clearly distinct from siblings like project_set_layer_visibility or project_update_layer_style, which touch other layer attributes. It does not explicitly name a sibling to disambiguate against, which keeps it from a 5.

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 gives one real usage condition — that expectedSpecVersion must be supplied to avoid stale writes — which tells the agent it is a concurrency-guarded mutation. However, it never says when to use this versus project_add_layer / project_remove_layers / set_layer_zoom_range, nor what happens if the caller omits or mismatches the version. Usage is implied rather than spelled out.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds nothing beyond purpose: no note that forward geocoding can return multiple ambiguous candidates per query, how the limit applies per query vs. overall, or how results are ordered. With rich annotations the bar is lower, but there is essentially zero added behavior here.

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 well-formed sentence with the primary verb and both modes front-loaded; no filler or redundancy. It is efficient, though its terseness means it leaves real gaps rather than being genuinely complete.

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?

This is a dual-branch (oneOf) tool with a limit cap, bbox/language/countryCode context, and up to 10 queries per forward call, and there is no output schema. A single sentence covering only the two directions is not enough for an agent to call it correctly without reading the full schema.

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 reported at 100%, so the schema is the primary documentation source and a 3 is the baseline. The description does implicitly map 'place names' to the queries/forward branch and 'coordinates' to latitude/longitude/reverse, which helps orient the agent to the oneOf structure, but it says nothing about limit, context.bbox, language, or countryCode.

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?

Names two concrete operations (forward geocoding of place names, reverse geocoding of coordinates) with clear verbs and resources, so the agent immediately knows the domain. It does not differentiate itself from any sibling (e.g. project_configure_search, map_get, search), which keeps it below a 5.

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 two directions implicitly tell the agent which mode to pick based on whether it holds names or coordinates, but there is no explicit 'use X when you have Y' statement, no mention of the action enum values 'forward'/'reverse' by name, and no guidance on when a different tool (map_get, project_configure_search) would be better.

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=false, destructiveHint=false and idempotentHint=false; the description usefully adds that results are persisted as derived output rather than computed transiently. It does not disclose whether repeated runs create duplicate layers (relevant given idempotentHint=false), whether the operation is synchronous or job-based, or what permissions/state the project must be in.

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 with no filler. The parenthetical operation list is the only questionable content: it partly duplicates the schema enum and is inaccurate, so it does not fully earn 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 mutating, nested-parameter, non-idempotent operation with no output schema, the description omits what is returned (derived layer ID? job handle?), whether execution is async, and how the operation enum interacts with single- vs multi-layer sources. The agent would need the schema plus guesswork to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description says nothing about parameters, and its operation list conflicts with the enum, so it adds no meaning beyond the schema (which itself does document operation, sourceId, secondarySourceId and the params sub-fields). It never explains which operations require distanceMeters, keyA/keyB, or groupBy, and with schema coverage reported at 0% the description fails to compensate.

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 ('Run') and resource ('predefined spatial operation') and enumerates example operations, so the agent can distinguish it from siblings like project_inspect_source or project_analyze_mobility. However, the parenthetical list ('union', 'proximity', 'spatial join') does not match the schema enum (bounds, buffer, centroid, dissolve, clip, countPoints, intersect, join, subtract), which weakens the otherwise clear statement of purpose.

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 choose this tool over the many project_* siblings (e.g., project_analyze_mobility, project_query_database, project_add_layer), and no prerequisites such as the project needing existing sources. The phrase 'predefined spatial operation' hints at a fixed catalog, but the agent must open the schema to learn the actual conditions.

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 this a non-read-only, non-idempotent mutation, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: expectedSpecVersion exists to prevent stale writes, i.e., optimistic concurrency enforcement. It still doesn't say whether unspecified basemap slots are cleared or preserved, or what permissions are needed.

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 with zero waste; the core action is front-loaded and the versioning guard follows immediately. Nothing to trim.

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 nested-input mutation tool with no output schema and only generic annotations, the description covers purpose and the concurrency guard but omits what happens to existing basemap assignments, the required title field in the input object, and any error/return expectations. Adequate minimum, with clear gaps.

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?

Top-level schema coverage is 0%: projectId and expectedSpecVersion carry no descriptions. The description compensates for expectedSpecVersion ("required to prevent stale writes") and conveys that light/dark basemaps are optional ("and/or"), but gives no meaning for projectId and doesn't mention the required input.title field. Partial compensation only.

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 ("Assign") and resource ("light and/or dark basemaps to a project map"), which is clearly distinct from the sibling project_list_basemaps. It stops short of naming that sibling or explicitly contrasting read vs. write, so it is clear but not fully sibling-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 the verb and the sibling set (project_list_basemaps exists for discovery), and the description adds the prerequisite that expectedSpecVersion is required. However, it never says when to use this vs. alternatives, nor that basemap IDs should be obtained from project_list_basemaps first.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds real context: the filter is 'validated' (calls can fail validation) and expectedSpecVersion exists to prevent stale writes. It does not say what error surfaces on a version mismatch, but the concurrency contract is a genuine addition beyond the 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 sentences, no waste, with the core action front-loaded and the concurrency requirement immediately after. Nothing is repeated from the schema or annotations.

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 nested-object mutation tool with no output schema, the description covers the action, the validation risk, and the optimistic-concurrency requirement. It stops short of noting the failure mode on a stale version or the required permissions, but the essential calling contract is present.

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 reported as 0% at the top level, so the description must compensate: it explains why expectedSpecVersion is required (stale-write protection) and that filter can be cleared, which the schema's 'anyOf null' only hints at. However, projectId is left unexplained and the GMS expression array format is not described anywhere, so compensation is partial.

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 pair ('Set or clear') plus the resource ('validated attribute filter') and its effect ('controlling which features a layer draws'). This is easily separable from siblings such as project_set_layer_visibility, project_set_layer_zoom_range, and project_update_layer_style.

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?

'Set or clear' implies the two modes of use and the null-filter behavior, but the description never states when an agent should prefer this over, say, project_update_layer_style or project_configure_computed, nor any prerequisites (layer type support, permissions). 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=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: expectedSpecVersion exists for optimistic concurrency control against stale writes. It does not say what happens on a version conflict, whether the write bumps the spec version, or whether setting the same visibility twice is a no-op, so it is additive but incomplete.

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 sentences, no filler, and the core action is front-loaded before the concurrency caveat. Nothing is redundant with the title.

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?

This is a non-idempotent mutation with a nested input object, no output schema, and no annotation detail about failure modes. The agent is left guessing how to source expectedSpecVersion, what a version mismatch returns, and whether the response includes the new spec version needed for subsequent calls. The description covers the action but not enough of the calling contract.

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 reported at 0%, so the description needs to carry the load. It only explains the purpose of expectedSpecVersion; projectId and the nested input object (layerId, visibility) get no explanation of format, source, or interaction. The inline enum on visibility partially compensates, but overall coverage is thin for a nested three-parameter tool.

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: 'Show or hide one layer in the project map.' That clearly separates it from sibling layer tools like project_set_layer_filter, project_set_layer_zoom_range, and project_update_layer_style. It stops short of explicitly naming those siblings, so a 4 rather than a 5.

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 guidance on when to reach for this tool versus the many adjacent layer-configuration siblings, and no stated prerequisites such as required permissions or how the caller should have obtained a valid spec version. The only contextual hint ('required to prevent stale writes') explains a parameter, not when to use the tool.

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 it as a non-read-only, non-idempotent mutation. The description adds real value beyond that by stating that expectedSpecVersion exists to prevent stale writes, which is a behavioral concurrency contract not encoded anywhere in the structured fields. It stops short of saying what happens on a version mismatch or whether unspecified bounds are preserved.

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: the action first, the critical precondition second. Nothing redundant, no 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?

For a mutation with a nested input object and no output schema, the definition leaves meaningful questions open: whether omitted minZoom/maxZoom reset to the documented defaults (0/22) or preserve existing values, and how a stale expectedSpecVersion surfaces to the caller. Annotations cover the safety profile, so this is adequate but with clear gaps.

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?

Top-level schema coverage is 0%, so the description must carry the load, and it does for the one genuinely non-obvious parameter by explaining expectedSpecVersion's anti-stale-write purpose. The nested input properties (layerId, title, minZoom, maxZoom) are already documented in the schema, so the remaining unmentioned projectId is a minor gap.

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: setting a layer's minimum and maximum visible zoom levels. This is concrete enough to distinguish it from siblings like project_set_layer_visibility or project_set_layer_filter, though it never names those alternatives explicitly.

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 implies usage (editing a layer's zoom visibility window) and explains the concurrency precondition for expectedSpecVersion, but gives no explicit when-to-use/when-not guidance or pointers to sibling tools such as project_update_layer_style.

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=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context not present in structured fields: expectedSpecVersion exists to protect persisted changes from stale writes, which tells the agent that save is an optimistic-concurrency operation. It omits what happens on a version mismatch (error vs merge) and any auth/session requirement.

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 sentences, zero filler, with the purpose stated first and the version-guard caveat second. Appropriately front-loaded, though for a nested oneOf schema the brevity edges toward under-specification rather than efficiency.

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 is structurally complex (nested input with a three-way camera union, no output schema), so the description should do more. It covers purpose and the concurrency guard but says nothing about return values, what save changes for other users, or how a live navigation session must be established.

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 carries the full burden, yet it explains only expectedSpecVersion. projectId is undocumented and the input object's camera variants (static/bounds/layer-extent) and timing config are left entirely to the raw schema shapes.

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 pair of verbs and their resources: 'Navigate the live project camera' and 'persist a default view'. That is concrete enough to act on. It does not, however, distinguish itself from the sibling project_configure_camera or map_view, both of which plausibly touch the same camera state.

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 two modes are named ('navigate' vs 'persist a default view'), which implies the choice, but the description never states when to prefer one, nor points to project_configure_camera as the alternative for camera configuration. Usage must be inferred from the action enum in the schema rather than from the description.

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 indicate this is a non-destructive, idempotent write operation with no open-world access. The description adds useful context that the request is 'private' and tied to the project owner, but it does not describe what happens after submission, whether the request is visible to others, or what the response contains.

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 well-formed sentence that is front-loaded with the core action and includes the key prerequisite condition. There is no wasted wording.

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 five-parameter mutation/request tool with no schema parameter descriptions and no output schema, the description is too thin. It does not explain the roles of the optional parameters or what happens after submission, leaving significant gaps for an agent to infer.

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% across five parameters, so the description must compensate. It only broadly implies what is being requested ('missing geospatial data') and for whom ('project owner'); it does not explain dataset, geography, requirements, or knownSourceUrl, leaving most parameters undocumented.

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 action: submitting a private request for missing geospatial data on behalf of the project owner. It implicitly distinguishes itself from catalogue-search tools by saying this is used after search found nothing suitable, though it does not explicitly name a 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?

The phrase 'after catalogue search found nothing suitable' gives a clear contextual trigger for when to use this tool. However, it does not name the alternative search tool or state explicit exclusions, 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?

Annotations already declare the tool as a non-read-only, non-destructive, non-idempotent mutation. The description adds useful context that expectedSpecVersion prevents stale writes and that labels can be cleared, but it does not explain permissions, side effects, or return behavior.

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 wasted language, and the core operation is front-loaded before the versioning caveat.

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 mutation tool with annotations and no output schema, the description covers the main action and concurrency requirement but omits return expectations. The complex nested label object is left mostly to the schema.

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 explains the purpose of expectedSpecVersion, which is valuable, but it adds no meaning for projectId or the nested input object beyond what the schema already documents for layerId, label, and title. With low schema description coverage, this partial compensation leaves significant gaps.

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 a specific verb and resource: 'Configure or clear the label definition for a map layer.' This clearly distinguishes label configuration from sibling styling and visibility tools, though it does not explicitly name those alternatives.

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 phrase 'Configure or clear' implies when the tool is used, and the expectedSpecVersion note gives a prerequisite, but there is no explicit guidance on when to choose this tool over project_update_layer_style or other layer tools.

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

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

Beyond the annotations, it usefully discloses that changes are a merge (partial update rather than replacement) and that expectedSpecVersion guards against stale writes — real behavioral context. However, it does not say what happens on a version conflict, whether nested display metadata is also merged, or whether the call is restricted to existing layers. With no destructive or readOnly signal to add (annotations already cover that), the concurrency semantics are the main contribution — substantive, 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?

Two tight sentences, front-loaded with the action and scope; the concurrency constraint follows. Nothing is padded, though a bit more content could have been justified given the tool's complexity.

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

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

For a mutation tool with seven layer-type variants, a deeply nested paint/display payload, no output schema, and only generic annotations, the description is thin: it never addresses version-conflict behavior, layer-type-specific paint keys, or what the merge returns. The essentials for calling it are present, but not the essentials for calling it correctly under contention.

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?

Top-level schema description coverage is 0%, so the three required parameters carry no docstrings, but the description explains the purpose of expectedSpecVersion and maps the paint/display payload to concepts like colours, ramps, opacity, and stroke. It adds nothing about layerType variant selection or the meaning of styleBy/vizType/rampDomain, leaving most of the heavy nested surface to 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?

States a specific verb (merge) and resource (a map layer's symbology) and enumerates the affected facets (colours, ramps, opacity, stroke). It does not name a sibling such as project_set_layer_filter or project_update_layer_label, so the boundary against adjacent tools is left to inference, but the operation itself is unambiguous.

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

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

The description implies use for restyling an existing layer and mentions the optimistic-locking requirement, but gives no explicit when-to-use/when-not guidance and no pointer to which sibling to pick instead (e.g. label vs filter vs visibility updates). An agent must infer the selection rule.

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 it is a non-destructive, non-open-world write, so safety framing is covered; the description adds genuinely non-structured behavior: merge semantics (partial rather than full replacement), optimistic concurrency, and canonical GMS validation. It stops short of saying what happens on a spec-version conflict (error vs. retry) or what permissions the Workspace-owned settings require.

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 dense sentence with the merge semantics front-loaded and no filler. It is appropriately sized for a one-purpose mutation, though the trailing 'with optimistic concurrency and canonical GMS validation' clause is compressed to the point of jargon.

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 nested-object mutation with no output schema, the description gives the merge and validation model but omits conflict/error behavior, required permissions on Workspace-owned settings, and any mapping from the four required parameters to the described concepts. Adequate, with clear remaining gaps.

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% for 4 required parameters, including a nested 'settings' object, so the description must carry the burden and largely does not. It gestures at setting categories (camera, metadata) but never explains expectedSpecVersion or projectId, and does not clarify the relationship between the top-level 'title' and the nested settings.title.

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 ('Merge ... into a project') plus the resource ('Workspace-owned map settings') and an enumeration of what is covered: camera, interactions, metadata, computed fields. It is clear what the tool does, but it does not distinguish itself from adjacent siblings such as project_configure_camera, project_configure_computed, or project_set_view, which appear to touch the same sub-areas.

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 statement of when to use this versus the many per-feature configure/set siblings, nor any exclusion or prerequisite beyond the implicit optimistic-concurrency requirement. The agent must infer the routing decision entirely from the field list.

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 establish that this is a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds useful behavioral scope by listing the validation categories, but it does not disclose what a validation result looks like, whether failures are reported per check, or how partial or failed validation should be interpreted.

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 front-loaded sentence with no filler. Every listed item corresponds to a validation concern and 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, so the description should explain return values or at least the shape of a validation result, but it does not. Combined with the lack of parameter explanation and absence of usage guidance, the definition is incomplete for a nested-object validation 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 description coverage is reported as 0%, so the description should compensate, but it only vaguely references 'expected outputs' and does not explain projectId, the input.reason field, or the structure and semantics of expectedOutputs entries. The nested schema contains some descriptions, but the tool description itself does not add meaning beyond a passing mention.

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 (validate) and resource (project map), and enumerates the validation dimensions: canonical GMS, renderer compatibility, referenced resources, and expected outputs. It is clearly distinct from sibling mutators like project_add_layer or project_set_basemap, though it does not explicitly name or contrast a sibling tool.

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 does not state when to use this tool, when not to use it, or which alternatives to consider. There is only an implied usage from the schema's example reason, "before final response," but the description itself provides no routing 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered elsewhere. The description contributes the useful detail that the return is a 'full map specification' (complete snapshot rather than a diff or summary), but says nothing about behavior on invalid or nonexistent versions.

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 with no filler; the historical qualifier lands immediately after the resource. Nothing to trim and nothing 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?

For a two-parameter read-only tool with no output schema, the description covers the essentials of what is returned ('full map specification'), but leaves the nested input object and version-selection mechanics undocumented. An agent could call it, but would have to open the schema to learn how versions are discovered.

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 reported at 0%, so the description must carry parameter meaning and it largely does not — 'prior version' only obliquely gestures at the version parameter and never mentions projectId. Neither the accepted version range nor the 'use the history list to see available versions' guidance appears in the description.

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 ('Read') plus a precisely scoped resource ('full map specification of a project as it was at a prior version'), which clearly separates it from live-view siblings like map_view or project_update_settings. It does not name any sibling explicitly, so differentiation is by inference rather than statement.

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 phrase 'as it was at a prior version' implies the use case (historical inspection) but never states when to prefer this over the current-state view, nor any prerequisite such as needing a version number from a history listing. That hint exists only in the schema's version field, not in the description.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description earns credit beyond that by signaling that the result is *effective* (computed) access including inheritance — meaning inherited/organizational permissions are folded in, which an agent would otherwise not assume. It stops short of stating permission prerequisites or behavior when the caller lacks access.

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 compact sentence, front-loaded with the verb and payoff, listing the three facets in a natural order. No padding, though the colon-fragment style drops the subject and reads slightly clipped.

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 two-parameter read tool with rich annotations and no output schema, the description usefully previews what comes back (visibility, inheritance, shares). However it omits whether the caller needs owner/admin rights and how an unshared or inaccessible resource is reported, which matters for a permission-inspection 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 description coverage is 0% and the description compensates minimally: it says 'geospatial resource' but never explains that resourceId is a UUID or that resourceType must match the actual resource kind. The six enum values are self-explanatory in the schema, but the pairing constraint between the two required parameters is undocumented anywhere.

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 (inspect) and resource (effective access to a geospatial resource) plus the facets revealed: visibility, inheritance, and individual/organization shares. An agent can distinguish it from the mutation siblings resource_share_grant/resource_share_revoke and resource_change_visibility by the read-only 'inspect' framing, though it never names them explicitly.

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: 'inspect effective access' suggests a read-only diagnostic to run before sharing or visibility changes, but the description never says when to choose this over resource_view, resource_share_grant, or resource_change_visibility. No preconditions or exclusions are given.

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 description says 'Preview publishing or unpublishing,' which strongly implies a read-only dry run, but annotations declare readOnlyHint=false and the tool name indicates a real change. This is a material contradiction, and the description adds no other behavioral context such as side effects, reversibility, or required permissions.

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 short sentence with no filler, so it is concise. However, that conciseness comes at the cost of under-specification, and the sentence does not front-load the key facts an agent needs.

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 three-parameter mutation tool with no output schema and no parameter descriptions, the definition is substantially incomplete. It does not explain what visibility change is being previewed, what the resource types are, or whether any real state is modified.

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%, and the description does not mention resourceId, resourceType, or visibility at all. The schema has enums for visibility and resourceType, but the description provides no added meaning or usage guidance for these required parameters.

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 says 'Preview publishing or unpublishing a resource,' which is specific in verb and resource but inconsistent with the tool name and title ('Change resource visibility'). It does not mention visibility values or resource types and gives no sibling differentiation, so an agent could easily confuse it with a dry-run preview rather than a visibility mutation.

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 guidance on when to use this tool versus alternatives such as resource_share_grant, resource_delete, map_publish, or project_set_layer_visibility. The only context is the ambiguous word 'Preview,' which does not clarify when this operation should be selected.

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 description says "Preview moving ... to trash," which implies a non-mutating dry run, while annotations declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false. The agent cannot tell whether calling this trashes the resource or merely reports what would happen, or whether a follow-up confirm_action is required. This is a direct conflict with the structured safety metadata.

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 with no filler. It is efficient, though the brevity is partly under-specification rather than disciplined economy.

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 destructive operation with no output schema and zero parameter documentation, the description supplies almost nothing: no confirmation flow, no restorability (resource_restore exists as a sibling), no permissions, no effect on children or shares. An agent would be guessing at the consequences of a destructive 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 carries the burden for both parameters. It does implicitly enumerate the four resourceType values, which adds some value over the enum, but says nothing about resourceId (validity, not-found behavior, cross-type scope) or what resourceType governs beyond the type list. Not enough to compensate for the coverage gap.

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 names a verb ("preview moving ... to trash") and enumerates the four affected resource types (source, collection, map, project), matching the resourceType enum. But it conflicts with the tool name (resource_delete) and title ("Move a resource to trash") about whether the call actually mutates anything, so an agent cannot be confident what the tool does. It also doesn't distinguish itself from resource_restore or confirm_action.

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 statement of when to call this versus alternatives. The sibling list contains confirm_action, cancel_action, and resource_restore, which strongly suggest a preview-then-confirm workflow, but the description never mentions that flow or any prerequisites. Usage must be inferred entirely 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 this as a non-read-only, non-destructive, idempotent, closed-world mutation, so the safety profile is provided externally. The description adds useful context by specifying that restoration is from trash and that only eligible resources qualify, but it does not explain what 'eligible' means, what permissions are required, or what happens on conflict. With annotations carrying the behavioral burden, this is adequate but not rich.

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 efficient sentence with no filler, and the key scoping constraint ('from trash') is front-loaded before the enumerated resource types.

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 mutation tool with no output schema and 0% parameter description coverage, the description is too thin. It omits eligibility rules, permission requirements, conflict behavior, and any indication of what is returned, leaving significant gaps for an agent to invoke the tool correctly beyond the basic annotations.

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 lists the resource types in prose ('dataset, collection, map, or project'), which loosely maps to the resourceType enum, but it does not name parameters or explain the UUID format or required pairing. It adds some meaning for resourceType but leaves resourceId entirely undocumented beyond its schema format.

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 action ('Restore') and resource scope ('dataset, collection, map, or project'), and adds the important qualifier 'from trash.' It clearly distinguishes the tool from siblings like resource_delete or resource_view, though it does not explicitly name 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?

The phrase 'from trash' gives a minimal contextual cue about when the tool applies, but there is no explicit guidance on prerequisites, eligibility criteria, or when to use this versus alternatives such as resource_view or search. An agent must infer all usage conditions.

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 declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false, so safety is largely covered. The word 'Preview' adds real information about a staged/dry-run semantic, but the description never says whether a pending action is created, what must be done to commit it, or what permissions are required.

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 ten-word sentence with no filler, so it is structurally tight. But its brevity comes at the cost of under-specification, and the few words it does spend describe target types the schema doesn't support.

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 4-required-parameter mutating tool with no output schema and zero schema coverage, the description omits the resource identity, role semantics, expiration, and the preview/confirm lifecycle. Almost everything an agent needs to call it correctly 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?

Schema description coverage is 0% for 5 parameters, so the description must compensate — and it does not. It never mentions resourceType, resourceId, role, or expiresAt, and its mention of 'organization' and 'public share' targets actively misleads, since only ACCOUNT/handle and TEAM/teamId are accepted.

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 verb+resource ('granting ... access') is identifiable, but the 'Preview' qualifier conflicts with the name and title ('Grant resource access'), leaving it unclear whether this applies or merely stages a grant. It also names target kinds ('organization', 'public share') that aren't in the schema's ACCOUNT/TEAM enum, so the stated scope doesn't match the tool's actual inputs.

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 guidance on when to use this versus the sibling resource_share_revoke, nor any mention of the likely confirm_action / cancel_action follow-up implied by 'Preview'. An agent must infer the whole workflow from the 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?

Annotations declare destructiveHint=true and readOnlyHint=false, yet the description says "Preview", creating unresolved tension about whether anything is actually mutated, whether the operation is reversible, or whether a separate confirm step is required. With annotations covering the safety flags, the description should have explained the preview/confirm mechanics rather than leaving them to inference.

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 short sentence with the key concept front-loaded and no filler. It is appropriately sized for what it says, though the size comes at the cost of substance rather than being a model of efficiency.

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 destructive-flagged mutation with no output schema and no parameter documentation, the description omits nearly everything an agent needs: what a preview returns, whether the revoke takes effect immediately, and what must follow. The gaps are too large for the operation's risk level.

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% for the single parameter, and the description never mentions shareId or where the agent obtains it. Only the UUID format in the schema gives any hint, so the description fails to compensate for the coverage gap.

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 names a verb-plus-resource ("revoking an existing share") and adds a qualifier ("Preview"), so the agent knows it concerns share revocation. However, "preview" is ambiguous: it is unclear whether the share is actually revoked or a dry-run result is returned. It also does not clearly separate this from related siblings such as resource_delete or the cancel_action/confirm_action pair.

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 statement of when to use this versus resource_change_visibility, resource_delete, or resource_share_grant, and no mention of prerequisites or the follow-up confirmation step that the sibling names (cancel_action/confirm_action) imply. The agent must infer the workflow entirely.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is fully covered. The description adds two useful pieces beyond that: the resource must be 'accessible' (a permission gate) and the result is rendered for visual inspection rather than returned as raw data. It still says nothing about what happens when the identifier is unknown or the resource is inaccessible.

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 with no filler; the verb and resource scope come first. Nothing is wasted, though it is arguably too terse for a two-parameter tool with an undescribed identifier.

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 should clarify what 'render' produces — a visual payload, a URL, an image reference, or a structured view object. That is the main missing piece; otherwise the read-only safety profile and closed-world scope are adequately covered by annotations.

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 0%, so the description must carry the load. It enumerates the four accepted kinds, matching the enum, but the required 'identifier' parameter is never explained — no hint whether it is a slug, numeric ID, or name, nor any format or lookup behavior.

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 pair ('fetch and render') and enumerates the resource kinds it handles (collection, project, map, source), so an agent knows exactly what it does. It does not differentiate itself from the close sibling map_view, which likely overlaps on the 'map' case, leaving some ambiguity about which to pick.

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?

'for visual inspection' implies this is a read/display path rather than a data-fetch path, and 'accessible' hints at a permission prerequisite. However, no explicit when-to-use, when-not-to-use, or named alternative (e.g. map_view) is given, so the agent must infer routing.

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, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds real value in "accessible" (results are access-scoped to the caller) and "one ordered result set" (cross-kind merged ordering). It says nothing about paging behavior despite offset/limit existing, or about how matching works when query is omitted.

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 sentences, zero filler, with the resource scope front-loaded and the workflow hint trailing. Every clause 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?

Four undocumented parameters, no output schema, and no description of result shape or pagination mean the definition is only just sufficient for a federated search tool. It does not explain default ordering, what a result entry contains, or how to page through more than `limit` matches.

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 0% and none of the four parameters are documented in the schema, so the description carries the burden. It partially covers `kinds` by naming the kind categories, but the vocabulary diverges from the enum ("datasets" vs `source`, "published maps" vs `map`), and `limit`, `offset`, and `query` are never mentioned at all — leaving pagination semantics entirely implicit.

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 concrete verb (search) plus the resource set and enumerates the four kinds returned (datasets, projects, published maps, collections) as one ordered result set. That is specific enough to distinguish it from single-resource getters, but it never names the obvious sibling `search_view`, so an agent must infer whether this federated search supersedes it.

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?

"Use it to find GIS data or a map before calling the get tools" gives a clear entry-point role in the workflow and implies the ordering search → get. It stops short of exclusions or named alternatives (e.g. `search_view`, `project_configure_search`, `project_resolve_places`), so it is clear context without routing 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new context that this call has a UI side effect (renders an interactive grid), which annotations do not convey. It says nothing about pagination, result caps, or how the grid state interacts with later calls.

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 with no filler, and the core action is front-loaded before the usage hint. It is efficient, though the brevity comes at the cost of the missing parameter and sibling guidance noted elsewhere.

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 4 undocumented parameters, no output schema, and a sibling 'search' that overlaps in purpose, the description should do much more. An agent knows roughly what the tool does but not how to scope kinds, paginate results, or choose it over the plain 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 description coverage is 0% across 4 parameters, so the description carries the full burden and fails: 'kinds', 'limit', 'offset', and the query string are never mentioned. The word 'Search' weakly implies a query parameter, but filtering, pagination, and the default limit of 12 are completely undocumented.

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 accessible Geobble resources') plus a distinctive behavioral outcome ('render an interactive result grid'). However, it never distinguishes itself from the sibling 'search' tool, so an agent cannot tell from the description alone which search entry point to pick.

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?

'Use when visual selection would help the user' gives a contextual hint, but it is vague and leaves the key comparison implicit. The obvious alternative, the sibling 'search' tool, is never named, and there are no when-not conditions or 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 readOnly/idempotent/non-destructive, so the description's added value is the polling contract: each call re-issues a fresh capability rather than returning a cached one. It does not say what a poll returns when conversion is still running (error vs. pending status), which is the single most important behavior for a polling 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?

Two sentences, no filler, and the polling purpose and the filter constraint are both front-loaded. Nothing could be cut without losing information.

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