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

Annotations only cover the read/write/open-world profile, but the description adds the async contract ('returns pending while the analysis runs'), deduplication behavior ('reuses an active run'), a retry policy with a concrete time window, an authorization prerequisite, and a durable side effect (storing the business analysis). That is meaningful behavioral disclosure well beyond what the structured hints provide.

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?

Compact and front-loaded: the core action comes first, followed by async behavior, retry rules, and non-goals. Nearly every clause carries information, though the trailing API reference URL is boilerplate that adds no selection 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?

No output schema exists, and the description does cover the key return-state concept (pending vs. completed) plus persistence of the result, which is what an agent most needs for an async tool. The remaining gap is brandId's role and whether one is required, which leaves a required-ish decision under-specified.

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% – just the 'confirm' parameter is documented, and url/brandId are bare. The description compensates partially by clarifying that url must be a public website and that confirm gates AI usage, but brandId is never explained (is it required? defaults to current brand?). Baseline 3 for a low-coverage schema that is only half-compensated.

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?

States a specific verb and resource: 'Analyze a public website to understand the brand's business.' It also bounds the operation by naming what it does not do ('does not extract colors or update the strategy brief'), which helps separate it from extract_brand_kit and update_strategy_brief. It stops short of naming its retrieval counterpart get_brand_site_analysis, so sibling differentiation is inferred rather than explicit.

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?

Gives real operating conditions: the AI usage must be confirmed, an active run is reused, and retry is appropriate after failure or if stuck beyond 10 minutes. The exclusion of color extraction and strategy-brief updates further routes the agent away from adjacent tools. It never explicitly points to get_brand_site_analysis for polling results, which would have made this a 5.

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