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

Annotations only declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the description carries the interesting behavioral load: the snippet is installed once for all pages, quizzes and their settings are then delivered from the server, is_code_installed means the script has already called in from the site, and re-adding an existing domain returns the existing site with created: false. That last point sits in mild tension with idempotentHint=false, but does not flatly contradict it. Error behavior and whether add returns the snippet are not covered.

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 sites are, then the two actions in order, then the downstream dependency. Every clause carries information (snippet install model, is_code_installed, duplicate-domain behavior, access requirement). Slightly dense in a single paragraph with dash-delimited clauses, but no filler sentences.

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 two-action tool with no output schema, the description discloses the key return fields (created, is_code_installed) and what list returns, which is enough for an agent to call it correctly. Missing only error/edge-case behavior and confirmation of what add returns besides created.

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 schema already explains action, domain normalization (https://Shop.Example.com/path → shop.example.com) and workspace_id; the baseline is therefore 3. The description adds workflow meaning — the site ID is consumed by manage_quiz_site_placement — but adds no semantics about the parameters themselves that the schema does not already provide.

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 states a concrete resource and its scope — workspace sites that display on-site quizzes of type 'micro' — and then splits the two operations explicitly (list = sites with an embed snippet, add = add a site by domain). An agent understands what the tool operates on without opening the schema. Sibling differentiation is only partial: it names manage_quiz_site_placement as a downstream consumer but does not distinguish itself from manage_workspace_domain or get_workspace_details.

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?

It gives clear selection context for each action: use list to get sites that already have the snippet and the is_code_installed flag, use add to register a new domain. It also states the access prerequisite ('workspace access is enough, same as in the dashboard') and notes the resulting site ID is needed for manage_quiz_site_placement, which is a concrete usage hand-off. It stops short of explicit 'do not use this when…' exclusions.

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