Smitline

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds substantive behavior beyond that: the return shape (ok, the brief as it would be placed, blocking problems, carried-note count) and the brief_incomplete error path with a question to ask the user. Minor deduction because it doesn't say whether the response is a dry-run artifact that can be passed straight to start_call.

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 tight sentences, front-loaded with the identity-defining constraint, then outcomes, then the routing rule. Every sentence carries information an agent needs; nothing is padded.

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 21-parameter tool with no output schema, the description covers the missing piece — return values and the incomplete-brief path — so an agent knows what to expect and how to handle failures. Schema covers the inputs, description covers the outputs; nothing material is absent.

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 95%, so the 21 parameters are already thoroughly documented in the schema; the description adds no field-level meaning beyond two illustrative failure cases (missing setup, refused number). Baseline 3 applies when the schema does the heavy lifting.

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 (validate) and resource (a call brief), with the defining scope constraint: 'exactly as start_call would, without placing a phone call or joining a meeting.' That makes it unmistakable versus start_call and the other call-management siblings.

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?

Explicitly names the condition for use ('when unsure whether a brief is complete') and the alternative ('start_call runs the same checks itself'), so an agent knows both when to reach for this and when to skip it. That is exactly the when/when-not/alternative triad.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds some behavioral nuance (polite wrap-up, handling unconnected calls) but does not detail what gets destroyed, auth needs, or rate limits. With annotations covering the safety profile, a 3 is appropriate.

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?

A single, front-loaded sentence with no wasted words. It efficiently conveys the two use cases. 5.

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 the simple one-parameter tool, rich annotations, and no output schema, the description covers purpose and usage adequately. Minor gaps (e.g., what happens if the call already ended) are not critical. 4.

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% for the single callId parameter, and the schema itself describes it as 'Call id returned by start_call'. The description does not add any parameter meaning or format details. Baseline 3.

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 states a specific action: 'Ask the assistant to wrap up politely and hang up, or cancel a call that has not connected yet' – clear verb+resource. It does not name any sibling tool for differentiation, so it fits a 4.

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?

It gives clear context for when to use: wrapping up an active call politely or cancelling an unconnected call. It does not mention alternatives like transfer_call_to_me or send_call_instruction, nor any when-not conditions, so 4.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds non-obvious behavioral detail: it enumerates the full status lifecycle and explains what a finished call includes (result, outcome, summary, details, transcript, cost). It also notes not_found error behavior. This goes nicely beyond the annotations, though it's not exhaustive about rate limits or auth.

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?

Dense but efficient: packs status sequence, output details, error behavior, and sibling alternatives into three sentences. Front-loaded with the core action. Every sentence earns its place.

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?

No output schema exists, so the description must explain return values—it does, by describing what a finished call includes. It also covers error cases. However, it doesn't detail pagination (not relevant) or authentication requirements. Given the simple single-parameter tool and annotations covering safety, this is nearly complete, but could mention that the call must belong to the authenticated user.

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 implies that 'callId' refers to any known call, and the schema itself gives a concrete example. The description doesn't add much beyond what the schema provides, but the lifecycle context hints at what the callId represents. Slightly above baseline for implicit utility.

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?

Specific verb+resource: 'Get one phone call or meeting and its current status.' Clearly distinguishes itself from siblings: wait_for_call for waiting, list_calls for finding ids. The purpose is unmistakable.

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?

Explicitly names alternatives and when to use them: 'To wait for a call to finish, use wait_for_call instead; to find call ids, use list_calls.' This gives clear routing without ambiguity.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the non-obvious behavioral fact that this content is injected as background into every call, and it sketches the shape of the returned data (identity, contacts with name/relationship/phone/notes, style, boundaries). It does not cover auth or rate limits, but those are unlikely concerns for a local profile read.

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?

One sentence, front-loaded with the verb and resource, then the content enumeration. It is dense but every clause adds information about what the profile contains. Slightly list-heavy but nothing is padding.

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?

There is no output schema, so the description carries the return-value burden, and it does so reasonably by naming the categories of data returned, including the nested contact fields. Adequate for a zero-parameter read tool, though a sentence on when the profile is refreshed or how it relates to update_profile would complete it.

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?

