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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the mutation profile is covered. The description adds useful non-structural context: untouched fields retain current values, semantics mirror create_sip_trunk, and the response returns updated attributes with passwords masked or a readable error. This is above the annotation baseline, though it does not detail auth/permission requirements.

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 tightly packed sentences, each earning its place: purpose, invocation contract, sibling routing, and return behavior. The most decision-relevant information (which sibling to use) is front-loaded and unambiguous.

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 49-parameter mutation tool with no output schema, the description is unusually complete: it clarifies the partial-update contract, delegates field semantics to create_sip_trunk, and describes the return value including password masking. Remaining gap is minor – no mention of permissions or error conditions in detail.

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% with rich per-field documentation, so the schema does the heavy lifting and the baseline of 3 applies. The description reinforces the partial-update semantics (only send changed fields) and points to create_sip_trunk for field meaning, but adds no syntax or format detail 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?

States a specific verb (Update) and resource (SIP Voice IN Trunks) with the defining scope 'inbound voice trunks'. It explicitly distinguishes this tool from its two closest siblings, update_pstn_trunk and update_phone_systems_trunk, so an agent can unambiguously select it.

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 explicit routing rules: PSTN trunks go to update_pstn_trunk, phone.systems™ trunks to update_phone_systems_trunk. It also states the update contract ('pass ONLY the fields to change, never invent values'), which tells the agent how to invoke it rather than just when.

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