track_brand

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

Annotations only declare readOnlyHint=false and openWorldHint=true, which cover mutation and side effects. The description adds significant behavioral detail beyond this: the dual-mode prompt generation (Claude Haiku when ANTHROPIC_API_KEY is set, otherwise three generic starter prompts), explaining the conditional behavior based on env configuration. This is genuinely valuable context an agent wouldn't infer from annotations.

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 well-front-loaded with the core purpose in the first sentence, followed by operational details. It's dense with useful info (trigger phrases, env-dependent behavior, follow-up action) but each sentence earns its place. Slightly longer than minimal, but every clause adds value.

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 mutation tool with openWorldHint=true, the description covers the key behavioral facets: side effects (DB creation), conditional prompt generation, and the required refresh_brand follow-up. It doesn't detail return values, but an output schema exists which flags this context signal, so that's acceptable. The main gap is not clarifying how competitors/aliases/exclude_terms fully affect behavior, but the schema already documents their semantics.

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 coverage is 100%, so all 8 parameters are documented in the schema itself. The description doesn't add parameter-specific details beyond what's already there, but it does clarify the prompt_count behavior in context (generation of buyer-intent prompts). Baseline 3 is appropriate given full schema coverage.

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 uses a specific verb+resource ('Start tracking a brand's AI visibility') and clearly explains what the tool does: creates the brand in the local DB and generates buyer-intent prompts. It distinguishes itself from siblings by noting the upgrade path to generate_prompts and the follow-up refresh_brand call.

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?

Provides explicit trigger phrases ('track my brand', 'add my site', 'start monitoring acme.com') and a clear when-to-use scenario (when another tool reports the brand doesn't exist). Also names the alternative tool generate_prompts and the required follow-up refresh_brand, giving strong usage context.

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