execute_plan

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

The description adds substantial behavior beyond the annotations: invalid plans run nothing, steps execute in order, execution stops at the first failing step, outputs already produced stay on disk, every step writes a provenance manifest, and a plan-level manifest records the plan sha256 and per-step outcomes. It also discloses the step_warnings signal for suspicious results. This is rich, non-obvious behavioral context.

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

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

The description is dense but well-organized, front-loading the core purpose before explaining execution behavior, failure semantics, and warnings. It is longer than a minimal description, but the length is justified by the complexity of execution. The only minor redundancy is reiterating 'validate first, then execute' after the opening sentence already says 'Validate, then execute.'

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 multi-step execution tool, the description covers the essential operating envelope: validation, ordering, failure handling, provenance manifests, and the step_warnings caveat. It also notes that outputs persist after partial failure, which is critical for an agent reasoning about side effects. With an output schema present, the description is complete enough for correct invocation and interpretation.

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?

Although the top-level plan parameter has no description in the schema, the description compensates by explaining key semantics: steps run in order, '$step_id' references resolve to earlier step outputs, and manifests are tied to the last output. It also cross-references validate_plan for the exact plan format. The nested schema definitions cover the structural details, so the description adds meaningful semantic value without needing to restate every field.

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

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

The description opens with a specific verb and resource: 'Validate, then execute a geoprocessing plan step by step.' It clearly distinguishes this from validate_plan by stating that execution re-validates first and that the plan format matches validate_plan. The resource and behavior are unambiguous.

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

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

The description gives clear context on when execution happens: only after re-validation, and only valid plans run anything. It also points to validate_plan with 'Same plan format as validate_plan — validate first, then execute.' However, it does not explicitly say when to prefer this over run_operation or when not to use it, so exclusions are missing.

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