Request a store action (needs approval)

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

Goes well beyond the annotations: it discloses that this only creates a request, that an API key or the tool itself can never approve or execute, that approval binds the exact payload hash and expires after an hour, and even the return shape. None of this is recoverable from the readOnly/destructive/idempotent hints alone.

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 what the tool does and the approval gate immediately, then adds the binding/expiry and return contract without a wasted clause. Dense but every sentence carries operational weight.

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-style request tool with no output schema, the description supplies the missing return values, the approval lifecycle, and the safety constraint. An agent has everything needed to call it correctly and warn the user beforehand.

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 the schema already documents connectorId, payload, reason, and the optional ids. The description reinforces that the payload is what gets hashed for approval, but adds no syntax or format detail beyond it — baseline 3 for a fully-covered 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+resource ("Ask for one connector action") and immediately grounds it with concrete examples (set_rollout, promote_track) on a named connector type. An agent can distinguish this request-only tool from execution tools without opening the schema.

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 use and an explicit precondition ("Confirm with the user first"), plus the crucial constraint that nothing runs until an owner/admin approves in the console. It does not name an alternative tool or contrast with list_connectors, so it stops short of full when/when-not guidance.

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