create_repository_decision_plan

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

The annotations indicate readOnlyHint=false (so a write is expected), destructiveHint=false (not destructive), idempotentHint=false, and openWorldHint=true. The description adds significant behavioral context beyond those annotations: it states the operation is 'stored' and 'immutable', that it 'persists the plan revision', that snapshot_id is resolved from the bundle when omitted, and that the model optionally picks the planner model. This goes beyond the bare annotations and explains the persistence and lifecycle behavior. It does not contradict annotations, and while it doesn't detail error conditions, it provides meaningful context for a mutation tool.

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

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

The description is efficiently written, with the core purpose stated first, then the bundle resolution detail, the pipeline context, and the alternative. It is two dense sentences but not overly long. Every sentence adds value: the first introduces the action and return, the second explains the LLM stage and the chaining alternative. No fluff, though the phrasing 'model optionally picks the planner model' is slightly awkward. Overall it's well-structured and front-loaded.

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 that the tool has an output schema? No, it has no output schema, so the description must explain the return value, which it does (decision_plan_id plus patch diff). The complexity is moderate (4 parameters, with an optional model and snapshot resolution). The description covers the relationship to the pipeline (simulate and apply), the input from triage, and the persistence behavior. It lacks details about error conditions or exact format of the patch diff, but it provides enough for an agent to know what to expect and how this fits into the 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?

The schema has 100% coverage with descriptions for all parameters, so the baseline is 3. The description adds extra semantic meaning beyond that: it explains that snapshot_id is resolved from the bundle when omitted (which is already in the schema but reinforces it), and it clarifies the role of model as an optional override and the only LLM-touching stage. It also explains the purpose of workspace_evidence_bundle_ref as feeding from triage_repository. This adds context that helps an agent understand dependencies and optionality beyond the schema's dry descriptions.

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

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

The description states a specific action ('Create one stored, immutable repository DecisionPlan revision'), a clear resource (DecisionPlan), and the input (triage workspace evidence bundle), while also mentioning the primary return value (decision_plan_id plus patch diff). It distinguishes itself from siblings by mentioning that it is the only LLM-touching stage and that simulate_repository and apply_repository consume its output, and it explicitly points to run_repository_pipeline as the chaining alternative. This is far beyond a tautology and gives the agent a concrete handle on what this tool achieves.

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 provides explicit guidance on when to use this tool versus alternatives: it is the only LLM-touching stage, and it says to use run_repository_pipeline to chain the entire pipeline in one call. It also implies that if you need to go further in the pipeline, you chain simulate_repository and apply_repository after, making the context of use clear. There are no explicit exclusions, but the alternative is named and the condition for choosing it is stated.

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