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

With no annotations, the description carries the full behavioral burden. It usefully discloses mutating nature, atomic semantics, and the 'replace' implication, plus the botId default source (header/OAuth token). It does not cover permissions/auth requirements, error behavior, or the consequences of replacing existing subscriptions.

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 the core action and its mutating/atomic warning, then uses compact colon-separated field lists. Dense but virtually every clause carries information; no filler.

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 5-parameter mutation tool with no annotations and no output schema, the description covers the essentials: atomic replace, the confirm-first requirement, per-parameter semantics, and the subscription derivation source. Missing only return/error behavior and explicit permission requirements.

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 compensate, and it largely does: it enumerates role and capability enum values, defines responsibilities ('the user's own words'), documents the nested subscriptions shape with op='eq', the 'me' value semantics, and botId defaulting. This adds substantial meaning beyond the bare 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: 'Register or replace this QA bot's profile and event subscriptions atomically'. The scope (profile + event subscriptions, atomic replace) is clear and distinguishable from read siblings like get-bot-profile and ack-bot-events, though no sibling is named explicitly.

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?

Provides procedural guidance ('confirm with the user first', 'derive subscriptions from capabilities per the testchimp skill's bot onboarding guide'), which implies this is a setup/onboarding step. However, it never states when to use this vs get-bot-profile or when not to call it, so routing must be inferred.

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