gc_checkpoint

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

No annotations were provided, so the description carries the full burden of behavioral disclosure. The description explains that 'get' fetches a render payload + risk dot and that resolve supports edit-then-approve, which is some context. But it doesn't disclose what happens on reject (terminates? re-queues?), whether resolve is idempotent, what payload/risk dot represent, or any side effects. For a tool with get/resolve semantics, critical behavioral details are missing.

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 compact, using a bulleted list for the two actions. Each line is dense with information about the sub-operations. The only minor issue is the cryptic 'Story 3.5a' reference that adds no functional value for an agent. Otherwise efficient and well-structured.

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?

The tool dispatches across two distinct operations (get and resolve) with a nested object parameter (edited_args) and no output schema. The description explains render payload/risk dot for get and approve/reject for resolve, which is reasonable, but it doesn't describe the output format of get (what the render payload looks like), the full resolve flow (what happens after approve/reject), or failure scenarios. For a multi-action dispatcher with a nested object, more detail would help the agent.

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 all four parameters (id, action, decision, edited_args) are documented in the schema. The description adds the meaning of the action enum values ('get' vs 'resolve') and the edited_args use case (edit-then-approve), which enriches beyond raw schema. However, it doesn't clarify how decision and edited_args interact (e.g., is decision required when edited_args present?), leaving some ambiguity. Baseline 3 is appropriate given high schema coverage with modest description augmentation.

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 states this is for 'Approval checkpoints (Story 3.5a)' and distinguishes two sub-actions: 'get' fetch a held action's render payload + risk dot, and 'resolve' approve/reject. The verb and resource are clear, though the 'Story 3.5a' reference is cryptic. It's distinguishing internally between actions but doesn't differentiate from sibling tools (though checkpoint semantics are fairly unique among siblings).

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?

The description explains the two actions and what they do, which implies when each would be used (get before resolve, resolve to complete a checkpoint). However, it doesn't explicitly state when to use this tool vs sibling tools, nor does it describe the workflow ordering clearly (must get before resolve, is resolve required after get, etc.). The edit-then-approve concept is mentioned but not fully explained.

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