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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety class is known. The description adds concrete consequence ('which can then overwrite or delete content, publish, or write to an external service') and the failure behavior for a non-pending interaction, though it leaves non-idempotency 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?

Front-loaded with the core action, then branches by type, then consequences, then failure mode. Sentences are dense but every one carries distinct information; nothing is redundant with the schema.

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?

No output schema exists, and the description covers the return ('updated session status') and the error case for stale interactions. Combined with the rich parameter guidance, an agent has everything needed to call it correctly in one attempt.

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?

With schema coverage at 80%, the description still adds real meaning: answers are one array per form step in order, an empty array skips a step, custom text is allowed only where that step's allowCustom is true, and decision comes from response options. The schema alone would not convey the ordering/skip semantics.

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 and resource ('Resolve one pending Replo agent interaction') and scopes it to a single pending interaction with the user's explicit answer. An agent can separate it from get_agent_session or abort_agent_session without opening any 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 explicit branches: permission requests take type=permission plus the decision; questions take type=question plus one answers array per form step. It also states an exclusion ('Never infer an answer') and a recovery path ('call get_agent_session again') when the interaction is stale.

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