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

Annotations already establish a non-read-only, non-destructive, closed-world write. The description adds important behavior beyond that: the write goes live immediately without a build, and repeated calls create duplicate records (non-idempotent). It does not discuss permissions or rollback, but the key operational traits are disclosed.

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?

Three tightly written sentences, front-loaded with the use case, followed by the alternative and the idempotency warning. Every sentence carries useful routing or behavioral 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?

Given the output schema and annotations, the description covers the important operational facts: where the record goes, that it is live immediately, and that duplicates are not prevented. The only minor gap is the unexplained site_id parameter, which is left to the schema.

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 67%, with data and table documented in the schema and site_id undocumented. The description adds some context by tying the tool to database tables and giving example records, but it does not explain the site_id parameter or add syntax guidance beyond the schema.

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 specific verb and resource: add a record to a WebTwizz site's database table, with concrete examples (product, booking). It clearly separates this from edit-site and implicitly from update-site-data by emphasizing 'add' rather than modify.

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 explicitly says when to use this tool and names the alternative (edit-site) for new tables, new columns, or file-based content. The exclusions are concrete, so an agent can route correctly without opening other schemas.

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