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

Annotations already declare not read-only, open-world and non-destructive, so the description focuses on traits the annotations can't express: the import runs in the background for a few minutes, the return carries `id` and `status`, and a duplicate site is refused with a `duplicate` error. It stops short of covering the `articles` kind or failure modes other than duplicates, so it is strong rather than exhaustive.

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?

Front-loaded with what the tool does, then the kind choice, then the async/return behavior, then duplicate handling – a logical order with no filler. It is a single dense block, though, and the duplicate-handling sentence is long enough that it takes a careful read to parse.

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 5-parameter mutation tool with no output schema, the description covers what matters most for correct invocation: background import timing, the `id`/`status` return, and duplicate recovery paths. The gap is that it neither explains the `articles` kind nor any non-duplicate failure, leaving a modest blind spot.

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 the baseline is 3, and the description earns a notch above it by giving the crawl scope ('pages at and under `baseUrl`') and the practical meaning of each `kind` value. It does not mention `maxPages` or `excludePaths`, which the schema already documents, and it never addresses the `articles` enum value that the schema itself also under-describes.

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: it teaches Aide a website by crawling pages at and under `baseUrl`, and answers customers from the imported content. It distinguishes the two relevant kinds (`website` vs `help_center`) and clearly separates itself from sibling readers like get_knowledge_source or reimport_knowledge_source.

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 routes the agent: use `website` for the company site, `help_center` for Zendesk/Intercom, use get_knowledge_source to check status later, and on a `duplicate` refusal look up the id via get_setup_status or list_knowledge_sources then retry with reimport_knowledge_source. Alternatives and their triggering conditions are named, not implied.

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