affiliate_run_diagnostic

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

No annotations are present, so the description carries the full burden. It discloses the return structure (NetworkCapabilities per network plus a server block with version, update availability, and how to apply) and the diagnostic nature. It doesn't explicitly state side-effect profile, but 'diagnostic' strongly implies a read-only operation.

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?

Three sentences, front-loaded with the action and scope, then use cases and return-value details. Every sentence adds value, with no redundant content.

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 simple tool with one optional parameter, no output schema, and no annotations, the description is self-contained: it explains the return values (NetworkCapabilities per network, server block), use cases, and relationship to verify_auth tools. Nothing critical is missing.

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 single 'network' parameter has 0% schema description coverage. The description compensates by indicating the tool runs across 'one or all' networks, implying that providing a network selects one and omitting it covers all. It doesn't specify the exact value format, but sibling tool naming conventions provide enough context.

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 clearly states the tool runs a capabilities diagnostic across one or all registered affiliate networks, answers 'is everything working?', confirms supported operations, and checks server version. This specific verb+resource scope distinguishes it from per-network sibling 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?

Explicitly lists when to use (health check, capability confirmation, server version check) and provides an alternative approach: pair with per-network verify_auth tools for auth failure isolation. This gives clear selection guidance.

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