onboard_brand

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

With no annotations provided, the description carries the full burden. It discloses that the tool crawls the site in the background, kicks off potentially async work, sets the brand active (a mutating action), and returns a nextStep payload. It also implies an asynchronous flow, which is useful behavioral context. It could be more explicit about reversible actions or failure modes, but it is substantially transparent.

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 concise and well-structured. It front-loads the step number and purpose, then succinctly lists actions, return value, and mandatory next steps. Every sentence provides necessary guidance with no filler.

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 tool has no output schema and significant side effects (background crawling, audience analysis, brand activation). The description covers the main behaviors, workflow context, and the immediate follow-up steps. It does not detail the nextStep payload structure, but the explicit workflow instructions and warnings make it adequately complete for use.

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%, so the baseline is 3. The description adds some context by linking websiteUrl to the crawl action and name inference, but does not go beyond the schema's own descriptions. It does not introduce new semantic details for parameters.

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 this is step 1 of brand onboarding via the website path. It specifies the concrete actions: crawling the site, kicking off audience analysis and 10 themes, setting the brand active, and returning a nextStep payload. This distinguishes it from sibling tools like set_brand_mediums and get_onboarding_status.

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 explicitly frames this as the first step in a multi-step workflow. It provides direct sequencing instructions: immediately ask the user about social platforms and call set_brand_mediums, and warns not to call get_onboarding_status until mediums are set. This is clear when-to-use and next-step guidance.

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