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

The description adds significant behavioral context beyond the annotations: it warns that writes land in a shared AIsa workspace with no per-caller isolation, which is not captured in readOnlyHint/destructiveHint. It also implies partial update semantics ('send only what changes'). These details are consistent with destructiveHint=true and add value for the agent.

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?

The description is concise, consisting of three sentences that each serve a purpose: the first states the action and fields, the second gives the partial-update instruction, and the third warns about the shared workspace. It is front-loaded with the core purpose and contains no redundant filler. The only minor issue is the 'notes' inaccuracy, but structurally it is efficient.

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 write operation with 13 parameters and an output schema, the description covers the essential behavioral aspects: it is an update by id, only changed fields are sent, and the write affects a shared workspace. It does not mention the required id (but the schema does) or error handling, but the output schema presumably covers the response. The shared-workspace warning is critical context that makes the description fairly complete for an agent.

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 schema already documents all parameters. The description adds the partial-update guidance, which is helpful, but it incorrectly lists 'notes' as an updatable field when no 'notes' parameter exists in the input schema (only phone_call_outcome_id, duration, etc.). This inaccuracy could mislead an agent into searching for a notes parameter. The description does not clarify which other fields can be updated beyond the three mentioned, so it only partially compensates for the schema's completeness.

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 description clearly states the action (update), the resource (logged call), and identifies it by id. It lists specific updatable fields (outcome, notes, duration) which, while notes is not in the schema, the intent is unambiguous. It distinguishes from sibling tools like post_apollo_phone_calls (create) and get_apollo_phone_calls_search (search) through the verb and resource.

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 implies this is for modifying existing call records by requiring an id, and it gives a clear instruction to 'send only what changes,' which is a useful partial-update guideline. However, it does not explicitly mention when to use this over creating a new call (post_apollo_phone_calls) or searching, leaving the agent to infer from the name and context. It lacks explicit exclusions or alternative routing.

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