List Control Revisions

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

With no annotations, the description carries the full burden and does well: it declares 'Read-only' outright and explains the semantics of non-obvious state such as 'discarded' (version replaced by a revert), 'undo_of'/'undone_by', and when 'undo_target' is null. It stops short of stating pagination, ordering, or permission requirements for reading another version.

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-loaded with the one-line purpose and read-only flag, then a dense but well-organized enumeration. The long field-by-field walkthrough overlaps with the existing output schema, so some content is not strictly earning its place, but the prose is tight and skimmable.

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 read-only list tool with a 3-parameter schema and an output schema, the description covers what it does, its safety profile, and the meaning of ambiguous return flags. Since an output schema exists, the extended return-value enumeration is largely redundant rather than necessary, leaving little genuinely 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 67% (version and model_id documented, server_version not), so the schema does most of the work. The description's only parameter-adjacent statement is that undo_target is null 'for any version but the latest', which hints at the version parameter's behavior but adds no new input semantics beyond the schema.

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 ('List every change to a model version's set of controls') with clear scope, and the read-only audit-history framing separates it from mutation siblings like apply_control_changeset or undo_model_change. It does not explicitly name an alternative listing tool (e.g. get_controls) to route against, but the resource is specific enough that an agent can distinguish it.

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 explicit 'use this when / not when' guidance. The only usage signal is the cross-reference that 'undo_target' is the revision undo_model_change(target="controls") would undo, which implies this tool is used to find an undo target, but the agent must infer that.

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