Contacts: Create contact inbox

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

Annotations already declare non-read-only, non-idempotent, openWorld; the description goes further by naming the auth mechanism and exact header (api-access-token), disclosing the extra_body escape hatch, and warning that text may be Persian/Farsi and digits may be Arabic-Indic and are passed through unchanged — a genuinely useful non-obvious behavior. It stops short of saying what happens on duplicate creation or what the response contains.

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 before endpoint/auth/body details, and each sentence carries information. The HTTP verb/path line is somewhat redundant with the tool name, and the Farsi/digit note is lengthy, but nothing is wasted.

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 mutation tool with no output schema, the description covers auth, required body fields, the extra_body mechanism and an encoding caveat, and annotations carry the safety profile. It omits return shape and failure/duplicate behavior, but is usable as written for a 5-parameter endpoint.

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 documents id, inbox_id, source_id, account_id and extra_body. The description restates the body fields and marks inbox_id required, adding minimal semantics beyond the schema. Baseline 3 is appropriate.

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+resource ('Create a contact inbox record for an inbox') and reinforces it with the exact endpoint POST /api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes. This is clearly a join/link operation distinct from gapify_create_contact, though it never explicitly contrasts itself with sibling tools like get_contactable_inboxes or create_contact.

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?

Usage is implied by the resource name and the required path components (account_id, id, inbox_id), so an agent can infer you need an existing contact and inbox. However, there is no explicit when-to-use statement, no prerequisite note (e.g., that the contact must already exist, or when to prefer this over assigning an inbox another way), and no alternatives named among the many sibling tools.

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