Geobble

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 structurally. The description adds useful context that the returned accounts are the ownership targets and carry the handle create tools need, but nothing beyond that (e.g. scope of 'available', auth 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?

A single front-loaded sentence stating verb, resource, scope, and the downstream use of the returned handle. No filler or redundancy.

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

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

With an output schema present, return-value shape need not be described, and the description supplies the key context an agent needs: what accounts are returned and the handle the create tools consume. Slightly thin on how results are scoped/ordered, but adequate.

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; the 4 baseline applies. The schema is empty and 100% covered, so no compensation is required.

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 (List) and resource (personal and organization accounts), and narrows scope to accounts that can own new geospatial work. It does not explicitly contrast with nearby siblings like geobble_profile or geobble_capabilities, so it is clear but not fully differentiated.

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

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

The clause 'including the handle the create tools require' implies this should be called before the create/owning tools, but it never states that as an explicit when-to-use rule and names no alternative tool. Usage is inferable 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 destructiveHint=false and idempotentHint=true, so the agent knows this is a safe, repeatable mutation. The description adds one genuinely useful piece of context beyond that: the underlying action is not executed. It stops short of covering auth requirements, error behavior for unknown/expired confirmation IDs, or the effect on the pending state.

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 filler; the scope-limiting clause ('without executing the underlying action') is placed where it matters most.

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 cancellation tool whose annotations already carry the safety profile, the description is minimally adequate. The gaps are the parameter's origin/meaning and the failure/edge-case behavior, neither of which exists in an output schema or in the schema itself.

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 never mentions confirmationId at all, so nothing clarifies where the ID comes from or its expected format beyond the type and length bounds in the schema. For a required, 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 a precise resource (a pending Geobble confirmation), plus the key scoping fact that it does not execute the underlying action. This implicitly distinguishes it from the sibling geobble_confirm_action, though it never names that alternative directly.

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 'pending' implies a precondition, but there is no explicit when-to-use guidance, no statement of what happens if the confirmation is already executed or expired, and no routing to geobble_confirm_action as the opposite choice. Usage must be inferred.

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. The description adds no further behavioral context (no mention of what it returns or how results should be used), only capability domains, which is content rather than 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 enumerating the four capability domains with zero filler. 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?

An output schema exists, so return values need no explanation, and the annotations carry the behavioral profile. For a no-parameter discovery tool the description is essentially complete, though a hint about when in a workflow to call it would make it fully self-sufficient.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter information is needed or missing.

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 enumerates the four capability domains, which is clear enough to distinguish it from the operational siblings. It does not explicitly position itself against its siblings, but the meta/discovery role is evident.

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/introspection call to make before invoking specific project, map, or source tools. There is no explicit when-to-use, when-not-to-use, or named alternative among the many siblings.

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-destructive, non-open-world write, so the safety profile is covered. The description adds only the soft constraint of creating 'under an accessible account' — no idempotency behavior, slug-uniqueness failure mode, or persistence consequences are disclosed.

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

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

A single well-formed sentence with the action front-loaded and no filler. It is efficient, though the clause between the dashes is the only reason it is not maximally tight.

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 whose payload is a deep nested object with zero schema documentation and no output schema, one sentence is far too thin. Required fields, slug format constraints, and the meaning of the owner handle are all left to the schema alone, which documents nothing.

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 two parameters, one of which is a nested object with ~17 fields (slug pattern, enums, dates, tags) that the description never mentions. The phrase about a 'curated group of geospatial datasets' only loosely gestures at the collection payload and leaves ownerHandle 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?

Specific verb (create) plus resource (collection) and a gloss of what a collection is (a curated group of geospatial datasets), which disambiguates it from generic create tools. It does not distinguish itself from the nearby collection_update_metadata sibling, so it stops 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?

No when-to-use guidance, no prerequisites, no mention of alternatives. 'Under an accessible account' hints at an ownership requirement but never states what makes an account accessible or what to do if it is not.

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=true, so the safety profile is covered. The description adds nothing beyond that — it does not say whether 'patch' is a partial merge (fields omitted are left untouched) or a full replacement, nor how conflicting concurrent edits behave.

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 focused sentence with no filler, and the core action is front-loaded. It is arguably too terse for a nested-15-field mutation, but there is no wasted text.

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

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

For a complex mutating tool with a nested patch object, no output schema, and 0% schema description coverage, a one-line description is insufficient. It fails to explain partial-update semantics, null-clearing behavior (several fields are nullable), or permission requirements.

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

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

Schema description coverage is 0%, so the description carries the burden for the nested 'patch' object, yet it names only title and description (two of ~15 fields) and references a nonexistent 'visibility' field. It omits licences, tags, country codes, review status/dates, and other patchable metadata, leaving the agent to reverse-engineer semantics from raw 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 (Update) and resource (collection metadata of a geospatial collection), which cleanly distinguishes it from siblings like geobble_source_update_metadata. However, it claims to update only 'title, description, and visibility,' while the patch schema exposes ~15 fields and contains no 'visibility' property at all, so the stated scope is both under- and mis-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?

The description gives no when-to-use guidance, no prerequisites (e.g., ownership/permission to edit a collection), and does not name alternatives such as geobble_resource_change_visibility for visibility changes or geobble_collection_create. The agent must infer usage 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds that the action is 'exact server-stored' (cannot be altered) and provides examples, which is useful context, but it does not disclose permissions, failure modes, or specific consequences beyond what the annotations provide.

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 that states the verb and the key precondition without any filler. Every word 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?

The description covers the core purpose and trigger, and no output schema exists to require return-value explanation. However, it lacks direct parameter semantics (origin, format, constraints) and operational caveats such as token expiry or permission requirements, which limits completeness for a destructive mutation 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%, so the description must compensate for the single undocumented parameter. It implies where the ID originates ('from a confirmation_required response') but never names or explains the confirmationId parameter, its format, or its constraints, leaving a significant 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 ('Execute') and resource ('the exact server-stored action from a confirmation_required response'), making the tool's role clear. However, it does not explicitly distinguish itself from the sibling cancel_action or name an alternative, so it falls short of the sibling-differentiation bar for 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 phrase 'from a confirmation_required response' establishes a clear trigger condition for when to use it, which is more than implied usage. It does not, however, cover when not to use it or mention the cancel_action alternative, so it misses the exclusion requirement for a 5.

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 scope, so the safety profile is covered. The description contributes one extra behavioral fact, that only *accessible* resources can be fetched, implying permission-gated failures, but says nothing about error behavior or what a returned resource 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 front-loaded sentence with the verb, scope and enumerated kinds in the first clause. No filler, though the parenthetical '(source)' is slightly awkward phrasing rather than an addition of real 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?

For a two-parameter federated getter with no output schema, the description covers what kinds exist but omits what is actually returned (full resource vs summary), identifier format, and how inaccessible/invalid identifiers are reported. Adequate but with clear gaps for an agent deciding between this and the kind-specific getters.

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 for two undocumented parameters. It does usefully clarify that 'source' means a dataset, which is the least self-evident enum label, but it says nothing about the identifier's format (ID vs slug vs URL) despite the 1-256 char constraint.

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 (Get) and resource (accessible geospatial resource) and enumerates the four supported kinds, which map exactly to the schema enum. It stops short of differentiating itself from close siblings such as geobble_resource_view, geobble_map_get, and geobble_resource_access_get, so an agent cannot fully disambiguate on the description alone.

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 geobble_search (to find an identifier) or the more specific geobble_map_get / geobble_resource_view siblings. The word 'accessible' hints that visibility matters, but no prerequisite or exclusion is 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context the annotations lack: the iframe embed markup is returned only 'when public embedding is enabled', a conditional the agent must know about.

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 that names the resource first and then the return contents. No filler, no redundancy.

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

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

With no output schema, the description correctly carries the burden of describing returns (publication, URL, embed), and annotations cover safety. It omits any error/not-found or non-published-map behavior, but is otherwise sufficient for a one-parameter 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?

A single mapId parameter with 0% schema description coverage. The description says nothing about it, but the parameter name is self-evident and the schema supplies format (uuid) and pattern. Baseline 3 for a lone, clearly-named identifier the description does not enrich.

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 (Get) and a precisely scoped resource (a published interactive map), plus enumerates the payload: active publication, canonical URL, and iframe embed markup. This distinguishes it from the raw geobble_get and geobble_map_view siblings, 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 implied by the scoping word 'published' and the delivery-link framing (URL/embed), which signals this is for consumers needing a shareable/embeddable map. However, there is no explicit when-to-use vs geobble_map_view, geobble_map_publication_list, or geobble_map_publication_activate, leaving the agent to 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 idempotentHint=true and destructiveHint=false, so 'create or reuse' usefully explains what idempotency means here (an existing export may be returned instead of a new one). It also discloses the async nature, which the annotations do not. It says nothing about permissions, quota/rate limits, or what happens if the export is already 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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though it is arguably under-sized for a tool with this much configuration surface, which is captured in contextual completeness rather than verbosity.

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 whose inputs are largely a deep nested options tree, with no output schema and no annotations describing the workflow, one sentence is far too thin. The agent is not told how to express view/bbox, that hiddenLayerIds and theme exist, or that it must poll geobble_map_image_export_status to obtain the finished PNG.

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 parameters carry real weight: resourceType/resourceId determine the target, and the nested options object controls view (static center/zoom vs bbox bounds), theme, dimensions, layers and overlays. The description names none of these, so it adds no meaning over the raw schema and leaves the agent to parse a large nested object unaided.

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+resource pair ('Create or reuse ... PNG image export') and scopes it to both project and published maps. It implicitly separates itself from the sibling status tool by saying 'prepare', but never names geobble_map_image_export_status, so an agent must infer the pairing.

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 'asynchronous' implies this is a job-start call that must be followed by a status check, and 'reuse' implies it is safe to call repeatedly. However, it never states when to prefer this over alternatives or that the status tool is the required follow-up, leaving the workflow to inference.

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 covered. The description adds that it blocks/delays until 'the PNG is rendered' and yields a 'download capability', which is useful behavioral context, but it omits pending/failed states and whether the returned download link expires.

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 the polling action and the success condition front-loaded; nothing is wasted. It is arguably too terse for the state machine it implies, but structurally it is clean.

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 the response, and it only gestures at it ('a download capability'). The intermediate not-yet-ready and failure outcomes an agent will actually encounter while polling are left undocumented.

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

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

Schema description coverage is 0% and the single required parameter (exportId) is never explained in the description. The schema only gives format/pattern, not provenance or meaning, so the description fails to add the missing semantics (e.g., 'the UUID returned by geobble_map_image_export_prepare').

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 pairs a specific verb ('Poll') with a specific resource ('map image export') and states the outcome ('return a download capability once the PNG is rendered'). It is clearly distinguishable from geobble_map_image_export_prepare, though it never names that sibling as its predecessor.

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 'Poll' implies repeated invocation until the image is ready, but there is no explicit guidance on when to call it, how often to poll, what to do while not ready, or that the exportId must come from geobble_map_image_export_prepare. 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?

Annotations declare readOnlyHint=false, i.e. this is a mutating operation, yet the description's verb is 'Preview', which implies a read-only dry run. This directly contradicts the annotation, and the description says nothing about permissions, reversibility, or the effect of activation.

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, so it is structurally clean. However, it is under-specified rather than concise for an operation that requires four coordinated parameters.

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?

A mutating tool with four required parameters, no output schema, and no parameter descriptions needs the description to carry concurrency, idempotency, and safety context. The one sentence supplies none of it and additionally mislabels the operation.

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 never mentions them. In particular, expectedCurrentPublicationId is clearly an optimistic-concurrency guard and idempotencyKey an operation-dedupe token, but neither concept is explained anywhere, leaving the agent to guess at invocation semantics.

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 ('rolling a map forward or back to an immutable publication revision'), which is more than a tautology, but it labels the operation 'Preview' while the tool name and title say 'Activate'. An agent cannot reconcile whether this commits a change or merely shows one, so the purpose is misleading rather than clear.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as map_publish or geobble_map_publication_list. The agent must infer the trigger condition 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful domain context (revisions are immutable, one revision is live), but says nothing about ordering, pagination, or what fields each revision carries.

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 tightly-written sentence with the resource front-loaded and the live-revision detail appended. No filler, no redundancy 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?

For a one-parameter read-only tool there is no output schema, and the description partially compensates by naming the two things the response contains: the revision list and which one is live. Ordering, pagination and per-revision fields remain unstated.

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 would ideally clarify mapId, and it does not mention the parameter at all. Mitigating this, there is only one parameter, its name is self-evident, and the schema supplies type, uuid format and pattern.

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 a specific resource (immutable publication revisions of a map), plus a second capability: identifying which revision is live. It is clearly separable from geobble_map_publication_activate by verb, though no sibling is named 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?

There is no when-to-use guidance, no prerequisite, and no mention of the alternative geobble_map_publication_activate or map_publish. The agent must infer that this is the discovery step before activation.

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 by structured data. The description contributes the content of the render (preview, delivery state, canonical link), which is useful, but omits whether the map must already be activated via geobble_map_publication_activate or what happens for an unpublished mapId.

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 the returned artifacts appear immediately. It is efficient, though arguably too terse to carry the missing usage and parameter context.

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 right thing by naming what the render returns (preview, delivery state, canonical link) and annotations cover safety. However, the required mapId is undocumented and there is no guidance on the publication precondition, leaving gaps for an agent acting among many map_* and publication_* siblings.

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 the single required parameter mapId has no description in either the schema or the description text. The phrase 'published map' hints that mapId refers to a published map, but the format constraint (UUID), whether it is a project/map/publication identifier, and what happens with an invalid or unpublished ID are all left unstated.

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 is surfaced: preview, delivery state, and canonical link. It is clear on its own, but it never distinguishes itself from the very similar sibling geobble_map_get, so an agent cannot tell the two apart from the text alone.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative. The agent must infer from the name that this is the tool for displaying an already-published map rather than fetching raw map data via geobble_map_get.

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's help. The description adds the notion of a "connected" account (implying session state), but nothing about auth failure modes or what happens when no account is connected.

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 return content and followed by the use case. No filler, though the second sentence is arguably optional given the trivial nature of the 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?

With an output schema present, the description needn't describe return values, and it correctly stays short. Complete for a no-arg read tool; only the lack of sibling differentiation leaves a small gap.

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. No parameter context is needed or missing.

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 (return) and resource (connected Geobble account), plus an enumeration of the fields returned (identity, display name, email, handle). It is clear on its own but never distinguishes itself from the sibling geobble_account_list, which an agent could easily 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?

"Use it to confirm which geospatial workspace is connected" gives a usable context, but there is no when-not guidance and no mention of the near-identical sibling geobble_account_list that would be the natural alternative for account data.

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

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

Annotations only declare readOnly=false, destructive=false and non-idempotent. The description adds two pieces of context the annotations do not carry: the optimistic-concurrency contract (expectedSpecVersion is required to prevent stale writes) and the source-constraint that the referenced dataset/collection/map must already be in context. It still omits what happens on version mismatch or that repeated calls create duplicate layers.

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 main action stated first and the hard prerequisite immediately after. Nothing restates the tool name or 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 non-idempotent write with no output schema and 0% top-level parameter coverage, the description is thin. It never says what the call returns, nor the critical follow-on fact that adding a layer changes the spec version agents must pass on their next write, which is the natural consequence of the concurrency contract it introduces.

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 projectId and position are explained nowhere. The description partially compensates by explaining the semantics of expectedSpecVersion and the origin of the layer payload, and the nested layer schema is itself heavily documented. Position, the insert index, is left entirely unexplained by both description and 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 ("Add a map layer to a project") plus the accepted source kinds (dataset, collection, or map in context). It is clearly distinguishable from the many geobble_project_configure_* and geobble_project_remove_layers siblings, though it never names the closest alternative (geobble_studio_add_layer) to sharpen the boundary.

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 a dataset, collection, or map already present in its context" implies the precondition that the source must already exist in the project's context, and the expectedSpecVersion note implies a read-then-write flow. However, it never states when to prefer this over geobble_studio_add_layer or geobble_project_duplicate_layer, and no explicit 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?

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false, so the mutation/open-world safety profile is already covered. The description adds the genuinely useful behavioral fact that the operation is asynchronous ('Queue') and provider-backed, but says nothing about cost, latency, what gets created, or how to retrieve results.

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 first and the capability list following. Zero filler and no repetition of the name or 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 tool with a deeply nested multi-branch schema, no output schema, and no param descriptions, the description is too thin: it omits the async submit-then-poll workflow, the preview vs materialize choice, and how results attach to the project. An agent could pick the right operation family but would not know the surrounding workflow.

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% over a very large nested schema with oneOf branches, enums (mode, profile, output, detail), and defaults. The description's operation-family list loosely maps to operation.type values, which has some value, but it never mentions mode, profile, attachToProject, title, or the preview/materialize distinction, so it leaves most of the parameter surface undocumented in both the schema and 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?

The description gives a specific verb ('Queue ... mobility analysis') and resource, and enumerates the five operation families (routing, reachability/isochrones, nearest, travel-time metrics, map-matching) that map onto the schema's operation.type discriminators. It does not explicitly distinguish itself from the sibling geobble_project_mobility_analysis_status, though 'Queue' implies the submission half of an async 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 explicit when-to-use or when-not-to-use guidance. The description never tells the agent that this only queues a job and that results must be fetched via geobble_project_mobility_analysis_status, nor does it explain when to prefer preview vs materialize mode. The word 'Queue' is the only hint about the workflow.

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 the safety profile (readOnly=false, destructive=false, idempotent=false), so the agent already knows this is a non-destructive write. The description adds genuinely useful context beyond that: expectedSpecVersion exists as optimistic-concurrency protection against stale writes. However it omits that passing bubble=null wipes all bubbles and whether the call replaces or merges the layer's bubble config.

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, front-loaded with purpose then the key constraint. No filler, nothing 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?

For a nested-object mutation tool with no output schema, the description is thin: it never states that bubble=null removes all bubbles or whether the update is a full replace of the layer's bubble config. The concurrency note is the one piece of context it contributes; the rest relies on 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?

Top-level schema coverage is 0% (projectId and input have no descriptions), so the description must compensate — and it does explain the purpose of expectedSpecVersion. It adds nothing for projectId, and the nested schema's own descriptions (linkFilter, targetSource, artifactsLayer, null-to-remove) carry the rest of the weight.

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+resource: "Configure bubble interactions for a project map." This is clear enough to separate it from sibling configurators like configure_popup and configure_legend, but it never names a sibling or clarifies what 'bubble interactions' means relative to 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 gives no when-to-use guidance, no preconditions beyond a required param, and no routing to alternatives among the many configure_* siblings. The only guidance is that expectedSpecVersion is required, which is a schema constraint restated rather than usage context.

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 mutation profile is covered structurally. The description adds genuinely new behavioral context the annotations lack: the optimistic-concurrency contract ('expectedSpecVersion is required to prevent stale writes'), i.e. that a stale version will be rejected. It still omits what happens to any pre-existing camera config and whether the change can be undone.

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 purpose statement is front-loaded ahead of the versioning constraint. 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 nested mutation tool with no output schema and 0% schema description coverage, the description is too thin: it neither explains the input payload (camera trigger/delay/center semantics beyond the schema's brief inline notes) nor what the call returns or how a rejected stale version surfaces.

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 there are three required params (projectId, expectedSpecVersion, input with nested layerId/camera). The description explains the purpose of only expectedSpecVersion; projectId, input, layerId and the camera object semantics are left entirely to the raw schema, so it does not 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?

States a specific verb+resource: 'Configure camera interaction behaviour for a project map.' An agent can distinguish this from sibling configurators like geobble_project_configure_popup or configure_legend on the strength of 'camera interaction behaviour' alone, though it never names 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?

No when-to-use guidance, no prerequisites, and no routing to or away from the many sibling configure_* tools. The only usage-adjacent note is that expectedSpecVersion is mandatory to avoid stale writes, which is a constraint rather than situational 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 as a non-read-only, non-destructive, non-idempotent write, so the bar is lower. The description goes beyond them by disclosing the optimistic-concurrency contract - expectedSpecVersion exists to prevent stale writes - which an agent could not infer from the annotations or schema. It omits what happens on a version mismatch, so it is not a full 5.

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

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

Two short sentences, no filler. The purpose is front-loaded and the concurrency constraint follows immediately; 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?

A mutation tool with a nested input object, 3 required parameters, and no output schema. Purpose and the concurrency contract are covered, but permission/authorization requirements, failure behavior on version mismatch, and the meaning of projectId are absent.

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%, but the description compensates for expectedSpecVersion by explaining its purpose. projectId is left entirely unexplained in both description and schema, and the expression DSL shape is conveyed only structurally by the anyOf. Baseline 3 is appropriate given the description covers one of the three top-level 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?

States a specific verb+resource: configuring computed feature fields and expressions on a project map. The domain is narrow enough to be told apart from the configure_legend / configure_popup / configure_bubbles siblings. It does not explicitly name or contrast with any alternative tool, so it stops 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?

Usage is only implied by the phrase 'for a project map'; there is no explicit when-to-use, when-not-to-use, or routing to a sibling (e.g. update_layer_style for appearance). The one operational precondition given (expectedSpecVersion required) is useful but is a requirement, not 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 already declare this is a non-readonly, non-idempotent, non-destructive write. The description adds real value beyond them by explaining why expectedSpecVersion exists (preventing stale writes), but it omits the fact that a configure call replaces the existing legend and that passing null disables it — both relevant to a mutation.

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 key constraint; nothing is wasted. It is close to minimal, erring on the terse side rather than padded.

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

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

For a tool with a deep nested legend schema and no output schema, the description is thin: it omits the replace-vs-merge semantics, the null-to-disable behavior, and any note on what is returned. Adequate to identify the action, but not complete for confident 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?

Top-level schema description coverage is 0% (projectId, expectedSpecVersion and input carry no descriptions), so the description must compensate. It clarifies expectedSpecVersion's purpose but says nothing about projectId or the shape of input, leaving two of three required parameters dependent on the JSON schema alone.

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 the legend of a project map plus its entries. Among siblings like configure_bubbles, configure_camera, configure_popup and configure_search the resource word "legend" makes it easy to tell apart, though the description never names a sibling or scope boundary 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?

There is no when-to-use guidance, no preconditions (e.g. layer must already exist), and no routing against alternatives such as update_layer_style, which could plausibly be confused with legend styling. The second sentence is a concurrency constraint, not 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 already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the mutation and non-idempotency profile is covered. The description adds genuine value with the optimistic-concurrency note that expectedSpecVersion prevents stale writes, but it never says what happens on a version mismatch or what the tool does to existing popup config.

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, front-loaded with the operation and followed immediately by the one behavioral constraint that matters. Nothing is wasted or redundant.

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

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

For a deeply nested mutation with no output schema and 0% top-level schema coverage, the description is thin: it omits how input.title is used, that a null popup disables popups, and any error/response behavior. Nested field descriptions in the schema fill some gaps, keeping this at a minimum-viable level rather than inadequate.

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?

Measured top-level schema description coverage is 0%, so the description carries the burden. It explains expectedSpecVersion's purpose (stale-write protection) and indirectly maps to input.popup.properties, but projectId and the input wrapper (layerId, title) go unexplained. Partial compensation, not full.

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+resource: configuring popup presentation and the feature attributes shown in project map popups. It does not, however, distinguish itself from the obvious siblings geobble_studio_set_basic_popup and geobble_project_configure_bubbles, so an agent must guess which popup tool applies.

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 alternatives are named despite multiple overlapping popup/bubble tools in the sibling list. The only prerequisite hint is that expectedSpecVersion is required, which is stated as a rule rather than as a selection condition.

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 mutating, non-idempotent, non-destructive operation, so the safety profile is covered. The description adds the useful behavioral detail that expectedSpecVersion guards against stale writes, but says nothing about what happens on a version mismatch, required permissions, or what state is changed.

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 purpose is front-loaded ahead of the concurrency caveat. Efficient, though the second sentence could be phrased more fully.

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 tool with a nested config object and no output schema, the description covers the essentials of what it does and the optimistic-concurrency requirement. It omits what the search config comprises (nested schema does cover this) and the failure behavior on a stale version, leaving a real gap.

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, expectedSpecVersion, and the input object have no schema descriptions. The description compensates for expectedSpecVersion only, leaving projectId and input unexplained at the top level.

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 ('Configure how search behaves in a project map'), which is enough to distinguish it from sibling config tools like configure_popup and configure_legend. It does not explicitly name those siblings, but the search-specific scope is clear.

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 alternatives are named. The only contextual hint is that expectedSpecVersion prevents stale writes, which is a concurrency note rather than usage guidance for choosing this tool over siblings.

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?

Adds real context beyond the annotations: the project is created 'empty' and 'private', and creation is gated on caller permissions. Annotations already cover the write/safety profile (readOnlyHint=false, destructiveHint=false), so the description earns credit for the privacy and authorization disclosures.

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 resource first, then a clarifying clause and the permission caveat. Efficient, though the stacked em-dash clause makes it slightly dense.

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 create tool with no output schema and annotations that already cover safety, the description is adequate: it says what is created, its privacy, and the permission requirement. It falls short only on parameter guidance (basemap IDs and owner handle are entirely unexplained).

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, and the description compensates for none of them — no mention of ownerHandle, title, or the light/dark basemap UUIDs. Only a faint hint that the project starts empty, which is not a parameter 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?

States a specific verb+resource ('Create an empty private project') and clarifies the resource's role (geospatial workspace holding layers, datasets, styles, analysis results). This cleanly separates it from siblings like geobble_project_create_theme or geobble_collection_create.

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 a precondition — the caller must be able to create under the target account — which is useful routing context. But it never says when to prefer this over alternatives (e.g., duplicating an existing project) or what happens if the account lacks create rights.

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 (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false). The description adds genuinely useful context that isn't in the annotations: the theme is reusable, owned by the project account, and creation also attaches it to the project. It omits authorization requirements, duplicate/name-collision behavior, and what is returned.

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

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

One sentence, front-loaded with the action and the resource, with the ownership/attachment scope following immediately. 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 nested-input mutation with no output schema, a 2-param surface is small, but the description says nothing about what the caller receives back (e.g., a theme id), how conflicts with existing themes are handled, or required account permissions. Adequate but with clear gaps for a write 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?

Top-level schema description coverage is reported as 0%: neither projectId nor the input wrapper is described anywhere in the schema. The description adds nothing about parameters, arguments, or the shape of the nested input, so it fails to compensate for the stated coverage gap. The nested object's own field descriptions do much of the work, keeping this from a 1.

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 ('reusable cartographic colour theme'), plus the scope ('owned by the project account', 'attach it to the project'). This is clearly distinguishable from siblings like collection_create or project_update_settings, though it never names an alternative 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 says what happens but never when to use this tool versus alternatives, nor any preconditions (existing project, permissions, whether duplicate titles are allowed). The agent must infer usage entirely from the tool name.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description usefully adds that expectedSpecVersion exists to prevent stale writes, implying optimistic-concurrency semantics, but says nothing about permissions, what the duplication copies (styles, filters) or reversibility of a non-idempotent mutation.

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 purpose front-loaded and the parameter caveat second; nothing is padded. 'Preserving canonical GMS validity' is domain jargon that may not translate for an unfamiliar agent, which keeps it just short of ideal.

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 no output schema, the description never indicates what comes back (e.g., the new layer's identifier) or what scope of configuration is duplicated, which is exactly the information a caller cannot get from structured fields. The concurrency note is a genuine addition but the definition remains 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?

Top-level schema description coverage is 0%, and the description only compensates for expectedSpecVersion, explaining its stale-write-prevention role rather than restating its minimum/maximum. projectId and the nested input object carry UUID constraints and field descriptions but no explanation of why the layerId/title pair is needed, leaving the burden only partly met.

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 ('Duplicate a map layer') that maps cleanly onto the tool name, so the core action is unambiguous. It does not, however, distinguish itself from adjacent creation tools like geobble_project_add_layer or geobble_studio_add_layer, which an agent could plausibly confuse when a new layer is the goal.

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 / when-not-to-use guidance and no naming of alternatives among the many layer-mutating siblings. The only conditional statement ('expectedSpecVersion is required') describes a parameter obligation, not a usage scenario.

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 state readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is fully covered by structured data. The description adds only the scoping fact that the datasets live in a collection attached to the project; it says nothing about result size, pagination or truncation behavior that the limit parameter implies.

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 words, stating the action and the resource scope immediately. It is efficient, though arguably under-specified rather than truly concise.

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

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

With no output schema, a nested input object, and low schema description coverage, the description should have said what an exploration returns (dataset names, ids, metadata) and how limit affects it. It gives an agent no basis to distinguish this from inspect_source or to predict the response shape.

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 mentions no parameters at all, and the reported schema description coverage is 0% with projectId carrying no description in the schema. The nested collectionId format and the limit semantics are left entirely to the schema, and even the schema is thin on projectId, so 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?

The description names a specific verb pair (list and inspect) and a specific resource (geospatial datasets in a project collection), so an agent knows what it returns. It stops short of differentiating itself from adjacent readers such as geobble_project_inspect_source or geobble_search, leaving the agent to infer the boundary.

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 or when-not-to-use guidance, no prerequisites (e.g. that a collection must already be attached), and no named alternative despite many overlapping read tools in the sibling list. Usage is only implied by the phrase 'attached to the project'.

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, so the safety profile is covered. The description adds useful content about the return payload (schema, provenance, freshness, sample rows), which goes beyond annotations, but says nothing about failure modes, permissions, or cost.

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 enumerating the four inspection aspects with no filler. Efficient, though the extreme brevity leaves no room for usage or behavioral framing.

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 read-only inspection tool with annotations covering safety and no output schema, the description adequately signals the return content. It is incomplete on prerequisites (project scope, queryable vs non-queryable sources) and leaves projectId entirely unexplained.

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 undocumented, input container undocumented), and the description provides no parameter meaning at all. The nested sourceId/sampleRows fields are self-documenting in the schema, but the description does nothing 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 ("inspect") plus a precise list of what is inspected: attribute schema, provenance, freshness, and sample features of a dataset/source. This is concrete enough to distinguish it from write-oriented siblings. It stops short of naming which sibling it replaces (e.g. geobble_project_query_database), so it isn't 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?

No when-to-use guidance, no prerequisites, and no alternatives are mentioned. Nothing tells the agent when to prefer this over query_database, explore_collection, or source_update_metadata, nor what state the project/source must be in.

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, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds only the enumeration of valid values, which largely restates the schema enums, and says nothing about return shape, pagination, or caching.

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 loses a point only because the trailing enumeration duplicates the schema enums rather than adding new 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?

This is a simple read-only listing with two optional filters and no output schema; the description conveys the resource and the returned value categories adequately. It could note that an unfiltered call returns all basemap types/themes, but nothing essential for invocation 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 coverage is 100% and both optional filters (type, theme) are fully described with enums in the schema. The description's mention of 'light, dark, vector, raster' and 'DEM' maps loosely onto those enums but adds no syntax or filtering semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

The description names a specific verb ('List') and resource ('basemaps available to a project'), and the enumerated values make the scope concrete. It implicitly contrasts with the mutating sibling geobble_project_set_basemap, but never names it explicitly, so it stops 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?

Usage is only implied: an agent can infer this is a discovery call to run before geobble_project_set_basemap, but the description never says when to use it or what the alternative is. No preconditions or exclusions 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=false (a mutation), idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the effect of adding (availability to layer and query tools), which is genuinely useful, but says nothing about what removal does to dependent layers/queries or any 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?

Two tight sentences, front-loaded with the verb pair and resource kinds, with no filler. Both sentences carry information, though the effect sentence could be slightly more specific.

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 tool with 0% schema description coverage and no output schema, the description is thin. It omits what happens on removal, the meaning of resourceId/title, and any side effects, leaving significant gaps an agent must guess at.

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 carries the full burden. It restates the action enum and resourceType values (already self-documenting via schema enums) but never explains projectId, resourceId, or the optional 'title' parameter, which is completely unaddressed.

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 (add/remove) and enumerates the resource kinds (source, collection, symbol set, theme) plus the target (project context), so the operation is clear. It does not, however, distinguish itself from plausible siblings like resource_share_grant, resource_change_visibility, or project_add_layer, leaving the agent to infer which is correct.

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 use case ('Adding a resource makes it available to project layer and query tools'), which gives some context for when to add. But there is no explicit when-to-use vs alternatives, no exclusions, and no mention of when removal is appropriate versus resource_delete or resource_share_revoke.

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 advertises a delete action ('Create, update, delete, or assign layer groups'), yet annotations declare destructiveHint=false, which per the annotation semantics asserts the tool performs only additive updates. A group removal is a non-additive mutation of the project spec, so the description directly conflicts with the structured safety signal and could mislead an agent about reversibility. The otherwise-useful expectedSpecVersion/stale-write context cannot offset this contradiction.

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: the capability statement comes first and the concurrency requirement second. Each sentence carries distinct information and nothing is repeated from the title 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 compound four-action mutation tool with nested objects and no output schema, the description is only minimally sufficient. It does not say what a stale expectedSpecVersion produces (error vs. silent retry), does not clarify what delete does to the layers inside a group, and gives no response information, though the rich nested schema and annotations cover part of the burden.

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 carry projectId, expectedSpecVersion, and the input envelope. It meaningfully explains the one non-obvious parameter, expectedSpecVersion, as an optimistic-concurrency guard against stale writes, which the schema (bare integer with min/max) does not convey; projectId is self-evident and the nested input fields (action enum, group.id/name/collapsed, layerIds) are documented inside the schema itself.

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 a concrete verb set (create, update, delete, assign) and a specific resource (layer groups in a project map), so an agent can immediately tell this apart from layer-level siblings such as geobble_project_add_layer or geobble_project_reorder_layers. It stops short of explicitly contrasting itself with the closest ambiguous sibling, geobble_project_manage_context, so it is clear but not maximally differentiating.

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 four action verbs imply when to reach for this tool (group CRUD on an existing project map), and the note that expectedSpecVersion is required to prevent stale writes gives a prerequisite. However, there is no explicit when-not guidance and no routing to alternatives, e.g. whether assigning layers belongs here versus geobble_project_add_layer, leaving usage to inference.

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, openWorldHint=false and destructiveHint=false, so safety and repeatability are covered without the description. The description adds that the call returns both status and result, but says nothing about when a result becomes available or how terminal states behave.

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 tight sentence with the key scope front-loaded and no wasted words. It is efficient, though minimal to the point of under-specifying.

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 some burden for describing what a status/result response contains (e.g., pending vs completed vs failed), which it does not. Missing that detail, but the read-only polling model is simple enough that it is still usable.

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 two required UUID parameters, so the schema contributes no prose meaning and the description must compensate. It never mentions runId or projectId, leaving their roles (which project the job belongs to, which run to poll) unexplained.

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 (read) and resource (status and result of a queued mobility analysis job), which is clearly distinct from the sibling geobble_project_analyze_mobility that presumably enqueues the job. It does not name that sibling explicitly, 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 phrase 'queued mobility analysis job' implies this is a follow-up poll after starting an analysis, but it never states when to use it versus geobble_project_analyze_mobility or how polling should be sequenced. Usage is only implied, not 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, destructiveHint=false and idempotentHint=false; the description adds the useful nuance that the SQL itself is read-only while an optional materialisation step creates derived datasets. However, 'read-only DuckDB SQL' sits in tension with readOnlyHint=false, and the description never resolves it explicitly (what exactly gets written, whether it is reversible, auth requirements). Some added context, but the safety picture is left partly ambiguous.

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 that names the verb and resource immediately and wastes no words. The em-dash capability list is dense but readable; only the materialisation clause is slightly tucked away at the end.

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 say what a preview returns and what materialisation yields (e.g. a new source identifier), and it does not. Combined with no guidance on permissions, query limits, or failure modes for a SQL-execution tool, the definition is adequate but leaves real gaps an agent must discover by trial.

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 is expected to compensate for the two required top-level parameters (projectId, input). It adds nothing about either: projectId is an undescribed UUID and the description never mentions the query, title, or action fields beyond the passing phrase 'optional materialisation'.

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 read-only SQL) against a specific resource (the project's GeoParquet data) and enumerates the operations available (filter, aggregate, join, measure). This clearly separates it from siblings like geobble_project_run_spatial_operation or geobble_project_explore_collection, which are not general SQL surfaces, so an agent can select 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?

Usage is only implied: the description tells you it is SQL over GeoParquet, and the 'optional materialisation' phrase hints at the preview-vs-materialize choice. It never states when to prefer this tool over sibling alternatives (e.g. run_spatial_operation, explore_collection) or what prerequisites the project must meet.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered by structured data. The description adds genuinely new context by explaining that expectedSpecVersion is an optimistic-concurrency guard against stale writes. It stops short of saying whether removal is reversible, whether confirmation is expected, or what happens to downstream layer references.

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 mutation stated first and the parameter caveat second. Nothing is padded or redundant.

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

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

For a destructive, non-idempotent mutation, the definition covers the core action and one important guard, and no output schema exists so return values need no explanation. Missing are reversibility, required authorization, and any confirmation workflow, which matter given the sibling geobble_confirm_action.

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 nested input documents layerIds and title, and the description supplements the otherwise-bare expectedSpecVersion with its concurrency-guard purpose. projectId remains explained by nothing beyond its uuid format, though its meaning is self-evident. This is net positive but not full compensation.

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?

"Remove one or more layers from a project map" gives a specific verb (remove), resource (layers), and scope (from a project map), which distinguishes it from geobble_project_add_layer. It does not, however, name or contrast with the many other layer-mutating siblings (set_layer_visibility, reorder_layers, duplicate_layer), so the differentiation is only implicit in 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 description never says when to reach for this tool versus alternatives such as hiding a layer with set_layer_visibility or deleting the underlying resource. The only conditional statement concerns a required parameter, not usage context or prerequisites like confirmation or permissions.

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 and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: expectedSpecVersion exists specifically to prevent stale writes, which signals optimistic-concurrency behavior an agent must respect. It still omits what happens on a version conflict and why the call is not idempotent.

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 core action front-loaded and the versioning constraint immediately after. 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.

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 thin: no permission/auth requirements, no conflict or failure behavior, and no hint about how existing order is replaced. The stale-write note is the one substantive addition. 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?

Schema description coverage is reported at 0% for the top-level parameters, so the description must compensate and it only partly does: it explains the purpose of expectedSpecVersion but says nothing about projectId or the required nested input/title. The important semantic that layerIds must be the complete ordered list lives only in the schema. With low coverage and one of three params illuminated, a middling score fits.

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.' That is unambiguous and distinguishable from siblings like set_layer_visibility or add_layer, though it never explicitly names the boundaries against those neighbours.

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

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

There is no when-to-use guidance, no prerequisite/permission note, and no mention of alternatives among the many sibling layer tools. The only usage-ish statement is that expectedSpecVersion is required, which is a constraint 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds nothing behavioral beyond that: it does not mention batch handling (up to 10 queries), result limits, ambiguity handling for multiple matches, external-service rate limits, or the shape of returned place data.

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 that states both directions of the operation. Nothing in it is redundant or padded.

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

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

The tool has a branching oneOf schema, batch queries, contextual filters, and no output schema. The description covers only the two core modes and leaves the agent uninformed about what a result contains (coordinates, place names, address components, confidence) and about the batch/limit semantics.

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 structured schema is expected to carry the parameter documentation and the baseline is 3. The description does add a small semantic link by pairing 'place names' with the forward branch and 'coordinates' with the reverse branch, 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?

The description names two specific verbs and their resources ('geocode place names to coordinates', 'reverse geocode coordinates to place names'), which maps cleanly onto the two oneOf branches. It is clear and unambiguous, though it never ties those modes to the 'action' parameter or distinguishes this tool from any other resolution-adjacent 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?

Usage is only implied: an agent can infer that forward mode takes place-name strings and reverse mode takes lat/long from the description's phrasing. There is no explicit statement of when to prefer one mode, no prerequisites, and no mention of the sibling tools or any excluded scenario.

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 core profile: readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false. The description contributes one genuinely useful behavioral fact beyond that — derived results are persisted — which tells the agent a new artifact is created rather than an in-flight computation returned. It stops short of saying whether this is synchronous or long-running, whether an existing derived layer is overwritten, or what quota/permission constraints apply, which matters for a geoprocessing call.

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 tight sentence with the action front-loaded and no filler — structurally ideal. It loses a point only because the appended operation list is both redundant with the enum and factually inconsistent with it, which is worse than omitting it.

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 write with a nested parameter object, nine operation variants, and no output schema, so the description bears a heavy burden. It never explains where the derived layer lands in the project, whether the call returns an ID or a job handle, whether it blocks, or how multi-layer ops require secondarySourceId. An agent can guess at the purpose but not at the call 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?

Top-level schema description coverage is 0% (projectId carries only format/pattern, and the 'input' object has no description). The nested fields are well documented in the schema itself (operation enum with single vs multi-layer semantics, secondarySourceId, distanceMeters, keyA/keyB, groupBy), so the description should compensate for the undescribed top level or reconcile the operation list. Instead it repeats a partial and partly inaccurate operation list, adding no meaning beyond the schema and contradicting its enum.

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) plus resource (predefined spatial operation) and adds the notable fact that results are persisted, which cleanly separates it from the sibling configuration/read tools. The parenthetical operation list, however, names 'union', 'spatial join' and 'proximity' — none of which appear in the schema enum (which instead offers bounds, buffer, centroid, dissolve, clip, countPoints, intersect, join, subtract), so the description partially misdescribes its own scope.

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 other analysis-oriented siblings such as geobble_project_analyze_mobility, geobble_project_query_database or geobble_project_inspect_source. No prerequisites (e.g. sources must already exist in the project) or exclusions (e.g. raster vs vector, size limits) 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: expectedSpecVersion gates against stale writes, i.e. optimistic concurrency control, which is not derivable from the schema. It does not explain what happens when only one of light/dark is supplied or whether omission clears a basemap.

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: the action first, the critical constraint second. No filler or restatement of the tool 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 three-parameter mutation with a nested input object, zero schema description coverage, and no output schema, the description is too thin. It omits the conflict/retry behavior on stale expectedSpecVersion, whether both basemaps are required, and how to source valid basemap IDs.

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% at the top level, so the description must carry the burden — and it only covers expectedSpecVersion and the light/dark distinction. projectId is entirely unexplained, and the nested input.title ('Short description of the basemap change') semantics are left to the schema alone. The partial coverage does not compensate for the 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 (assign) and resource (light/dark basemaps on a project map), which an agent can distinguish from the read-only sibling geobble_project_list_basemaps. It stops short of explicitly differentiating from other project_* mutation tools, but the purpose 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?

No when-to-use or when-not guidance, and no alternatives named (e.g., whether geobble_project_list_basemaps should be consulted first to obtain valid basemap IDs). The expectedSpecVersion sentence implies a prerequisite but never states how to obtain the value or what to do on a conflict.

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 write. The description adds genuine value beyond that: the filter is server-side validated, and expectedSpecVersion enforces optimistic concurrency against stale writes. It does not say what happens on version mismatch or whether the mutation is applied live to viewers, which keeps it from a 5.

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

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

Two tight sentences that are front-loaded with the action and effect, with the concurrency requirement attached immediately after. No filler and nothing repeated from the schema.

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 payload and no output schema, the description covers the safety-relevant concurrency contract but omits error behavior on invalid expressions or stale versions, and says nothing about the returned state after the write. Adequate but with visible 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%, so the description carries the burden, and it only illuminates expectedSpecVersion (stale-write prevention). projectId, layerId, the nested input object, and the shape/nullability of the GMS filter expression are left without descriptive meaning beyond the word 'validated'.

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/clear), the resource (a layer's attribute filter), and the effect (controls which features a layer draws), which distinguishes it in practice from set_layer_visibility, set_layer_zoom_range, and update_layer_style. It stops short of naming a sibling tool or exclusion, so it lands at clear-but-not-explicitly-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?

'Set or clear' implies the two modes of use, and the note that expectedSpecVersion is required to prevent stale writes gives a concrete precondition for calling it. There is no guidance on when to prefer this over related layer-configuration tools, or what happens if the version check fails.

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 readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutation/concurrency profile is partly structured. The description adds genuine value by disclosing the optimistic-concurrency guard, but omits what happens on a version mismatch, permissions, or reversibility.

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 operation stated first and the critical version constraint second. Nothing is wasted and the ordering is front-loaded appropriately.

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, three-parameter mutation with no output schema, the description covers the operation and the concurrency contract but says nothing about failure modes, permissions, or the effect of the write. 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?

Schema coverage is 0%, so the description must carry parameter meaning. It explains only expectedSpecVersion ('required to prevent stale writes'), leaving projectId, input.layerId, and input.visibility undocumented beyond the terse schema. It partially compensates but leaves the majority of parameters unexplained.

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 and resource: 'Show or hide one layer in the project map.' This is clearly distinguishable from sibling layer tools (set_layer_filter, set_layer_zoom_range, update_layer_style), though it does not name any of 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?

No statement of when to use this versus alternatives such as set_layer_filter or update_layer_style, and no prerequisites or context beyond the schema. The 'expectedSpecVersion required' clause is a behavioral constraint, not 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-read-only, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds one genuinely useful behavioral fact: expectedSpecVersion exists to prevent stale writes, implying optimistic concurrency. It does not say what happens when the version mismatches, whether the call is rejected or overwrites, 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?

Two short sentences, the core action front-loaded and the concurrency requirement immediately after. Every sentence earns its place with 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 nested-object mutation with no output schema, the description covers the action and the concurrency guard but omits conflict/error behavior, permission requirements, and whether default zoom bounds apply when minZoom/maxZoom are omitted. Adequate for a simple setter, but gaps remain.

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?

Nested schema fields (title, layerId, minZoom, maxZoom) carry their own descriptions and defaults, but top-level projectId and expectedSpecVersion have no schema description, and reported coverage is 0%. The description compensates only for expectedSpecVersion, explaining its stale-write role, and says nothing about projectId or the semantics of omitting minZoom/maxZoom.

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 ('Set a layer's minimum and maximum visible zoom levels'), which is precise enough to distinguish it from siblings like set_layer_visibility, set_layer_filter, and update_layer_style. It stops short of naming those siblings explicitly, so an agent must infer the boundary itself.

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 the neighboring layer-configuration tools, and no preconditions beyond the implicit expectedSpecVersion note. The agent must infer usage context entirely from the name and sibling 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 declare non-read-only, non-idempotent, non-destructive. The description adds genuinely new context: the save path mutates project-level default state and expectedSpecVersion acts as an optimistic-concurrency guard against stale writes. It lacks detail on what a version mismatch returns, but that is a real addition beyond structured fields.

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

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

Two sentences, no filler, and the primary capability is front-loaded before the concurrency caveat. Every clause carries information the caller 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 no output schema and two distinct modes, the definition covers the conceptual core but omits failure behavior on a stale expectedSpecVersion, what happens to an existing default view on save, and any permission requirements. 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 description coverage is 0%, though nested fields (action, title, timing) are self-documenting. The description usefully explains the one opaque parameter, expectedSpecVersion, but says nothing about projectId or the shape of the input/camera union.

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 concrete verb+resource ('navigate the live project camera', 'persist a default view') and captures both operating modes, which is more than the title alone. It stops short of distinguishing itself from near neighbors such as geobble_project_configure_camera or geobble_map_view, so the agent must infer the boundary.

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 implies two usage modes (live navigation vs. persisted default) but never states when to choose one over the other, nor when to reach for the sibling camera/map-view tools. The navigate-vs-save semantics are only spelled out in the schema's action enum, 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 this is a non-destructive, idempotent, closed-world write (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds that the request is 'private' and made 'for the project owner,' which is useful context, but says nothing about who receives it, whether it needs approval, or any 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 the action verb first and zero filler. 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?

For a 5-parameter write tool with 0% schema coverage and no output schema, the description establishes purpose and precondition but leaves parameter meaning and post-submission behavior unexplained. Adequate as a routing signal, incomplete as a calling guide.

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 5 parameters, so the description carries the full burden. It only loosely gestures at 'dataset' ('missing geospatial data') and 'project owner' (projectId), leaving geography, requirements, and knownSourceUrl entirely unexplained beyond the bare schema types.

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 (Submit) and resource (dataset request) with the scope qualifier 'private request for missing geospatial data.' It implicitly distinguishes itself from catalogue/search tools via the precondition, but does not name a specific 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?

Gives a clear usage condition: submit only 'after catalogue search found nothing suitable.' This is a genuine when-to-use signal, though it names no explicit when-not or alternative tool by 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 is a non-read-only, non-idempotent mutation, so safety is partly covered. The description adds one genuinely useful behavioral fact not in the annotations: expectedSpecVersion exists to prevent stale writes (optimistic concurrency). It still omits whether the supplied label object replaces the entire existing label config, what happens on version mismatch, and 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?

Two sentences, front-loaded with the action and followed by the one non-obvious constraint. Nothing is wasted and nothing 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 nested-object mutation with no output schema, the description is thin: it never states replacement vs merge semantics, error behavior on version conflict, or what the call returns. Given the 3 required parameters and nested input, more disclosure is needed.

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 schema leaves projectId and input undocumented. The description compensates for only one parameter (expectedSpecVersion's stale-write role); projectId and the input envelope, including whether label replaces or merges, remain unexplained.

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 (configure/clear) and resource (label definition for a map layer), so the agent knows exactly what changes. It does not, however, distinguish itself from close siblings like geobble_project_update_layer_style, which also mutates per-layer presentation settings.

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

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

There is no when-to-use guidance, no stated prerequisites beyond a bare mention of expectedSpecVersion, and no routing to alternatives. The only hint at usage ('configure or clear') is implicit and duplicates what the schema's null option already conveys.

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 readOnly=false, destructive=false, idempotent=false; the description's 'Merge' wording is consistent and usefully discloses partial-update semantics (properties are merged, not replaced). It also explains the concurrency guard (expectedSpecVersion prevents stale writes), which annotations do not cover. It stops short of describing return behavior or auth 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?

Two tight sentences, front-loaded with the core action and followed by the one critical precondition. Nothing redundant.

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

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

For a large discriminated-union mutation schema with no output schema, the description covers the essentials (merge semantics, version guard) but omits the layerType variant requirement and what the caller receives after a successful update. The rich nested paint description in the schema carries much of the remaining burden.

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. It explains the meaning and purpose of expectedSpecVersion (a version token guarding against stale writes), which the bare integer schema does not, and characterizes the input block as paint and display properties. It adds little for projectId and does not clarify the layerType discriminator, 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?

The description gives a specific verb ('Merge') and resource ('a map layer's symbology') and enumerates the property classes touched (colours, ramps, opacity, stroke). This clearly distinguishes it from siblings like update_layer_label, set_layer_visibility, set_layer_filter, and 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 'Merge ... into a map layer' phrasing implies it targets an existing layer's styling, and it states that expectedSpecVersion is required to prevent stale writes. However, it never says when to choose this over sibling mutators such as add_layer or duplicate_layer, and gives no 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 only declare non-read-only/non-destructive, so the description carries real extra weight: it discloses optimistic concurrency (requiring expectedSpecVersion) and canonical GMS validation, which tells the agent that stale versions and validation failures are expected outcomes. It does not say what happens to fields omitted from settings (preserve vs. clear), which is a notable gap for a merge 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?

A single dense sentence that front-loads the operation and scope before the behavioral caveats. No wasted words, though the parenthetical field list is slightly obfuscating rather than clarifying.

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 required-param mutation with nested objects, no output schema, and zero schema descriptions, the definition is only partially sufficient. It explains concurrency and validation but omits merge/preservation semantics, permission requirements, and the version-conflict error behavior an agent would need to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It names the setting categories and the concurrency parameter's semantics, but its list ('camera, interactions, metadata, and computed fields') does not map cleanly onto the schema's actual keys (title, defaultView, description, zoomConstraints, extentConstraints), leaving the agent to guess which fields are addressable.

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 (Workspace-owned map settings into a project) plus the categories affected. It partially distinguishes itself from siblings like configure_camera/configure_computed by framing this as a bulk merge, though the overlapping field names ('camera', 'computed fields') could confuse selection.

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 explicit when-to-use or when-not guidance, and no mention of the many adjacent sibling tools (configure_camera, configure_computed, set_view, validate_map). The word 'merge' hints at applying workspace settings wholesale, but the agent must infer whether to prefer this over the granular configure_* 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description usefully discloses what is checked, but says nothing about what a failure looks like, whether it errors vs. returns diagnostics, or whether it has side effects on the project state.

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 a colon-list of checks; every word earns its place and nothing is padded. It is perhaps too terse given the tool's complexity, but there is no waste.

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 carries the burden of explaining return behavior; the enumerated check categories partially imply what a result reports, but the agent still cannot tell whether validation returns a report, a boolean, or throws on failure. For a 2-parameter nested-input validation tool, that is a real gap.

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% at the top level: neither projectId nor the required 'input' object is documented in the description, and the nested shape of 'input' is not referenced beyond the phrase 'expected outputs'. The description therefore does not 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?

States a specific verb ('validate') and resource ('project map') and enumerates the four check categories (canonical GMS, renderer compatibility, referenced resources, expected outputs). No sibling shares this purpose, though the description never explicitly differentiates itself from the many project_* tools.

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 alternatives named. The closest hint is buried in the schema's 'reason' example ('before final response'), not in the description itself, so the agent must infer the trigger condition.

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 useful scope context ('full map specification', 'prior version', i.e. historical/immutable), but says nothing about return format or what the specification 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 sentence with the key scope ('full map specification') and the key qualifier ('prior version') front-loaded. 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?

For a simple two-parameter read tool with full annotation coverage and no output schema, the description conveys the essential behavior (reading a historical map specification). It is nearly complete; only an explicit pointer to the history-list sibling and the projectId's role are 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?

Reported schema coverage is 0% at the top level: projectId carries no description and 'input' is undocumented. The description conceptually maps to both ('of a project' -> projectId, 'prior version' -> version) but adds no format or constraint detail. The nested version field is well documented in the schema itself, which partially offsets the 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 specific verb and resource: 'Read the full map specification of a project ... at a prior version.' An agent can tell this is a historical read of a project's map spec. It does not explicitly differentiate from siblings, but no sibling (e.g., geobble_map_view, geobble_project_validate_map) overlaps with the version-history concept.

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, when-not-to-use, or alternative tool named. The phrase 'as it was at a prior version' implies the historical use case, but the crucial guidance ('use the history list to see available versions') lives only in the schema, not the description. An agent gets no routing help here.

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 covered. The description does add one genuinely useful behavioral fact: the result is 'effective' access including inheritance, i.e. resolved rather than raw share records. It says nothing about permissions required or output shape, so this is a modest add rather than a rich disclosure.

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 subject (effective access) leads and the three dimensions follow. Nothing redundant.

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

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

For a two-parameter read tool with rich annotations, the description is close to adequate: it names what the call inspects. But with no output schema and no parameter descriptions, it should say more about the return payload and the accepted resourceType values. Minimum viable rather than 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 0%, so the description carries the burden and does not compensate at all: neither resourceId nor resourceType is mentioned. The enum values live in the schema, but the description gives no hint about which resource types are supported or how the type affects the lookup.

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') and enumerates what is returned: visibility, inheritance, and individual/organization shares. An agent can distinguish this from mutation siblings like resource_share_grant or resource_change_visibility, but it never names or contrasts with the closest read sibling (geobble_resource_view), so it falls short of full 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?

There is no when-to-use guidance and no alternatives named. The description does not say whether to call this before granting a share, after changing visibility, or instead of resource_view; the agent must infer the timing from the word 'effective' 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 readOnlyHint=false and destructiveHint=false, establishing that something is written but nothing dangerous is destroyed. The word 'preview' adds real behavioral context beyond the annotations, but it also creates tension with readOnlyHint=false: an agent cannot tell whether a pending action is created, whether a confirmation token is returned, or how long the preview survives. It does not state that no visibility change occurs until confirmed.

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 appropriately terse, though the terseness borders on under-specification for a tool with a downstream confirm step.

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 tool with three undocumented required parameters, no output schema, and a preview/confirm workflow implied by siblings, one sentence is not enough. An agent lacks the follow-up step, the effect of each enum value, and any idempotency/expiry expectations.

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 three required parameters, and the description mentions none of them. The two enums (PUBLIC/PRIVATE, and the four resource types) are partly self-describing, but resourceId, the required visibility semantics, and the valid resourceType set receive no explanation anywhere 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?

The description gives a verb (preview) and an object (publishing/unpublishing a resource's visibility), so the general intent is discernible. But it conflicts in emphasis with the tool name ('change'), leaving it unclear whether this actually applies a change or only computes one, and it draws no distinction from siblings like geobble_confirm_action that presumably follow 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?

There is no statement of when to call this versus geobble_confirm_action, geobble_resource_share_grant, or geobble_resource_delete/restore. Given the strong preview/confirm sibling pattern (geobble_confirm_action, geobble_cancel_action), the absence of any routing guidance is a clear gap.

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 frames the operation as a 'Preview', which reads as a non-mutating, read-like call, while annotations declare readOnlyHint=false, destructiveHint=true and idempotentHint=false. An agent relying on the description would not expect a destructive operation, and the description offers no compensating disclosure (trash retention, reversibility, 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?

A single short, front-loaded sentence with no filler. It is efficient, though its brevity for a destructive, likely multi-step operation borders on under-specification rather than true conciseness.

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, non-idempotent tool with no output schema and 0% schema description coverage, the description leaves out the essentials: what the preview returns, whether a confirm_action call must follow, whether the trash move is recoverable, and what permissions are needed.

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 carry the parameter burden. It does map the resourceType enum to readable labels (source, collection, map, project), but says nothing about resourceId beyond its UUID format, nor whether the id must belong to the caller.

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 (moving to trash) and enumerates the four resource kinds (source, collection, map, project) that match the resourceType enum, so the resource side is clear. However, 'Preview' directly conflicts with the tool name geobble_resource_delete, which leaves the agent unsure whether this call actually deletes or only simulates the deletion.

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 guidance is given, no prerequisites (auth, ownership) are stated, and no alternatives are named. Crucially, sibling tools geobble_confirm_action and geobble_cancel_action suggest this is a two-phase preview/confirm flow, but the description never says whether a follow-up confirmation is required.

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 and destructiveHint=false, so the safety profile is largely covered. The description adds the meaningful fact that a precondition ('eligible') gates the operation, but does not say how eligibility is determined or what failure looks like.

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 words. Its brevity is appropriate, though 'eligible' adds a vague constraint without elaboration.

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 and 0% schema coverage means the description should resolve open questions: what eligibility means, whether a resource not in trash errors out, and how the SOURCE/dataset naming maps. It covers purpose but not these operational details, so it is adequate rather than 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 0%, so the description must carry the load. It does enumerate the resource kinds, which maps loosely to the resourceType enum, but it says 'dataset' while the enum value is 'SOURCE', and it says nothing about the resourceId UUID format. 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?

Clear specific verb (restore) plus the affected resources (dataset, collection, map, project) and the source state ('from trash'). It implicitly contrasts with the sibling geobble_resource_delete, though it doesn't name that alternative. The qualifier 'eligible' is left undefined, which slightly blunts the precision.

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 siblings such as geobble_resource_delete or geobble_resource_view. The word 'eligible' implies a precondition exists but never states what makes a resource eligible or what happens when it isn't, leaving the agent to guess.

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', implying a non-mutating dry run, while the annotations declare readOnlyHint=false, i.e. a state-changing operation. That is a direct conflict about whether the call has side effects. The annotations otherwise tell us it is non-idempotent and non-destructive, but the description adds no auth requirements, no duplicate-share behavior, and nothing about what the preview returns.

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?

It is a single short sentence with no filler or repetition, which is structurally clean. But brevity here comes at the cost of substance rather than from efficient compression, so it reads as under-specified rather than concise.

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

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

This is a five-parameter access-control mutation with no output schema and no schema descriptions, so the description is the only source of behavioral detail, and it supplies almost none. An agent cannot determine the role semantics, target formats, expiry behavior, or whether a confirming step follows.

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 carry the load, and it does not. It alludes to three target kinds ('user, organization, or public share') while the schema's target oneOf only accepts ACCOUNT and TEAM, so the only parameter hint it gives is partly inaccurate. role, resourceType, resourceId, and expiresAt are never explained.

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 verb ('granting') and object ('user, organization, or public share'), so the general intent of granting resource access is visible. However, the leading word 'Preview' muddles whether the call commits a grant or only simulates one, and the title 'Grant resource access' says something different from the description. It also does not distinguish itself from the sibling geobble_resource_share_revoke.

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, no prerequisites (e.g., must the caller have ADMIN on the resource?), and no mention of the complementary geobble_resource_share_revoke for removing access. 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?

The description says 'preview revoking', which implies a non-mutating read, while annotations declare readOnlyHint=false and destructiveHint=true. An agent following the description would treat this as a safe dry-run; the annotations say it destroys state. With no output schema and no clarification, this is a direct conflict rather than an addition.

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, so it is not bloated. But for a destructive, one-parameter tool, one ambiguous sentence is under-specified rather than efficiently concise; the brevity comes at the cost of the information the 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 destructive operation with full annotation coverage on the danger axis, no output schema, and an undocumented lone parameter, the description should at minimum resolve the preview-versus-execute ambiguity and say what gets removed. It does neither, so the agent is left unable to call this correctly or safely.

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 carry parameter meaning and it does not. It never explains what shareId refers to, where an agent obtains it, or whether it is the share identifier versus the resource identifier. Only the schema's uuid format/pattern gives the agent any structural cue, leaving the semantic gap unfilled.

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

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

The description names a verb ('revoking') and a resource ('an existing share'), so the general target is identifiable. However, the operative verb is actually 'preview', which muddles whether this tool mutates state or only simulates it, and nothing distinguishes it from siblings like geobble_resource_share_grant, geobble_resource_delete, or the confirm_action/cancel_action pair. An agent cannot confidently tell what this tool does from the name and description alone.

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 indication of when to call this versus geobble_resource_share_grant, geobble_resource_delete, or geobble_confirm_action. If a preview/confirm two-phase flow exists, the description never says so, nor does it state prerequisites such as ownership or admin rights over the share.

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 that it both fetches and renders and that the resource must be 'accessible' (implying permission scoping), but it never says what 'render' produces or whether any UI/state side effects occur. That is modest added context, appropriate for a 3.

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 operation first and the object scope second, and no filler. It is efficient, though the trailing qualifier is more vague than informative.

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 display tool with no output schema, 0% parameter coverage, and no annotations describing returns, the description does not state what the agent gets back (a rendered view, image, URL, or payload) or how the identifier is supplied. The critical unknowns for correct invocation are left unaddressed.

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

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

Schema description coverage is 0%, so the description must carry the parameters, and it largely does not. It names the resource kinds that already appear as the `kind` enum, but it says nothing about the required `identifier` — its format (ID, slug, path?), how to obtain it, or whether it is scoped per kind. The description adds no meaning beyond the enum the schema already exposes.

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 (fetch and render) plus the exact resource kinds it operates on (collection, project, map, source), which mirrors the `kind` enum. It is clear on its own, but it never distinguishes itself from heavily overlapping siblings like geobble_map_view, geobble_map_get, or geobble_get, 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 only guidance is the trailing phrase 'for visual inspection,' which implies a rendering use case but does not tell the agent when to pick this over geobble_map_view or geobble_get. With such a crowded sibling set containing two other 'view' tools, the absence of any when/when-not routing is a real gap.

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 a closed world, so the safety profile is covered. The description adds two genuine behavioral facts — results are permission-scoped ('accessible') and merged into 'one ordered result set' — but says nothing about pagination or result shape, matching the calibration's 'adds some value but not rich behavioral context' case.

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: the scope statement is front-loaded and the usage cue follows immediately. 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?

With no output schema and 0% parameter coverage, the description should do more than name the resource kinds — it omits pagination semantics for limit/offset and what a result record contains. Purpose and routing are adequate, but the invocation-level detail is thin for a 4-parameter 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%, so the description carries the full burden, yet it only loosely gestures at the 'kinds' parameter (and names 'datasets' where the enum says 'source'). query, limit, and offset are entirely unexplained, leaving the agent to infer filtering and pagination behavior from bare names and numeric bounds.

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

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

States a specific verb (search) and resource (accessible geospatial resources) and enumerates the kinds covered — datasets, projects, published maps, collections. It partially differentiates from siblings by pointing at the get tools, though it never distinguishes itself from the similarly named geobble_search_view (saved searches).

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

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

Explicitly gives the trigger and the downstream alternative: 'Use it to find GIS data or a map before calling the get tools.' That is clear when-to-use guidance, but there are no exclusions (e.g. when to prefer search_view or project-scoped listing tools) to complete the routing picture.

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 covered. The description adds the meaningful behavioral note that it renders an interactive grid, but says nothing about pagination behavior (limit/offset), result contents, or accessibility filtering beyond the word "accessible".

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 capability stated first and the usage cue second. Nothing is redundant or padded.

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

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

With no output schema, 0% parameter coverage, and no sibling differentiation, the description is too thin to call the tool correctly. It should at minimum explain the kinds filter, pagination via limit/offset, and how it differs from geobble_search.

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 all four parameters, so the schema names them (kinds, limit, query, offset) without explaining any of them. The description contributes zero parameter detail, leaving the kinds enum, the 12/50 limit bounds, and offset-based paging entirely unexplained.

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

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

States a specific verb (Search) and resource (accessible Geobble resources) and adds the distinctive behavior of rendering an interactive result grid. It is clear what the tool does, but it never names the sibling geobble_search, so the agent must infer the visual-vs-plain distinction itself.

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 an implied usage context, but there is no explicit when-not guidance and no named alternative (e.g. geobble_search) to route between. The agent must infer the tradeoff 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=true, idempotentHint=true, destructiveHint=false, so the safe-read profile is covered. The description adds useful context that this reveals readiness of an asynchronous format conversion and issues a fresh capability, but it does not say what happens while still pending, whether repeated calls are cheap, or how the capability materializes.

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 that leads with the verb 'Poll' and packs the resource, condition, and return into one line. No waste, though the condition ('once conversion is ready') is folded in rather than surfaced as its own cue.

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 carries the full burden of explaining the return, yet only gestures at 'a fresh download capability' without describing the pending state or how readiness is signalled. Combined with zero parameter explanation, it is under-specified for an async polling tool with a nested format/TTL parameter.

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

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

Schema description coverage is 0% for two required parameters, one of which is a nested object with an enum of seven export formats and an expiresIn TTL. The description mentions none of this, so it does not compensate for the coverage gap; an agent gets no help on format selection or TTL semantics from the prose.

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 (poll) and resource (a prepared geospatial export), and clarifies the outcome (returning a fresh download capability once conversion is ready). It aligns with the obvious sibling geobble_source_prepare_download, but never names that sibling, so the async hand-off is left implicit rather than differentiated.

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

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

The word 'Poll' and the phrase 'once the format conversion is ready' imply this is the status-check step following a prepare call, but there is no explicit when-to-use, no mention of geobble_source_prepare_download, and no guidance on cadence or when to stop polling. Usage is inferable but not 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 mark this as a write (readOnlyHint=false), open-world (openWorldHint=true), and non-destructive operation. The description adds genuinely new behavioral facts beyond the annotations: SSRF validation of the URL, the enqueue (async) nature, and a bounded import limit. It stops short of explaining how to poll the enqueued job or cancel it.

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 that communicates the action, target, and key behavioral traits with no filler. Sized appropriately for the amount of information conveyed.

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

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

Given the mutation semantics, nested object, 0% schema descriptions, and no output schema, the description is only partially complete. It discloses SSRF and the enqueue but omits any parameter meaning and any pointer to how the resulting async job is tracked or cancelled.

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 says nothing about ownerHandle or the nested upload fields (title, slug, collectionSlug, url, description). For a tool with a nested object, the schema supplies only constraints (patterns, lengths) and no meaning, 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 states a specific verb ('Import') and resource ('a geospatial dataset from a public URL'), which cleanly separates it from read-side siblings like geobble_source_download_status. It does not, however, name any sibling or explain how it differs from geobble_source_prepare_upload or geobble_project_submit_dataset_request, so the distinction must be inferred from the name.

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 and no mention of alternatives, prerequisites, or the fact that the import is asynchronous. The single hint, 'public URL', implies a precondition but leaves the agent to infer the rest.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false) establish the mutation/safety profile, and the description adds meaningfully by disclosing that exports are 'billed' and asynchronously 'enqueued'. That billing and async behavior is exactly the kind of context annotations cannot express. It stops short of stating auth requirements or how the enqueued job is tracked.

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 a colon-separated clause structure that wastes nothing. The primary behavior (return capability) precedes the conditional fallback (enqueue billed export), which is the right ordering.

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, billed, async tool with no output schema and 0% schema coverage, the description covers the key behavioral facts (billing, enqueue, conversion trigger) but omits the structure/meaning of the download object and how to retrieve the enqueued result. Adequate but with clear gaps given the tool's complexity.

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 there are two required parameters, including a nested 'download' object with format and expiresIn fields. The description hints at the format parameter ('requested GIS format') but explains nothing about sourceId or the expiresIn/expiry semantics, leaving the schema to carry the load entirely.

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 (prepare) and resource (dataset download), and uniquely describes the dual-mode outcome: returning a download capability or enqueuing a billed export for format conversion. This clearly separates it from the sibling geobble_source_download_status, though the differentiation is left implicit rather than 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?

The condition that triggers the enqueue path ('when the requested GIS format needs conversion') is stated, implying usage context. However, it never says when to prefer this over geobble_source_download_status for checking results, nor any prerequisites, so guidance is only implied.

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 openWorldHint=false, so the write nature is covered. The description usefully adds that the source is created in a 'pending' state and that a presigned upload capability is returned, but omits constraints present in the schema such as the ~200 MB size ceiling, the credential expiry window, and whether the pending source must later be confirmed or can be abandoned.

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 front-loads the action and its output, with no filler. It could still be slightly tighter, but every clause carries information.

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

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

This is a multi-step, nested-parameter mutation with no output schema, no annotation detail on side effects, and 0% schema description coverage. The description covers only the high-level shape of the call; an agent still lacks the expiry semantics, size limits, and the lifecycle of the 'pending' source after the upload.

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 tool takes a nested 'upload' object with eight fields (title, slug, collectionSlug, fileName, fileSize, expiresIn, contentType, description) plus ownerHandle. The description only loosely gestures at file content types and adds no meaning for any of these fields, so it does not 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?

States a specific verb and resource ('Prepare a dataset upload: create a pending spatial source') and describes the output ('return a presigned upload capability'). It distinguishes itself from siblings like geobble_source_import_url by naming the upload mechanism, though it never names an alternative 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 listing of accepted GIS formats (GeoJSON, Shapefile, GeoPackage, KML, CSV with coordinates) implies when the tool applies, but there is no explicit when-to-use or when-not guidance, and no mention of the URL-ingestion alternative (geobble_source_import_url) or of a required follow-up confirmation step.

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