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

The description goes far beyond the readOnlyHint and idempotentHint annotations, explaining what the tool actually reports and how the agent should behave in edge cases. It explicitly instructs the agent not to retry when account restriction reports moderation, when to offer suggested projects, and when to follow recommended next steps instead of attempting disallowed bucket creation. This gives the agent safety-relevant behavior that annotations alone do not convey.

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 long, but it is dense with actionable information and organized around meaningful conditionals: account.restriction, onboarding.state, free_plan, and connector health. Each sentence carries operational value, though a lighter structure with section breaks or explicit bullets would make it easier to scan. It is still well front-loaded with the overall purpose.

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?

Given the tool's scope, the description covers what the tool returns, how to interpret key states, when to involve the user, and how to recover if tools are missing. The presence of an output schema reduces the need to exhaustively document return values, but this description also documents the important behavioral consequences of reading the status. No significant gap is left for an agent to stumble into.

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?

The tool has no input properties, so parameter selection is not a challenge. The description does not clutter parameter meanings, and there is no schema gap to compensate for. This matches the 0-parameter baseline of 4.

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 opens with a specific verb and resource: 'Check the authenticated Revdoku account and remote MCP capabilities.' It goes on to name the exact data areas inspected, including onboarding, publishing, restrictions, and server version. This distinguishes revdoku_status from the many bucket and website preview siblings.

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 provides clear situational context: check account state, capabilities, and whether the connector is functioning. It also gives conditional guidance for empty_account, no_visible_buckets, and missing tools, which tells the agent what to do after calling this tool. It does not explicitly contrast this tool with sibling tools, but the read-only account-level status role is clear enough.

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