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

Annotations declare readOnly=false, idempotent=false, destructive=false, and the description adds substantive context beyond them: the action is queued, not executed, until an owner approves, and it requires write scope. The 'Queue ONE action' phrasing also implies each call creates a distinct pending proposal, consistent with non-idempotency.

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 approval-gating behavior is front-loaded and every sentence carries parameter or behavioral information. The framing phrase 'The kind that makes this powerful from an AI client' is a bit of unearned filler, but the rest is dense and useful.

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 mutation tool with annotations and an output schema, the description covers the approval workflow, scope requirement, and per-field semantics of the primary kind well enough for correct invocation. It leaves outbound kind fields to the API registry, which is a documented gap but not a blocking one.

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 0%, so the description must carry the burden, and it does: it maps target=record title, body=record body, extra.class_name=app class, extra.properties={property:value}, extra.relationships=[{type,target_name}], and memory=graph slug. Only `kind` is left to an external registry rather than enumerated inline, which keeps it from a 5.

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+resource: 'Queue ONE action for HUMAN APPROVAL,' and immediately clarifies the scope ('nothing is sent or written until a graph owner approves it'). No sibling tool performs this staged-approval function, so it is readily distinguishable.

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?

Explains the operating context (actions are gated by human approval) and distinguishes the `workspace_write` kind from outbound kinds (jira_comment, slack_message, gmail_send) and `memory`. It notes the write-scope requirement. It stops short of explicit when-not-to-use guidance (e.g., when to call a direct write tool instead).

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