Edit Assumption

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

With no annotations, the description carries the full burden, but it does disclose one genuinely important behavior: the edit creates a new model version rather than mutating in place. It does not cover permissions, validation failures, or undo (undo_model_change exists), so the disclosure is valuable but partial.

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?

Three short sentences, front-loaded with the action and then the versioning side effect and return shape. No filler; only the reStructuredText markup backticks are slightly noisy.

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 the return shape need not be explained, and the description still sketches it. However, for a 12-parameter mutation with subtle partial-update and predicate-rewrite semantics, the description says nothing about how omitted fields behave or the version-creation implications for concurrent callers, leaving it merely adequate.

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 description coverage is 92%, so the twelve parameters — including the tricky clear_exclusion vs exclusion_* precedence and the predicate-rewrite defaults — are already documented in the schema. The description adds no parameter meaning beyond that, which is exactly the baseline case.

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 and resource ('Edit an assumption'), which cleanly separates it from add_assumption, remove_entity, and edit_trust_boundary in the sibling list. It doesn't explicitly contrast itself with adjacent tools like convert_assumption_to_controls, but the resource naming does most of the work.

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 when-to-use guidance: nothing says to prefer edit_assumption over add_assumption for a new assumption, nor when to convert to controls instead. The only implicit cue is the word 'Edit', leaving routing decisions to inference.

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