call_recordings

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description still earns credit by disclosing that locked-chat recordings are suppressed from results and that transcripts are speaker-attributed with per-word timings. It does not cover rate limits, pagination behavior, or how missing transcripts are represented.

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 purpose, then a compact action table, then examples – a structure that is easy to scan and every block earns its place. Minor redundancy remains where the action list restates parameter names already documented in the schema.

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?

With no output schema, the description carries the return-value burden and does it well: turns by speaker, start/end seconds, optional per-word timing, and matching lines for search. It omits any mention of target_session (multi-account routing) and result ordering/pagination semantics for search, which leaves small gaps for a 9-parameter tool.

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 baseline is 3, but the description adds genuine meaning beyond the schema by scoping parameters to actions (conversation_id/date_from/date_to/limit on list and search, id on get, include_words only on get) and by showing a real conversation_id format ('5491157390064@c.us') and recording id format.

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 opening sentence states a specific verb and resource ('Read WhatsApp call recordings ... and their transcripts, with every word timed') and adds the distinguishing scope that each recording links to query, get_contact and get_group. An agent can separate this from siblings like query or summarize_conversation without opening the schema.

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 three actions are enumerated with the parameters each one accepts and when each is required ('requires id', 'requires search'), plus four worked examples that model typical calls. There is an explicit exclusion ('Recordings of locked chats are never returned') but no direct 'use X instead of Y' routing against siblings, which keeps this below a 5.

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