plan_integration

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

With no annotations, the description carries the full burden and does well: it discloses that no write occurs, that a plan_id is produced, and that harness must be an already-enabled configured name — a real precondition an agent would otherwise miss. It omits plan lifetime/expiry, whether the plan is deterministic, and what happens if the config changes between plan and install.

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 core behavior and the no-write guarantee, then the preconditions and consent requirement. Nothing is padded; the only noise is the RST-style double backticks, which are cosmetic.

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-shape explanation is unnecessary, and the description covers the dry-run semantics, harness precondition, and consent workflow. The main remaining gap is the semantic meaning of approve_level values, which matters for a planning tool whose output depends on that choice.

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 compensate, and it largely does: it enumerates the legal approve_level values (read, dispatch, all, none) which the schema leaves as a bare string with only a default. It still does not explain what each level actually authorizes, which is the meaning an agent most needs.

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 first sentence states a specific verb and resource ('Return the exact installation plan and plan_id') plus a crucial scope qualifier ('without writing'). That qualifier cleanly separates it from the sibling install_integration, so an agent can pick correctly without opening either 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?

It gives an explicit workflow: show the plan to the user and obtain consent before calling install_integration. That is clear when-to-use guidance tied to a named alternative. It does not address edge cases such as re-planning after a failed install or whether a plan can be reused, so it stops short of a 5.

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