The tool takes zero parameters, so the schema fully documents the input surface and no parameter description is required. Baseline 4 applies; there is nothing for the description to clarify or omit.

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 states a specific verb+resource (read the user's profile) and enumerates the profile's contents — identity, contacts with their fields, communication style, and boundaries — which meaningfully distinguishes it from siblings like list_contacts or update_profile. It stops short of explicitly naming which sibling to use instead, so a 5 is not warranted.

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?

"which every call gets as background" is genuinely useful routing context — it implies the profile may already be supplied and that this call is for retrieving it explicitly. However, there is no explicit when-to-use/when-not-to-use guidance and no alternative tool named for related needs (e.g. list_contacts for people data).

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior the annotations don't: newest-first ordering, a default limit of 20 with a hard max of 100, and the absence of paging. That is substantive context, though it stops short of noting any rate limits or freshness guarantees.

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?

Two tightly packed sentences: the first covers scope, ordering, and return fields; the second covers filters, limits, the no-paging constraint, and the routing alternative. Nothing is padding and the most important facts are front-loaded.

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 still enumerates the shape of each result (id, status, brief, outcome) and ordering, and it covers the limit/paging behavior and all filtering axes. An agent has everything needed to call it correctly and interpret results.

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 only 50% (task and contact are documented; limit and channel are not), so the description must compensate, and it does: it clarifies contact means one E.164 number, channel is phone vs meeting, and limit defaults to 20 capped at 100. This meaningfully fills the schema gap for the two undocumented parameters.

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 opens with a specific verb and resource ('List recent phone calls and meetings') and immediately names the returned fields (id, status, brief, outcome), so an agent knows exactly what it gets. It also distinguishes itself from get_call and wait_for_call, which cover the single-call case.

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?

It states the three available filters (channel, contact, task) and when they apply, then explicitly names the alternatives for a different job: 'Use get_call or wait_for_call for one call's full result.' It even explains the operating constraint (no paging, narrow with filters), which guides correct usage.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so 'Read-only and takes no arguments' largely restates structured data and the empty schema. The description does add useful data semantics (carry-over behavior of earlier calls), but says nothing about ordering, completeness, or result limits for a potentially long list.

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?

Two sentences, front-loaded with scope and followed by routing guidance; every clause carries information. The first sentence is long and packs five output fields, but none are filler.

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?

No output schema exists, so the description must carry the return-shape burden and it does, enumerating the per-contact fields. It omits ordering/pagination behavior, which matters for a full-list, argument-free tool, but otherwise an agent has what it needs to call it correctly.

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?

Zero parameters, so baseline 4 applies; there is nothing to misinterpret. The 'takes no arguments' clause is redundant with the empty schema but harmless.

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 and resource ('List the people and businesses Smitline has called or been called by') and enumerates the fields returned (phone number, saved name/notes, call count, latest call, carry-over flag). It explicitly distinguishes itself from siblings list_calls and get_profile, so an agent can select it without opening schemas.

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?

Names two alternatives with the conditions that select them: list_calls with a contact for one contact's calls, and get_profile for people the user described. Combined with the stated scope ('people and businesses Smitline has called or been called by'), the routing decision is unambiguous.

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

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

Annotations already declare readOnlyHint=true and the description's 'Read-only' line is largely redundant. However, it adds real behavioral context the annotations do not: the payload includes the default voice, and omission of the parameter routes to the setup-chosen default.

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?

Three short sentences, front-loaded with what is listed, then the integration point, then the safety/no-arg note. No filler.

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?

There is no output schema, so the description carries the return-value burden and does so: the voice list plus the default. With a zero-parameter read-only tool, nothing an agent needs to call it correctly is missing.

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?

Zero parameters, so the baseline is 4. The description confirms 'takes no arguments', consistent with the empty schema and additionalProperties=false.

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?

Specific verb+resource with scope: it lists GPT-Live voices usable by a call or meeting, plus the default voice. It also distinguishes itself from siblings by naming start_call as the consumer of its output.

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?

It states the downstream use case precisely ('Pass one as voice in start_call's brief') and what happens if omitted (calls use the setup default), which is close to explicit when/when-not guidance. It does not name a competing sibling to avoid, so it falls short of a 5.

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

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

Annotations only declare the generic profile (not read-only, not destructive, open-world, not idempotent); the description adds the real behavioral detail: the voice stays silent unless announce is true, done still records after the call ends, details are posted to a meeting's chat and may fail, and the voice speaks at the next natural pause. This is exactly the context annotations cannot carry.

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 purpose is front-loaded, but the body is a dense run-on of semicolon-joined clauses and parentheticals that reads like stream-of-consciousness rather than structured guidance. Nearly all content earns its place given the asynchronous protocol, but the packaging makes it harder to scan than it needs to be.

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 7-parameter, no-output-schema, multi-step conversational protocol this covers the workflow, timing, approval rules, and failure modes thoroughly. The gap is that with no output schema, the description never states what a call to this tool returns, leaving the agent to infer the response shape.

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 86%, so the schema already documents most fields; the description still adds genuine semantics on top: what status vs done mean in the conversation flow, what announce controls, when ok:false applies, and why text must be speakable while links/code/numbers belong in details. It does not explain the requestId format or callId, but those are well covered by 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?

The first sentence names a specific verb and resource ('Answer a request someone on the call made') and anchors it to the sibling tool that produces those requests ('live.requests in wait_for_call'). An agent can distinguish this from send_call_instruction or save_call_note without opening any 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?

Explicit branching guidance is given: status for progress with the first one signalling pickup, done once at completion, 'a small question: answer with done straight away', 'a bigger task: status first, then done'. It also names a prerequisite check ('Before done, check the last wait for an add on the same request') and an approval constraint for side-effecting actions.

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

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

Annotations already disclose the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the description's job is to add context, which it does: it explains the carry-forward linkage via carryFrom and the summary fallback. It does not say whether a second save replaces or appends to an existing note, which is the main behavioral gap.

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?

Three sentences, front-loaded with the action and timing before the mechanics, with no filler. The middle sentence is somewhat dense ('this call, its task, or its number'), but each sentence carries distinct information.

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?

There is no output schema, so return values need no explanation, and annotations cover safety. What remains underspecified is the mutation semantics (overwrite vs append on a repeat save) and error behavior for an invalid callId, but for a two-parameter note tool the description is largely sufficient.

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 50%: callId is documented in the schema while text has only a type and maxLength. The description compensates by telling the agent what belongs in text ('the quote, terms, and dates a business gave') and frames it as 'short', which aligns with the 1200-character cap. It stops short of mentioning the length limit or which call identity forms carryFrom accepts.

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 gives a concrete verb and resource ('save a short note'), marries it to a trigger ('after a call ends'), and explains the downstream effect (later calls start with it when carryFrom names this call). That mechanism is unique among the siblings, so an agent can separate it from get_call, end_call, or list_calls without opening a 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?

It states the condition for use ('after a call ends') and indirectly states the cost of skipping it ('Without a note, later calls use the call's summary instead'). No alternative tool is named, but none competes for this job, so the guidance is effectively complete.

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

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

Annotations already cover the safety profile (readOnly=false, idempotent=false, openWorld=true, destructive=false), and the description adds genuinely non-structured behavior: it acts immediately, silent:true downgrades it to a background note applied when relevant, and it returns a conflict error after the call ends. It does not cover auth/permission expectations or whether repeated sends accumulate, so it stops short of a 5.

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?

Three tight sentences, with the core behavior front-loaded before the silent mode nuance and the sibling-routing note. No sentence is filler and the examples earn their space by clarifying what 'guidance' means.

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?

There is no output schema, so the description carries the return-side burden; it discloses the conflict error rather than a success payload, and no success return shape is described. Combined with the naming of sibling alternatives, this is nearly complete for a 3-parameter write 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 description coverage is only 33% (only callId is documented in the schema), so the description must compensate. It does explain silent's semantics well, but the required text parameter is only implied through examples, and no length/format guidance (e.g., the 2000-char cap) is conveyed.

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 opens with a specific verb+resource+state: passing guidance to a voice during an in-progress call or meeting, with concrete examples. It explicitly distinguishes itself from end_call and transfer_call_to_me, so an agent can route correctly without opening any 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?

It clearly states the enabling condition (call still in progress), the two named alternatives for adjacent intent (end_call, transfer_call_to_me), and the failure mode once the call has ended. The one gap is that silent: true overlaps conceptually with the sibling save_call_note, and the description never tells the agent when to prefer one over the other.

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

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

Annotations already flag openWorld=true, non-idempotent and non-destructive, but the description adds genuinely non-obvious traits: the tool is asynchronous and returns at once, the profile is injected automatically, recording discloses to the other party, and after-hours calling is restricted. It does not describe the shape of the structured result, which matters since there is no output schema.

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 channel scope are front-loaded, then briefing guidance, then the follow-up flow. Every sentence is doing work, though it is dense at eight sentences and the 'Smitline talks with people in real time using GPT-Live' line is more branding than instruction.

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 21-parameter, nested, asynchronous tool with no output schema, the description covers the call flow, the profile dependency, rehearsals, recording disclosure, and the handoff to wait_for_call. The one gap is what the 'structured result' actually contains, which the agent must discover by calling get_call.

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 95%, so the baseline is 3; the description earns a notch above by explaining how to compose the brief — objective, questions, mayAgreeTo, mustNotShare, and the summary/facts/details split for context — rather than restating field names. It adds intent-level guidance the schema's per-field strings do not fully convey.

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?

Opens with a specific verb+resource pair ('Place a phone call or join a video meeting for the user') and immediately names the agent behind it and the two channels. An agent can distinguish it from wait_for_call, get_call, or end_call without opening any 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?

Gives explicit routing: 'Returns immediately; then call wait_for_call with since: "" to follow the call live.' It also states prerequisites ('If anything required is unknown, ask the user instead of guessing') and a conditional alternative ('For a first call to someone new, offer a rehearsal'). When-to-use and when-to-do-something-else are both covered.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and non-idempotent, so the safety profile is covered by structured data. The description adds only the precondition that the call must be 'connected'; it doesn't say what happens to the AI leg of the call, whether the transfer is reversible, or that the bot stops handling it.

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?

Two short sentences, action first, constraint second. Every word earns its place with zero filler.

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 one-parameter tool whose annotations carry the destructive/open-world profile and whose schema documents callId, the description is nearly sufficient. The only missing piece is post-transfer behavior (that the call continues on the user's phone / the bot hands off), which would help an agent set expectations.

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% and the single callId parameter is fully documented in the schema, including its format and origin (start_call). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 and resource: 'Hand a connected phone call to the user's own phone.' An agent can tell this is not end_call or start_call, though the description never names those siblings explicitly, so differentiation is implied rather than stated.

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?

'Only when the user asks to take over' is an explicit precondition and a when-not constraint. It does not name alternative tools (e.g., end_call) or what to do if the call isn't connected, but the trigger condition is unambiguous.

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

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, but the description adds genuinely load-bearing detail: passed fields replace saved ones (replace, not merge), people are matched and upserted by name, and removePeople deletes entries. The security constraint (no passwords, keys, or payment details) is also real behavioral guidance not present in any structured field. Note a mild tension with destructiveHint=false given that removePeople drops data, though the scope is limited to the agent-managed profile.

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?

Three tight sentences, zero filler, front-loaded with the core action followed by mutation semantics then the safety constraint. Each clause earns its place by covering a different parameter family.

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 mutation tool with annotations present and no output schema, the description covers what gets changed, how people are keyed, how deletion works, and what must never be stored. The one gap is partial-update semantics for omitted fields, which matters since all five parameters are optional.

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 only 40%, so the description must compensate, and it does for the highest-risk parameters: replace semantics for about/style, name-based identity for people, and deletion semantics for removePeople. It does not clarify what happens to fields the caller omits (whether they are preserved or cleared), which is the main remaining ambiguity for a tool with zero required params.

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?

Specific verb+resource ("Update the user's profile") that clearly pairs with the sibling get_profile as the write half of a read/write pair. It names the key sub-resources it mutates (fields, people, removePeople), letting an agent separate it from call-management siblings like save_call_note. It stops short of explicitly naming get_profile as its counterpart, so it is clear but not fully sibling-differentiated.

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?

"Update the user's profile with what you know about them" implies the context (persisting learned facts about the user), but there is no explicit when-to-use/when-not or mention of the read alternative get_profile. The removePeople clause hints at cleanup usage but does not state a condition for reaching for it.

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

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

Annotations only cover readOnly/openWorld; the description adds substantive behavior beyond them: the polling contract, the live-following cursor protocol, the wake-on-new-speech semantics, the request-interception behavior when canDo is set, and the meaning of live.transcript speakers. This is rich, non-obvious operational context.

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-loads purpose and return contents before the live/request modes, so structure is sound. It is dense and contains some internal jargon ('speaker agent is Smitline'), which taxes readability, but nearly every clause conveys operational rules rather than filler.

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?

There is no output schema, so the description carries the burden of describing return values, and it does: outcome, summary, details, transcript, live.cursor, live.transcript, and live.requests fields (id, kind, text, askedBy, source). Combined with polling and escalation guidance, nothing essential is missing.

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 protocol-level meaning: 'since: "" the first time, then live.cursor from the last answer' and what only='requests' implies ('wake only for requests, without the transcript', 'Implies following live'). That is genuine value beyond the schema strings, though timeoutSeconds is not discussed.

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 and resource ('wait for a call to finish and return it with its result') and distinguishes it from get_call/check_call_brief by emphasizing the blocking wait. It also enumerates the return contents, so an agent knows exactly what this tool yields versus siblings.

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?

Explicit when-to-call-again ('if status is not completed, failed, or canceled, call again'), when to switch tools ('send_call_instruction only when you know something the call needs, or end_call if it goes wrong; otherwise keep waiting'), and a special mode for long meetings via only='requests'. Alternatives in the sibling set are named directly.

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