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

Annotations already declare non-readonly, non-idempotent, open-world, non-destructive, but the description carries the real behavioral weight: creation is asynchronous with analysisStatus "analyzing" and requires re-polling get_brand until a profile appears. It also discloses plan gating ("free, needs an active plan", per-plan brand limits) and an unusual refusal path with a recoverable id — none of which are inferable 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?

Front-loaded with the core action and the async behavior, then the refusal path, then the caution to ask the user — a sensible ordering with no filler. It is a single dense paragraph with long compound sentences, so the conditional branches around reactivate/fource are harder to scan than they could be, but every clause carries operative information.

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?

Covers what an agent must do before (ask the user), during (choose website vs description, set contentLocale), and after (poll get_brand until the profile answers) invocation, plus the exception path for archived duplicates. With no output schema present, the description supplies the essential return signal (analysisStatus "analyzing") that would otherwise be 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 high (83%), yet the description still adds meaning the schema lacks: contentLocale is the language posts are written in and defaults to the user's interface language, description becomes the profile's description when no website is given, and reactivateProjectId restores the archived brand with its posts and profile rather than creating fresh. It also clarifies the choice between reactivateProjectId and force.

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?

Opens with a specific verb+resource ("Makes a new Simplo project (one per brand)") and immediately scopes the two creation paths, website vs. description. This distinguishes it cleanly from siblings like update_brand, get_brand and list_projects, and even reconciles the title mismatch by defining a project as one-per-brand.

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 explicit routing rules: pass websiteUrl when a site exists, a description when it doesn't, description-plus-website is treated as extra context, and description-only requires follow-up via update_brand. It also names alternatives by name (get_brand for polling, update_brand for filling profile fields, reactivateProjectId vs force) and states the human-in-the-loop rule "Ask the user before making a brand."

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