Diagnose Bot Instance

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavioral context: it returns live XMPP/ai-service status and recent activity, and it requires a bot instance id from a specific sibling tool. It doesn't describe rate limits, pagination, or failure modes, but for a read-only diagnostic tool the annotations plus the description are adequate.

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?

Two sentences with no filler. The first sentence states the action, endpoint, and return value; the second gives the prerequisite and source of the required parameter. Every sentence earns its place and the most important information is front-loaded.

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 read-only diagnostic tool with strong annotations and a clear endpoint, the description is nearly complete. It explains what the tool returns, where the required parameter comes from, and the alias relationship between agentId and agentIdOrAddress. It doesn't describe the output schema, but no output schema exists and the description's mention of 'live XMPP/ai-service status and recent activity' gives the agent enough to interpret the result.

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 only 33%, so the description must compensate. It does: it explains that botInstanceId comes from ethora-bot-instances-list, and it clarifies the agentId/agentIdOrAddress alias relationship ('either name is accepted, pass whichever you have'). This adds real meaning beyond the bare schema fields, though it doesn't fully document all three parameters.

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 ('Diagnose'), a specific resource ('a specific BotInstance for an Agent'), and the exact endpoint. It also names the return value ('live XMPP/ai-service status and recent activity for troubleshooting'), which clearly distinguishes it from sibling tools like ethora-bot-instance-status or ethora-bot-instance-test-message.

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 description gives clear context for when to use the tool: troubleshooting a bot instance, and it explicitly states a prerequisite ('Requires: a bot instance id from ethora-bot-instances-list'). It doesn't explicitly name alternatives or say when not to use it, but the prerequisite and troubleshooting purpose provide enough guidance to route an agent correctly.

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