Create many contacts at once

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses critical behaviors: atomicity for validation errors, the risk that an ambiguous timeout/5xx may still commit, absence of duplicate detection, no auto-retry, and the requirement to verify via list_contacts. This is exactly the non-obvious behavior an agent needs before invoking a batch write.

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?

Four sentences, each earning its place: what the call does/scales to, the return shape, atomicity and ambiguity handling, and the sequential-send/quota guidance. The most decision-relevant facts are front-loaded and no schema content is repeated verbatim.

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 complex batch-write tool with no output schema, the description is complete: it names the return array and resourceName, explains failure semantics and retry safety, addresses duplicate creation, and covers quota/concurrency. An agent has enough to invoke it correctly and to recover from the API's ambiguous failure mode.

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 baseline is 3; the description adds value by saying the entries use the same normalized fields as create_contact and that each entry needs at least one field, which the schema does not explicitly require for the item objects. This helps agents compose valid contacts parameter values.

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 opening sentence states a specific verb ('Creates'), resource ('contacts'), upper bound ('up to 200 in one call'), and the underlying API. It also links entry fields to create_contact, distinguishing this bulk creation tool from single-contact siblings such as create_contact and batch_update_contacts.

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?

The description clearly defines the batch's scope (up to 200 contacts per call) and gives operational directives: re-check via list_contacts after an ambiguous failure and never send mutate batches in parallel. It does not explicitly state 'use create_contact for exactly one contact,' but the 'same normalized fields as create_contact' comparison plus title makes the bulk-vs-single distinction recoverable.

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