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

Annotations declare destructiveHint=true and openWorldHint=true, and the description usefully adds that a request is not a grant, that consequential capabilities are refused without prior Human grant and even then held for a Human decision, and that the result carries the primary actor block. This is real authorization behavior beyond the safety flags, though error/refusal response details are left implicit.

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 prerequisite is front-loaded in a bracketed tag, and each sentence contributes (admission, non-granting transport, capability naming, refusal semantics). The prose is dense and parenthetical-heavy, which slows parsing, but there is little wasted text.

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 four-parameter mutation tool with no output schema, the description covers admission prerequisites, capability discovery, payload semantics, and the consequential-act gating. It is nearly sufficient, with only the shape of returned/refused results left under-described beyond the 'primary actor block' remark.

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 the per-field descriptions already carry baseline meaning. The description nonetheless adds value by tying 'capability' to concrete act names and their payload shapes (e.g. evidence.append with payload {content}) and by noting payload belongs to the named capability, which the schema states only abstractly.

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 a specific verb+resource ('Request an external act') and clarifies the core mechanism: the act is named by a 'capability' string such as evidence.append or release:outside. It distinguishes itself from the transport/authorization layer ('Transport does not grant it'), but does not explicitly separate itself from generic siblings like atlas.use or atlas.room_act.

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 prerequisite chain clearly ('NEEDS ADMISSION: enroll, then atlas.bind_actor') and routes the agent to atlas.list_capabilities to discover which act names it holds. It also flags that release:outside is refused unless granted by the Human. It stops short of saying when to choose this over sibling action tools, so not a full 5.

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