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

Rich disclosure beyond the annotations: 'installs and posts nothing', returns the version sealed for review, every node and account is carried over, unbound-movement claims are dropped, residual exceptions come back with the result, posting re-judges only accounts bound or unbound, and it is 'Metered only when the model is asked'. The one residual ambiguity is whether the proposed version is persisted anywhere, given the name says 'update' while readOnlyHint=true and the description says nothing is installed - a small gap rather than a contradiction.

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?

Purpose is front-loaded in sentence one, and most sentences carry non-redundant information, so it is not padded. But it is a single unbroken block of ~9 clauses-heavy sentences with opaque constructions ('Claims that bind nothing or bind an account no register statement in the workspace is about are dropped'), which slows an agent parsing the operating rules.

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?

For a model-backed proposal tool with an output schema and full annotation coverage, this covers what an agent needs: what it does and does not mutate, the identity preservation, the claim-dropping rules, the compatible no-op outcome, the exceptions returned, the metering trigger, and the exact next step. Nothing essential is missing.

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 100%, so both parameters are already documented and a 3 is the baseline. The description adds only marginal semantics: that chart_id identifies the installed chart and is preserved across versions, and that workspace refers to the active workspace. No format, constraint, or failure-mode detail for either parameter appears in the prose.

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 opening sentence names a specific verb and resource with scope: 'Proposes the next version of one installed chart (chart_id, required)', and it frames the tool as the repair path for a chart_exception. It also distinguishes itself from create_standard_chart ('like create_standard_chart') and from post_chart_accounts. Clarity is only slightly undercut by domain jargon ('sealed for review', 'claims') that a new agent must decode.

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 states the triggering situation (repairing a chart_exception on an installed chart) and names the exact follow-up tool and condition: 'post_chart_accounts on that chart_id then installs it as the next version (refused there unless add-only) and posts it.' It also notes the no-op case ('A chart that is already compatible is left as it is'). There is no explicit statement of when NOT to use it or how to choose versus re-creating the chart, which keeps it short of 5.

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