Add client

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

Goes well beyond the annotations by disclosing side-effect scope (client is not invited, no message is sent, safe to run without confirmation) and a non-obvious state behavior: a previously deleted card matching the same email/phone is resurrected with its old visits, note and birthday unless new values are supplied. That resurrection/overwrite rule is exactly the kind of hidden behavior 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?

Purpose and the hard requirement (phone or email) are front-loaded, and the closure/confirmation facts come next. There is mild redundancy between 'Add a client card to your client list' and 'Adds one client card with a name', and the final sentence packs two distinct ideas (undo path and resurrection) together.

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-param mutation with full schema documentation and no output schema, the description covers side effects, confirmation policy and the interesting resurrection rule. The remaining gap is what the call returns (e.g., a new client id), which matters for follow-up calls like add_client_note or get_client and is unstated.

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, but the description adds a real cross-field constraint absent from the schema: at least one of phone or email is required ('Booksy needs one of them') even though only name is marked required. It also flags that birthday and note are optional/private, reinforcing the schema rather than merely repeating it.

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 ('Add a client card to your client list') and immediately names the counterpart sibling ('delete_client removes the card again'). An agent can distinguish it from find_client/update_client/list_clients 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 usage context — no invite, no message, no confirmation prompt needed before calling — and names delete_client as the inverse operation. It stops short of explicitly contrasting add_client with update_client for an already-existing client, which is the one genuinely ambiguous routing decision among the siblings.

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