aircall_push_insight_card

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

Annotations include readOnlyHint=false, destructiveHint=false, and openWorldHint=false, which already tell the agent this is a write operation but not destructive. The description adds that the card appears on the agent's Phone app during an ongoing call, but does not disclose whether the call must be active, what happens if the call ends, or the exact display behavior beyond the block types. No annotation contradiction is present.

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 one sentence that packs the core purpose, target location, timing, and a concise explanation of the content format. No filler or redundant wording.

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?

Given there's no output schema and the sibling list is vast, the description does enough to explain the call context and content structure. It doesn't mention response/return behavior, but for a push operation like this, the absence is minor since the schema fully covers inputs and annotations cover side effects. The complexity is low (2 params).

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%: call_id is 'The ongoing call ID' and contents is 'Content blocks to display on the card'. The description adds format details for contents (blocks like {type: 'title'|'shortText', text: ...} or {type: 'link', link: ..., label: ...}) which is helpful, but the schema already describes each property. Since coverage is high and description adds example shapes, credit is above baseline.

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 specifies the action ('Push an insight card with contextual info to the agent's Phone app during an ongoing call') and differentiates this from sibling tools by naming 'insight card', 'Phone app', and 'ongoing call'—none of the sibling tools overlap with this niche. The verb 'push' plus the resource 'insight card' identifies a distinct operation.

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 the tool is used during live calls but doesn't explicitly state when to use it versus alternatives (e.g., when not to use, prerequisites like call_id validity or agent availability). No exclusions or alternative tool names are given, but the context of 'ongoing call' gives some guidance.

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