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

Annotations only declare readOnlyHint=true, destructiveHint=false, openWorldHint=false; the description explains WHY that holds and what actually happens: nothing is built or charged until the person confirms in their browser, and the build starts only after that confirmation page. It also discloses the return shape (a link) and the human-in-the-loop gate, which annotations cannot express.

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 purpose, then the no-build/no-charge behavior, then parameter guidance. Four sentences, all earning their place, though the confirmation gate is stated twice ('confirms in their browser' and 'confirms on that page'), which is mild redundancy against a 10k-char brief tool that is otherwise tight.

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?

With only 2 params, full schema coverage, and annotations covering the safety profile, the description supplies the remaining essentials: return value (link), the deferred-build billing model, and brief content expectations. Minor gaps remain, such as link expiry or failure modes, but for an agent to call this correctly nothing critical is missing.

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 above that by telling the agent exactly what to pack into brief (business name, what they do, location, services, audience, tone, pages wanted, contact details) and where template_id comes from. It adds content guidance the schema's generic 'Full description of the business' does not.

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 ('Prepare a new WeInc website from a description of the business') and immediately names the observable outcome ('Returns a link'). It also routes the agent to the find_templates sibling for template_id, so it is distinguishable from create_project, create_client, and update_project without opening any schema.

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 clear context: call it when you want a website prepared, and feed everything known into brief. It also names find_templates as the source of the optional template_id, which is real routing guidance. It stops short of explicitly stating when NOT to use this versus siblings like create_project or update_project, so it is clear but not exhaustive.

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