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.