Ask for an amendment of a run's contract

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

Adds rich behavior beyond annotations: the request is only a ledger line, is free, sends nothing to any model, decides nothing, is judged by a person at a terminal, and stale-version requests are refused. That is exactly the kind of cost, side-effect, and failure-mode context annotations cannot convey.

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?

Front-loads the core action, then the constraints and lifecycle in three dense sentences with no filler. The parenthetical about cost and no-model-involvement is load-bearing rather than redundant.

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?

With 100% schema coverage, no output schema, and clear annotations, the description supplies enough: what happens to the request, the version-currency rule, and the human decision loop. It is slightly silent on what the filing returns or how to track the pending request, a minor gap.

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%, so the baseline is 3, but the description adds meaning: version must be the one you actually read and is refused if no longer current, and it clarifies the role of reason and proposed_text as the argument and the replacement wording. Slightly above baseline.

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 ('Ask for an obligation of a run's locked contract to be changed') and immediately clarifies the scope ('only files a request ... it decides nothing'). This distinguishes it cleanly from contract_read and the other run-management siblings that actually mutate state.

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?

Gives clear context for when to use it: after reading a contract, to propose changed obligation text, with the note that a human decides the outcome. It stops short of naming an explicit alternative path (e.g. when to use write_task or submit_stage instead), so no true when-not guidance.

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