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

Beyond the idempotentHint and openWorldHint annotations, the description elaborates on side effects: it creates a watch, is idempotent (returns existing watch on repeat), costs 5 credits only on the first call, and reuses the 'analyze' permission without new OAuth scope. This provides rich behavioral detail not captured in annotations alone.

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 informative but slightly redundant—idempotency and credit costs are mentioned in overlapping ways (e.g., 'returns the existing watch with credits_charged=0' and 'Costs 5 credits ONLY on the first call'). It's not overly long, but could be tightened without losing meaning.

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?

The description covers the tool's purpose, trigger phrases, side effects (credits, idempotency, permission reuse), and the parameters are fully explained in the schema. It does not need to describe the output schema per the guidelines. Overall, an agent has sufficient context to decide when and how to call this tool.

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 100% (both handle and platform have descriptions), so the baseline is 3. The tool description does not add extra nuance about parameter formats or constraints beyond what the schema already provides, so no bonus.

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 action ('Start tracking a creator') and the specific resource (a durable CreatorWatch and baseline snapshot), distinguishing it from siblings like analyze_account or get_changes. It also provides explicit trigger phrases ('track', 'watch', 'follow'), making the purpose unmistakable.

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?

It explicitly says 'Use when the user says track, watch, follow...' which gives clear, actionable guidance. It also implies the tool is for setting up monitoring for future change detection, which contrasts with tools like get_changes (retrieving changes) or list_watches (listing existing watches).

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