simulate_repository

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

With all annotations false (no hints provided), the description carries the full burden. It discloses the deterministic engine, that no LLM is involved, that snapshot_id resolves when omitted, and that seed makes results reproducible. It does not explicitly state whether the operation mutates state, but the term 'simulate' and 'score' imply a read-only action, which is reasonably transparent for the 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 three sentences, front-loaded with the core purpose, then provides parameter behavior and usage routing. There is zero redundancy or fluff; every sentence adds necessary 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?

Given there is no output schema, the description does explain the return envelope and its role in apply_repository. It covers prerequisites, alternative, optional parameters, and resolution rules. It doesn't describe the DecisionEnvelope structure in detail or potential failure modes, but the tool is well-scoped and the description is sufficiently complete for an agent to call it correctly. Minor gaps prevent a 5.

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 every parameter has a description. The description essentially restates the schema for runs, seed, and snapshot_id, adding no new meaning beyond the schema. It adds the 'no LLM' note, which is behavioral rather than parametric, so the incremental value for parameter understanding is minimal. Baseline 3 is appropriate.

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 clearly states the action (score patch risk), the resource (stored repository DecisionPlan), and the output (gated DecisionEnvelope checked by apply_repository). It explicitly distinguishes itself from simulate_repository_patch, which handles patches without a stored plan, making its scope 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?

It gives explicit prerequisites ('Call create_repository_decision_plan first') and names the alternative tool for the other case ('use simulate_repository_patch instead for a patch that has no stored plan'). It also explains when to omit optional parameters, leaving no ambiguity about invocation context.

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