expand_capabilities

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

No annotations are provided, so description carries full burden — and it delivers richly. It discloses the additive/superset constraint (rejecting reductions), the specific error condition REDUCTION_NOT_ALLOWED and NO_OP_EXPANSION, the immutability-gap/CVE rationale, audit-log recording with verified caller name, and token resolution paths (param, env, header). This is comprehensive behavioral disclosure for a mutation tool with zero annotation coverage.

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 well-structured with clear labeled sections (When to use, Behavior, Returns, Errors). It is slightly verbose — the CVE/immutability-gap rationale adds some length — but every sentence earns its place by conveying operational constraints. The front-loading of purpose and when-to-use is effective.

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?

Despite having no output schema and no annotations, the description fully specifies the return shape (`{ success, agent, added, capabilities }`), enumerates all error cases with conditions, and covers auth mechanisms. For a mutation tool with behavioral complexity (additive constraint), this is remarkably complete. The version-pinned rationale and audit-log detail fill the gap left by absent annotations.

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 schema already documents all three parameters including semantics for new_capabilities (superset requirement) and agent_token resolution. The description reinforces the superset constraint and 'added' vs 'capabilities' return distinction, but the parameters themselves are well-covered by the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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 ('expand capabilities of an agent') and clearly distinguishes the operation from siblings like register_agent and unregister_agent. It identifies the version (v2.1.4), explicitly notes it is self-managed/additive-only, and explains reductions are handled elsewhere. This is a strong, specific purpose statement that differentiates from the sibling registration tools.

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 'When to use' section explicitly names the scenario (agent registered with narrow caps via SessionStart, later needing more like webhooks). It also gives explicit when-not guidance: reductions are NOT supported here and require unregister+register, and it notes there's no admin equivalent by design. This is explicit when/when-not/alternatives coverage.

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