Inboxes: Update Agents in Inbox

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

With annotations present, the description adds real value beyond them: it discloses the full-replacement/removal behavior (the single most important trait for this tool), the PATCH endpoint, the required auth header, and extra_body passthrough. Note the tension with destructiveHint=false, since removing agents overwrites existing membership, though re-adding is trivial so it is not a hard contradiction.

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 removal semantics are correctly front-loaded, but the body-fields line largely duplicates the schema's required list, and the trailing sentence about Persian text values is partly boilerplate that does not apply to this tool (there are no free-text fields, only IDs).

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 moderate-complexity membership mutation with full schema coverage and annotations, the description supplies auth, endpoint, replacement semantics, and param notes. It omits error behavior (e.g., invalid user IDs) and any sense of the response, though no output schema exists to relieve that gap.

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 baseline is 3; the description adds meaning beyond the schema by flagging inbox_id/user_ids as required body fields, documenting extra_body passthrough, and noting that IDs/numbers may arrive in Persian or Arabic-Indic digits. This digit-handling note is genuinely new information not in 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?

States a specific verb+resource ('Replace the agents of an inbox') and immediately clarifies the replace semantics ('Agents not in user_ids are removed'). This clearly distinguishes it from the sibling mutators gapify_add_inbox_agents and gapify_remove_inbox_agent without needing to name them.

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 'Replace' framing and removal clause imply when to use it (when you want to set the complete membership list), but the description never explicitly routes the agent to alternatives like gapify_add_inbox_agents or gapify_remove_inbox_agent for incremental changes. Usage is inferable but not stated.

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