KaiCalls

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

Annotations already cover idempotency, mutation, and open-world hints, and the description adds substantial context beyond them: the exact already_member and forwarding_loop error outcomes, the admin-secretary routing difference, and the refusal of the business's own forwarded line. This materially enriches what an agent knows before calling.

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?

Six sentences, each carrying distinct information (purpose, idempotency, role behavior, loop refusal, prerequisite, API mirror), with the purpose front-loaded. Slightly redundant with the schema's role description, and the API mirror sentence is marginal, but nothing is 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 4-parameter mutation tool with full schema coverage, a rich annotations block, and an output schema, the description covers purpose, edge-case error conditions, prerequisites, and role semantics. Return-value explanation is unnecessary given the output schema exists, and no gap an agent needs to invoke 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?

Schema coverage is 100%, so the baseline is 3; the schema already documents the role enum semantics and phone format. The description adds one genuinely parameter-level fact — that the business's forwarded office line is refused for phone_number — but otherwise mostly restates role behavior already present in 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 states a specific verb ('Add'), a specific resource ('the phone system's team ring group'), and the operational goal (rings before Kai answers). It clearly differentiates from siblings like attach_number and set_owner_phone by scoping this tool to the ring-group membership action.

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 provides explicit context: it covers both teammates and owners/admins, notes idempotency behavior, and names the prerequisite set_up_phone_system. It stops short of explicitly contrasting with siblings (e.g., when to use set_owner_phone instead), so it lacks an exclusion-based routing statement.

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?

The description adds context about what the operation does (assigns existing number, optional routing) and mirrors the POST endpoint, but it doesn't explain the destructive implications indicated by destructiveHint=true. Annotations already carry some safety signals, but the description could say more about what changes or gets detached/replaced.

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: the main action, the key non-goal with alternatives, and the API mapping. No filler and every sentence contributes.

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 3-parameter mutation with an output schema, the description provides the key disambiguation from buy_number, states the registry requirement, and mirrors the API endpoint. It is sufficient for an agent to correctly select and invoke this tool, though a bit more detail on side effects would make it fully complete.

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%, so the schema already explains each parameter. The description reinforces that phone_number must already be in the registry pool, which adds a small amount of usage context over the schema but is mostly redundant with parameter descriptions.

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?

Description clearly states the tool's action: assigning an already-owned pool number to a business and optionally routing to an agent. It also differentiates from buy_number by saying it does NOT purchase a new number, distinguishing it from the closest sibling.

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 says when not to use it and points to alternatives: 'Does NOT purchase a new number — use search_available_numbers + buy_number for that.' This gives an agent clear routing between the related tools.

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?

The description adds critical behaviors well beyond what annotations indicate: it says the carrier bills immediately on approval, supplies caller-supplied authorization is insufficient, and emphasizes not to claim the purchase is complete while approval is pending. It states that existing entitlement and carrier reservation checks apply, giving a clear failure-mode expectation. This is valuable behavioral disclosure not present in annotations.

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 front-loaded with the key purpose, approval-gating status, and immediate consequence, which is excellent. The final 'Mirrors POST /api/v1/phone-numbers/purchase' sentence is perhaps a token technical detail that might be redundant, but the six-sentence structure is compact and informative without being overly verbose.

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 tool with high safety implications, approval gating, and several behavioral caveats, the description addresses the most crucial things an agent needs to know to invoke it correctly: it's approval-gated, how to handle the response, what never authorizes, and that existing checks apply. With the output schema present, there is no need to explain return values here, so the description is complete.

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 schema covers 100% of the 10 parameters with detailed descriptions, so the top-line description does not need to explain them. The description mentions caller-supplied fields (human_confirmed, dashboard_session, system_policy) only to state they never authorize, which slightly deepen the meaning of the authority parameter but mostly repeats what is already in the schema. 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?

The description clearly states the tool 'Request a real phone-number purchase' and immediately breaks the meaning of the name buy_number by signaling it is approval-gated, so it only prepares an owner-review request rather than authorizing an immediate purchase. This distinguishes it from a simple car-buying action and is distinguishable from sibling tools like request_extra_number, especially since the description describes a specific API flow and an explicit 'Mirrors POST /api/v1/phone-numbers/purchase' behavior.

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 clearly sets the context: use this tool to purchase a real number, and after invocation you must relay the stored request and review URL to the owner rather than treating the purchase as complete. It does not explicitly name when not to use this tool or alternative sibling tools (e.g., attach_number), but the approval-gated flow and the 'do not claim a number was purchased' instruction are strong usage guidance.

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 provide a strong behavioral profile: readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no additional behavioral context beyond saying 'Check', which is consistent with the annotations. It doesn't disclose potential quirks like whether the response is cached or live, but the annotation coverage lowers the burden.

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 a single, front-loaded sentence with zero wasted words. It states the verb, the target resource, and the parameter in one pass, making it easy to scan and understand.

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 low-complexity tool with one parameter, strong annotations, and an output schema, the description covers the essential selection and invocation context. It doesn't mention how to obtain a valid call_id or enumerate possible statuses, but those are secondary given the output schema and simple purpose.

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% and the schema already explains call_id as 'The call ID to check'. The description's 'by its ID' adds no quantitative or formatting detail beyond the schema, so the baseline score of 3 is appropriate.

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 ('Check'), a clear resource ('status of a call'), and the key discriminator ('by its ID'). This differentiates the tool from siblings like list_recent_calls, get_call_recording, and get_phone_system_status without requiring the agent to infer intent.

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 phrase 'by its ID' provides clear context for when to use this tool: when the agent has a specific call_id and needs that call's status. It doesn't explicitly name alternative tools or exclusions, but for a simple single-resource lookup the usage context is reasonably clear.

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 signal not read-only and idempotent true; the description adds genuinely useful behavior: approval-gating, that it does not claim customer coverage, that the number is not fully set up until forwarding/owner phone are verified. This goes beyond the flag values.

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?

Every sentence carries distinct information: approval flag, precondition + action, downstream effect, and caveat with related tools. 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?

The description covers approval state, prerequisites, side effects, and what it does NOT do (claim customer coverage). Given the output schema and annotations, most operation-level context is present; the main gap is richer parameter semantics.

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 very low (only source_phone is self-explanatory). The description clarifies the meaning of the choice values (forwarding/published_number/both/testing), but leaves key parameters like business_id, activation_session_id, idempotency_key, and authority unexplained. The description does not sufficiently compensate for the schema's gaps.

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 names the exact action ('save forwarding, published_number, both, or testing') and the concrete consequence ('unlocks the command center'). It is clear that this is a configuration/selection operation, not a validation step, and it distinguishes the tool from later verification steps.

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 a precondition ('after setup proof is complete'), warns about approval gating, and points to get_activation_status/set_owner_phone for verification. It does not explicitly say 'use this when X, otherwise use sibling Y,' but the guidance is sufficient for basic routing.

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 mutating/destructive/idempotent behavior; the description adds the governance context ('governed agent.patch broker') and claims safety, which are useful for an agent deciding to trust the call. It does not explicitly say that 'replace' overwrites an existing section or detail the review requirement, but the schema's authority field covers that.

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 the action, and every clause earns its place: purpose, governance path, and use cases. No redundant restating of title or 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?

For a complex 11-parameter tool with a rich schema and output schema, the description supplies the situational context and safety framing needed for selection. It could be more complete about approval/destructive behavior, but those details are already in the schema parameter descriptions.

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% and every parameter has a useful description (idempotency_key, authority caveat, business_id condition). The description adds only high-level examples of rule content, which is helpful but not necessary for parameter understanding.

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 names a precise action and target: 'add or replace a named operational rules section inside an agent inbound prompt,' and identifies the routing path ('agent.patch broker'). The listed use cases (handoffs, callback language, alert promises) make it clear this is not the generic update_agent_config sibling.

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?

'Use this for...' explicitly enumerates the intended scenarios and contrasts with 'round-tripping the whole prompt manually.' It does not state when to avoid it or name a specific alternative tool, so it falls short of full routing guidance.

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 signal write, idempotent, and destructive behavior, so the bar is lower. The description adds a useful caveat that saving does not prove provider delivery or owner receipt, with proof tracked separately. It does not, however, clarify what the destructive aspect means, such as whether existing recipients or rules are overwritten or merged.

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 with no filler. The first sentence states the operation clearly, and the second adds an important behavioral caveat. The structure is compact and 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?

The schema is thorough, output schema exists, and annotations cover safety traits. The description supplies the key caveat about lack of delivery proof, which is valuable. It would be more complete with explicit overwrite semantics or a why-to-use sentence, but the core information is present.

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%, so the baseline is 3. The description adds only high-level context by mentioning recipients and escalation rules, but the schema already documents each parameter in enough detail. No extra credit is warranted.

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 uses a specific verb ('Save') with a clear resource ('business-owned staff alert recipients and post-call escalation rules'). This clearly distinguishes the tool from notification/proof siblings by narrowing scope to staff alert configuration and escalation rules.

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 gives no explicit when-to-use guidance or alternative-routing instructions. The note that activation notification proof is tracked separately hints at a boundary with proof tools, but it does not tell the agent when to prefer this tool over siblings like confirm_notification_destination.

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 communicate idempotentHint and destructiveHint, so the description only needs to add context. It explains that entries feed send_link/send_sms and avoid exposing raw URLs, which is useful. However, it does not disclose what 'repair' overwrites or what destructive consequences may occur, leaving some ambiguity beyond the annotation flags.

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 written sentences with the core purpose front-loaded and the usage context in the second sentence. No filler or redundant restatement.

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?

The schema is thorough and an output schema exists, so the description does not need to restate return values. The description supplies the integration context and the trigger scenario. A small gap is that it does not mention the destructive overwrite behavior implied by 'repair', but annotations partially cover this.

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 input schema already provides rich descriptions for all parameters, including label, key, is_active, destination_url, and dry_run. With near-total schema coverage, the description adds little parameter-level meaning beyond the overall purpose.

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: 'Create or repair the business_links entries', then identifies the dependent tools (send_link/send_sms) and the use case. This clearly distinguishes the tool from its 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?

States exactly when to use the tool: when callers need booking, directions, cancellation, sister-location, or service-specific links texted without exposing raw URLs. It does not explicitly describe when not to use it, but the positive usage conditions are specific enough to guide selection.

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 mark this as a non-readOnly, destructive, idempotent operation. The description adds valuable behavior beyond that: approval is required, delivery is deferred until the inbound call artifact is ready, and saving settings alone is not delivery proof. No contradiction with annotations.

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 the most important approval-gating note and no filler. Each sentence adds a distinct fact: what is saved, when delivery starts, and what does not count as delivery proof.

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 annotations and an output schema present, the description covers the essential non-obvious semantics: approval, exact session scoping, async delivery trigger, and the delivery-proof caveat. It does not spell out every parameter, but the remaining gap is modest for a 6-parameter mutation with a rich schema.

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 0%, so the description must carry parameter meaning. It explains channel (sms/email) and destination, and partially covers activation_session_id via 'exact active activation session,' but it does not clarify idempotency_key, business_id, or the authority object.

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: 'Save the owner-approved SMS or email destination for the exact active activation session.' This clearly identifies what is being persisted and scopes it to a single session, distinguishing it from notification retry, sending, or alert configuration tools.

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: this is approval-gated and should be used to set the destination for the active session, not as proof of delivery. It does not explicitly name sibling alternatives such as retry_activation_notification or list when-not-to-use conditions, so it stops 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 (readOnlyHint=false, openWorldHint=true) already indicate a mutating, open-world operation. The description adds valuable behavioral context: every mutation is versioned and reversible via rollback_config, and it discloses that compliance features (AI-disclosure, consent handling) are automatically applied. It does not contradict annotations and enriches the safety profile beyond what annotations convey.

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 structured and efficient: it front-loads the core purpose in the first sentence, then adds versioning and compliance details in subsequent sentences. It avoids redundant phrasing and each sentence carries distinct information. It is slightly longer than strictly necessary but remains clear and well-organized.

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 an output schema present and annotations covering the basic safety profile, the description covers the essential context: it defines the agent concept, notes the versioning/reversibility mechanism, and highlights compliance behavior. It does not detail error handling or return values, but these are either covered by the output schema or less critical for an initial creation 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 100%, so the schema fully documents all 8 parameters. The description adds a few semantic hints (e.g., voice_catalog_id is 'preferred', the agent concept as a 'secretary'), but these are marginal and do not substantially supplement the schema. The baseline of 3 is appropriate given high coverage.

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 (create) and the resource (a KaiCalls agent) with a specific definition ('the secretary that answers this business’s calls'). It also names the endpoint it mirrors (POST /api/v1/agents) and enumerates the key configuration inputs (system prompt, greeting, voice, model), which distinguishes it from siblings like update_agent_config and list_agents.

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 the creation tool by mentioning 'Every subsequent mutation to this agent is versioned' and referencing rollback_config and history tools, but it does not explicitly state when to use this vs. alternatives (e.g., 'use update_agent_config for existing agents'). The context is clear but the guidance is implicit rather than directive.

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 declare readOnly=false, destructiveHint=true, and idempotent=false, but the description adds valuable specifics: launching queues calls for the orchestrator, TCPA/consent gating still applies at dial time, and an admin role is required. This goes beyond the annotations by explaining side effects and prerequisites.

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 two sentences with no filler. The core action is front-loaded ('Create an outbound call campaign...'), then the optional launch consequence and permission requirement are stated efficiently. Every sentence contributes.

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 tool with 7 parameters, nested objects, and an output schema, the description covers the essential behavior, side effects, and prerequisites. The output schema renders return-value explanation unnecessary. It lacks some explicit guidance on when to choose alternatives, but it is otherwise complete enough for an agent to invoke 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?

Schema description coverage is 100%, so the schema already documents all 7 parameters including the nested cadence_config object. The description does not add per-parameter detail beyond the schema, but it does clarify the high-level concepts (campaign = cadence + lead batch) and the purpose of the launch flag. This meets the baseline for high schema coverage.

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 and resource: 'Create an outbound call campaign' and clarifies its composition ('cadence + lead batch') and the optional launch behavior. This clearly separates it from sibling tools like list_campaigns or make_call, so an agent can identify the right tool from the name and description alone.

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 gives useful context about the launching behavior and the admin role requirement, which helps an agent decide when this tool is appropriate. However, it does not explicitly mention alternatives or state when NOT to use this tool (e.g., choosing make_call for an immediate one-off call instead of a campaign).

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 indicate idempotent, non-readonly, non-destructive, and open-world behavior. The description adds real value on top: idempotency-key mechanics, the human authorization step in Stripe, and the explicit warning that this tool never proves payment or phone activation. There is no contradiction with the annotations.

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 at five sentences, each earning its place: purpose and resource, required params, idempotency guidance, human authorization flow, and exact follow-up routing. Front-loading the purpose minimizes the cognitive cost for the agent.

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 state-changing checkout tool with no output schema, the description does a solid job: it names all required inputs, the owner-authorization step, the follow-up tool, and the caveat about payment proof. A minor gap is that it does not detail what fields the response will contain besides session_id and the link, but the agent has enough to invoke and verify 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?

Schema description coverage is 0%, so the description must compensate. It gives meaningful semantics for idempotency_key (durable, retry pattern, new key needed for plan change) and plan_id (current plan from list_plans), but it only name-drops business_id without explaining its meaning or source, leaving a gap for agents.

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 clear verb and resource: 'Create or resume an owner-bound hosted Stripe checkout for a current plan from list_plans.' It also distinguishes this tool from nearby siblings like get_checkout_status by naming the follow-up tool explicitly, and it clarifies the plan source.

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 provides direct usage conditions: use a current plan from list_plans, reuse the idempotency key for retries, and change the key when changing plans. It also explicitly says when not to use this tool for payment proof and routes to get_checkout_status with the returned session_id.

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 destructive and idempotent behavior, so the description does not need to repeat those. It adds 'by ID' and the DELETE endpoint mapping, which is useful but does not reveal additional consequences like permanence or side effects beyond what annotations provide.

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 two short sentences, front-loaded with the core action, and includes a useful API reference without redundancy. Excellent conciseness.

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 the output schema present, annotations covering destructiveness/idempotency, and a clear parameter schema, the description is largely complete for a simple delete operation. It could mention permanence or downstream effects, but 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?

The schema covers 100% of the parameters with clear descriptionsyk. The description adds no extra parameter semantics beyond confirming that the removal is by ID.

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 ('Remove a business outbound webhook by ID') and reinforces it with the HTTP DELETE mapping. This makes the tool’s purpose unmistakable and distinguishes it from set_webhook and get_webhook.

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 when to use the tool (when removing a webhook by ID), but it does not explicitly state when not to use it or contrast it with alternatives like set_webhook. The guidance is adequate but not explicit.

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 and idempotentHint=true. The description adds context by explaining the result (number returns to the unassigned registry pool) and the HTTP semantics (DELETE /api/v1/phone-numbers), which is helpful and does not contradict annotations.

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, the first conveys the core action and result, the second a precise API reference. No filler; front-loaded and 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 simple two-parameter tool with an output schema and strong annotations, this description covers the purpose, resource, and outcome. It is sufficiently complete for an agent to invoke 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?

Schema description coverage is 100%, so both parameters (business_id and phone_number) carry full descriptions in the schema. The tool description adds no extra meaning to them, and with baseline 3, the schema does the work.

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: 'Release a phone number from a business back to the unassigned registry pool.' It also adds the REST mirror, which reinforces the exact action and helps distinguish it from attach_number/buy_number.

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 action itself implies usage: when you need to release a number. But there is no explicit guidance about when not to use it, no mention of alternatives like attach_number or buy_number, and no exclusions or conditions stated.

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 destructiveHint=false, but the description adds valuable behavioral context beyond that: it clarifies the tool cannot mutate proof state, describes what it returns, and warns against misinterpreting proof state as full setup. This directly aids the agent in acting correctly without contradicting the annotations.

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 two sentences, front-loaded with the core purpose and return contents, and ends with a concise critical caution. There is no filler or redundancy; 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?

For a read-only tool with no required parameters and an output schema provided, the description adequately covers purpose, return contents, and interpretation caveats. It does not mention potential errors or prerequisites, but given the tool's simplicity and the presence of an output schema, nothing essential is missing. Slight deduction for not addressing error conditions, which are often relevant in practice.

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%, so every parameter (business_id, oauth_transaction_id, activation_session_id, origin_conversation_id, receipt_idempotency_key) is already documented in the input schema. The description does not add extra parameter-level semantics; it only adds general behavioral context. Baseline 3 is appropriate because the schema carries the full parameter load.

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 ('Read') and a precise resource ('persisted proof-first activation status for one accessible business'). It clearly differentiates from siblings like get_setup_recovery_status or get_phone_system_status by specifying the return contents (masked evidence, next action, unlock state). The purpose is unambiguous and actionable.

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 gives explicit context on how to interpret results ('do not report the line as live/working on the strength of proof state alone') and notes a limitation ('It cannot assert or advance proof'). However, it does not name a specific alternative tool or explicitly state when to prefer this over a sibling; the usage guidance is implicit rather than comparative.

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?

The annotations already carry the safety profile (readOnlyHint=true, idempotent, non-destructive), so the description only needs to add behavior beyond that. It adds the time-window concept and the dashboard-summary scope, but nothing extra about rate limits, caching, or data freshness—acceptable when annotations already cover safety.

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 tightly worded sentence front-loads the action and resource, then enumerates the included metrics in a clear parenthetical. There is zero filler or redundancy.

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?

An output schema is present, and the description succinctly states what the tool returns (a dashboard summary with listed metrics) and exposes the time-window semantics. Combined with the schema's param and returned structure, nothing needed for correct invocation 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 description coverage is 100%, with the single parameter 'days' fully documented (min, max, default). The description's phrase 'recent time window' merely reinforces the schema without adding new constraints or behavioral rules, so 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?

The description states a specific verb and resource: 'Get a dashboard summary' and enumerates the exact metrics (lead counts, conversion rate, call volume, top agents, business outcomes). This distinguishes it from sibling tools like get_usage or list_recent_calls, which have different scopes and data shapes.

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: use when you want a high-level dashboard summary over a recent window. Though it doesn't explicitly exclude alternatives or name a sibling tool, the context is specific enough for an agent to select it over single-call or detailed-report tools.

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 this read-only, idempotent, and non-destructive, and the description adds substantial non-obvious behavioral detail: trial-specific constants, paid-plan mapping, raw vs weighted usage semantics, extra-line inclusion, and an error case when billing data is unavailable. This goes well beyond what the annotations and schema convey, and nothing contradicts the annotations.

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 main purpose is front-loaded in the first sentence, and every subsequent sentence earns its place by disambiguating the meaning of 'balance'—trial behavior, allowance counts, phone allowances, activation caveats, and error behavior. It is dense but not padded, and it avoids repeating annotation or schema 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?

For a zero-parameter, read-only endpoint with an output schema, the description supplies everything an agent needs: expected value semantics, the exact endpoint it mirrors, the error case, and misleading interpretations to avoid. No material selection or interpretation context 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?

The tool has zero parameters and the input schema documents that completely, so there is no parameter ambiguity. Per the baseline for zero-parameter tools, the description does not need to add parameter-level detail and introduces none.

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 ('Get plan terms and usage') and then defines what 'balance' means with concrete distinctions: trial vs paid plans, raw billable usage vs informational weighted count, and phone allowance including extra lines. It also states what a balance does not prove (activation or inbound routing), which helps separate it from adjacent concerns. However, it never names sibling tools like get_usage or list_plans, so differentiation is implicit rather than explicit.

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 gives useful contextual guidance: no-card trials report fixed minutes and zero price, paid plans report mapped price and billing-cycle usage, and only the raw billable call count should be treated as allowance consumption. It also warns that a balance does not prove activation or inbound routing, providing a when-not cue. It does not explicitly name alternatives or say 'use get_usage for detailed call records', so routing guidance is contextual but not fully explicit.

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, idempotentHint=true, destructiveHint=false; the description reinforces this with 'Read back' and 'nothing is created twice.' It adds a little context but does not disclose anything beyond the annotation safety 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?

Front-loaded with the core read-back purposeable, then a single routing sentence. 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?

Given the low complexity, the presence of an output schema, and the annotations' safety profile, the description says enough about what data is returned and when to call the tool. No critical gap for selection or invocation.

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?

One parameter with 100% schema coverage. The description adds no parameter-level detail; the schema already documents the default behavior, 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?

The description uses a specific verb (

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?

States a clear trigger condition: use this first when someone wants a business number that answers missed calls, so nothing is created twice. It does not name alternatives or exclusions, so it stops short of a full when-to-use/when-not-to-use guide.

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, idempotent, and non-destructive behavior. The description adds that the tool returns a 'real call recording URL' rather than audio content itself, which is useful context. It does not mention URL expiration, access restrictions, or whether the recording is always available, but annotations cover the safety 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?

A single, focused sentence that explains both what the tool does and why it matters. No filler, front-loaded with the key purpose.

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 simple one-parameter read-only lookup with an output schema and clear annotations, the description is sufficient. It could mention URL expiration or auth requirements, but those are not critical for selection or invocation.

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 parameter call_id is already fully described in the schema. The description adds no additional meaning about the parameter beyond its existence, so it meets the baseline without providing extra value.

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 ('Get'), the resource ('call recording URL'), and the purpose ('so reviewers can listen to the voice/audio'). It also differentiates from get_transcript by emphasizing audio over transcript.

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 when to use this tool: when reviewers need the actual voice/audio rather than the transcript, which differentiates it from the sibling get_transcript. However, it does not explicitly state when not to use it or name the alternative directly, so it falls just short of full guidance.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description goes beyond annotations by explaining the data lineage (where the audit entries come from, including the phone tool) and stating that the changes are reversible through rollback_config, which implies a non-destructive read view. This adds meaningful behavioral context without contradicting the annotations.

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 compact at two sentences, begins with the core result details, and packs the source, the covered mutations, the relationship to the voice tool, and the rollback capability into one dense block. No filler or redundancy. Each 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?

Given the output schema exists, the description does not need to replicate return formats. It successfully covers the purpose, data fields, source store, provenance, possible callers, and even a related rollback sibling. Nothing critical for correct invocation is missing: an agent would know what it reads, why it exists, and how to use it in context.

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%; both agent_id and limit are fully described in the input schema. The description does not add extra semantics for the parameters themselves, only reasserts 'recent' and 'limit' indirectly via 'recent' in the first sentence. Since the schema carries the full parameter burden, baseline 3 is appropriate.

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 by stating the specific resource ('agent's recent config-change audit trail') and enumerates the exact fields returned (change_type, change_source, old/new value, timestamp). It places the tool at admin_change_history and connects it to the same record read by the admin_get_change_history voice tool, so the purpose is unambiguous even before looking at 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 description clearly indicates this tool is appropriate for inspecting config-change history and explicitly explains that every mutation made through named tools (update_agent_config, configure_agent_business_rules, the admin call-in secretary, the dashboard) is logged here. It also notes that these changes are reversible with rollback_config, which gives the agent a reason to invoke this tool. It does not explicitly exclude alternatives such as list_config_versions, but the context is strong enough for correct selection.

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 mark read-only, idempotent, non-destructive. Description adds value: ownership requirement, 'confirmed billing does not prove activation' caveat, and explicit statement that it never mutates checkout/provisioning state. No contradictions with annotations.

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, front-loaded with the core read operation, then prerequisites, caveat, and side-effect disclaimer. No filler or repetition of schema/annotations.

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?

Covers ownership requirement, parameter provenance, semantic caveat about what billing does not prove, and explicit non-creation/non-retry behavior. Output schema exists, so return values need no elaboration.

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 has 0% description coverage)Skip, so description must carry the semantic weight. It explains that both parameters are required, business_id is the owned business, and session_id comes from checkout. Could specify formats/sources further, but enough for an agent to invoke correctly.

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?

Clear verb ('Read') + specific object ('Stripe-verified subscription checkout receipt') + ownership scoping ('for a business you own'), and immediately distinguishes itself from get_activation_status. No ambiguity about what this tool does.

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 prerequisites ('business_id and session_id from checkout'), states what the result does NOT prove, points to the correct alternative tool (get_activation_status), and clarifies out-of-scope behavior ('never creates checkout or retries provisioning').

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the endpoint mirror, which is minor context but not substantial behavioral detail beyond annotations.

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 concise sentences, front-loaded with the core purpose and no wasted words. The endpoint mirror is a useful supplementary detail that 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?

For a single-parameter read-only fetch with a full output schema, the description plus annotations cover what an agent needs. There are no missing prerequisites, side effects, or routing details required for correct invocation.

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%, so the single parameter conversation_id is already well documented. The description's mention of 'by ID' reinforces but does not add meaningful new semantics 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?

The description states a specific verb and resource: 'Get a single SMS conversation thread by ID.' This clearly differentiates it from sibling tools like list_conversations or list_sms_messages, which handle broader listing operations.

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 makes clear this tool is for fetching one conversation by ID, which implies the correct context. It does not explicitly name alternatives or state when not to use it, but the singular scope is clear enough for an agent to route appropriately.

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 idempotentHint=true, so the read-only nature is known. The description adds behavioral context about unknown outcomes: 'Unknown checkout or provider outcomes retain the original request and number,' which is valuable beyond annotations. It also reinforces the non-destructive intent with 'never start a replacement purchase.'

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 three sentences with no wasted words. It front-loads the core purpose, then adds a critical behavioral note. Every sentence contributes meaningful information, and the structure is clear and scannable.

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 simple read tool with two parameters and no output schema, the description adequately covers what the tool does and a key behavioral nuance. It hints at distinct aspects (billing, assignment, activation) but does not detail the response format or enumerate possible statuses. Given the tool's simplicity and annotations covering safety, it is reasonably complete but could be more explicit about return content.

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 0%, so the description must compensate for parameter meaning. The description does not explain request_id or business_id beyond their obvious names, and it doesn't clarify their format or relationship. The names are self-explanatory, but no additional semantic value is provided, leaving the agent to infer.

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 ('Read an owner-authorized extra-number request') and clarifies the scope by noting 'Billing, assignment and live activation are distinct,' which differentiates it from related status tools. It also explicitly warns against starting a replacement purchase, distinguishing it from purchase/request actions.

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 provides clear guidance on when not to use this tool ('never start a replacement purchase') and implies that unknown outcomes should be checked here rather than initiating a new purchase. However, it does not explicitly name alternative tools like get_checkout_status or get_activation_status, so usage context is clear but lacks explicit exclusions.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minor context about return content but does not disclose additional behavioral details such as not-found behavior or freshness of the score.

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 sentence that is fully informative, front-loaded with the action and resource, and contains no filler or repetition.

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 simple single-ID read operation with a full output schema and safety annotations, the description is complete. Nothing an agent needs to call this tool 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?

Schema description coverage is 100%, so the parameter is already documented as 'The lead ID to fetch'. The description adds no new parameter-level meaning beyond reinforcing that the fetch is by ID.

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 ('Get') and a specific resource ('full details for a single lead by ID'), and distinguishes it from list_leads by indicating this is for one lead. The mention of the latest AI lead score and explanation adds useful specificity.

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 clearly implies usage when a lead_id is known and full detail is needed, and the singular wording contrasts with list_leads for bulk retrieval. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to choose correctly.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description's word 'Audit' reinforces this and adds useful context about when the read-only behavior matters, but it does not disclose additional behavioral traits such as authentication needs, rate limits, or side-effect details.

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 a single, well-organized sentence that front-loads the action and scope, then uses a concise list to specify the audited components. There is no filler or redundant repetition of the title or 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?

For a read-only tool with one optional parameter, clear schema coverage, and an output schema, the description covers the operational purpose and scope completely. An agent has enough information to decide when to call it and what it will return.

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 description does not discuss the business_id parameter, but the input schema provides 100% coverage with a clear explanation: 'Business ID (optional, defaults to first accessible business)'. With full schema coverage, the baseline of 3 applies because the schema carries the parameter-semantics burden.

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 uses a specific verb ('Audit') and a clear resource ('business-level operational setup'), then enumerates exactly what is included: staff alert recipients, alert flags, escalation rules, textable send-link entries, and agent voice/model/greeting metadata. This makes it easy to distinguish from sibling configuration tools like configure_staff_alerts or configure_textable_links.

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 gives a clear usage context: this is 'required before changing a live account', so an agent knows when to call it. It does not explicitly name alternatives or say when not to use it, but the audit-versus-configure contrast with sibling tools is strongly implied.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: data is 'reconciled from the phone system on every call' (indicating freshness/accuracy), and it explicitly discloses the 409 error condition when the hosted phone system is not set up. This goes beyond the annotations.

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 with no waste. The core purpose is front-loaded, followed by a data-freshness note and an error condition. 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?

The tool has an output schema, so return values don't need explanation. The description covers purpose, data source, and a key error condition. It could mention pagination or rate limits, but for a simple read-only tool with one optional parameter, this is nearly complete.

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%, so the schema already documents the single business_id parameter. The description doesn't add parameter-specific details beyond what the schema provides, but with only one parameter and full coverage, the baseline 3 is appropriate.

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 tool reads how calls ring on the business's hosted phone system, specifying the exact details it returns (which cells and desk phones ring, duration, after-hours routing to AI receptionist). It distinguishes itself from siblings like get_phone_system_status and update_phone_flow by focusing on the read-only flow behavior.

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 when to use this tool: when you need to understand call routing behavior on the hosted phone system. It mentions the mirror of POST /api/v1/phone-system action=get_flow, which provides an API-level reference. However, it doesn't explicitly state when not to use it or name alternative tools for related but different queries (e.g., get_phone_system_status for overall system health).

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 destructiveHint=false. The description adds valuable context: dial plan ids are 'never secrets' and next_step is 'the one line to relay to the owner.' No contradiction with annotations; adds behavioral nuance beyond the structured hints.

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 efficient sentences. Front-loaded with the primary purpose, then enumerates returned fields, then gives usage contexts. No padding or repetition; every clause contributes.

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 output schema exists, the description appropriately focuses on purpose and use cases. For a single-parameter read-only tool with clear annotations, nothing essential is missing; it even clarifies the 'never secrets' 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 covers business_id at 100% with a clear description. The tool description does not mention the parameter, but since schema coverage is high, the description does not need to compensate. Baseline 3 is appropriate.

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+resource: read the phone system status. Lists exact contents (Kai's extension, ring group, dial plan ids, phone-system line, next_step) which distinguishes it from sibling get_* tools like get_activation_status or get_phone_flow. Clear, non-tautological purpose.

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 states when to use it: to confirm a set_up_phone_system run or before adding team phones. Provides clear context but does not mention alternatives or when not to use it, which is typical for a read-only status tool.

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 show read-only and idempotent. The description adds non-obvious behavior: running requests are never automatically stolen (even stale ones) and a ready receipt does not prove live activation. No contradiction with annotations.

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 concise sentences, front-loaded with the core purpose, followed by two high-signal caveats.

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 a simple read tool with rich annotations stan, the description covers scoping and behavioral caveats welltwenty, but without an output schema or return-shape statement, an agent is left guessing what the response contains. Still fairly complete with name/title.

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?

With 0% schema description coverage, the description must supply parameter meaning. It clarifies the two parameters are a lookup key by 'business and idempotency key,' but it doesn't explain their format, validity, or behavior when matches are absent.

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 uses a specific verb ('Read'), names the resource ('owner-authorized setup recovery request'), and specifies the exact lookup keys ('business and idempotency key'). It clearly distinguishes this from sibling status tools by naming the unique 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 owner-authorized qualifier gives some context on when the tool applies, but there is no explicit guidance on when to choose this over alternative get_* tools. The usage context is implied rather than stated.

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 mark it readOnly, idempotent, and non-destructiveikuha. The description adds that it returns both a transcript and a summary screporting the completed-call requirement, which is useful behavioral context beyond the annotations.

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 clear, front-loaded sentence states exactly what the tool does without wasted 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?

With a single documented parameter, an output schema, and annotations covering side effects, the description is nearly complete. It could explicitly note what happens if the call is not completed, but the 'completed call' qualifier conveys the main constraint.

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 only parameter is fully described in the schema (100% coverage), so the tool description does not need to add extra meaning. Baseline 3 is appropriate.

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 uses a specific verb and resource: 'Get the transcript and summary of a completed call.' It clearly identifies both the payload and the precondition (completed call), which distinguishes it from sibling tools like check_call_status or get_usage.

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 narrows usage to completed calls but does not explicitly mention alternatives, exclusions, or when not to use it. The 'completed call' qualifier gives context, yet an agent isn't told what to use for in-progress calls or where this fits among the many sibling tools.

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 convey readOnly, idempotent, and non-destructive behavior. The description adds the 'caller's account' scoping and the REST endpoint mirror, but it does not mention result ordering, pagination behavior, default time window, or whether cost is estimated or final.

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 concise sentences deliver the core purpose and endpoint mapping without waste. The key action and resource are front-loaded, and the mirror reference adds useful context without bloating the text.

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 read-only, optional-parameter list tool with a full input schema and an output schema, the description covers the essential context. Minor gaps remain around default date range and when to choose this over similar observability/analytics tools, but these are not critical for invoking 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?

Schema description coverage is 100%, so the parameters start, end, and limit are already documented in the schema. The description adds no parameter-specific meaning beyond framing the resource as usage events, so the baseline 3 is appropriate.

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 a specific verb ('List'), resource ('recent API usage events'), and useful attributes (endpoint, method, status code, cost), scoped to the caller's account. It is unambiguous, though it does not explicitly differentiate from sibling tools like get_analytics or list_observability_events.

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?

There is no guidance on when to use this tool versus alternatives such as get_analytics, list_observability_events, or list_tool_execution_logs. The phrase 'Mirrors GET /api/v1/usage' identifies the backing endpoint but provides no selection criteria or exclusions.

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, idempotentHint, and destructiveHint, which cover the safety profile. The description adds useful context by mentioning that it returns supported event types, and the 'Mirrors GET /api/v1/webhooks' line suggests a standard read-only API response. This goes beyond the annotations without contradicting them.

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 a single, dense sentence that leads with the core function ('List the configured outbound webhook(s)'), includes the scope and a key detail (event types), and ends with a helpful API reference. No wasted words.

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 tool's simplicity (0 required params, 1 optional param with full schema coverage, output schema present, and annotations covering safety), the description is complete. An agent can understand what the tool returns and the business scope, and the annotation and schema cover the rest.

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?

With 100% schema description coverage, the single business_id parameter is already fully documented, including the nuance that it is optional when the token accesses one business. The description adds no additional parameter meaning beyond the schema, so the baseline 3 is appropriate.

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 tool lists configured outbound webhooks for a business, includes supported event types, and explicitly mirrors GET /api/v1/webhooks. This distinguishes it clearly from sibling tools like set_webhook and delete_webhook, giving a specific 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 the tool is for reading webhook configurations but does not explicitly state when to use it versus alternatives like set_webhook or delete_webhook. There is no mention of exclusions or when not to use this tool, leaving the agent to infer from the 'List' and read-only hints.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the account-scoped behavior and the business-filtering hint, but it does not disclose pagination behavior beyond what the schema already provides. It does not contradict annotations.

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 with no filler. The core action and scope are front-loaded, and the use-case guidance is a single clause. Every word 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?

For a read-only list tool with a rich output schema, full parameter documentation, and annotations covering safety, the description is nearly complete. The only minor gap is that it doesn't explicitly state when not to use it or mention pagination behavior, but those are covered by the schema and the tool's simplicity.

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%, so the schema already documents all three parameters (limit, offset, business_id). The description adds a small amount of context by mentioning the business filter implicitly ('this business'), but it does not add meaning beyond the schema. Baseline 3 is appropriate.

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 uses a specific verb ('List') and resource ('KaiCalls agents on the authenticated account'), and it distinguishes itself from sibling tools by clarifying scope (account-level listing). It also adds a practical use case ('before setting anything up, to see whether this business already has a secretary answering its calls'), which makes the tool's purpose immediately clear.

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 gives a clear context for when to use the tool ('before setting anything up') and what question it answers ('whether this business already has a secretary answering its calls'). It does not explicitly name alternatives or exclusions, but the context is strong enough for an agent to select it over siblings like list_numbers or list_recent_calls.

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, idempotentHint, and destructiveHint, so the description does not need to repeat those. It adds useful behavioral scope ('for the authenticated business') and the 'outbound' qualifier, giving the agent important access context without contradicting annotations.

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 sentence delivers the full purpose without filler or repetition. The differentiating qualifiers 'outbound' and 'authenticated business' are front-loaded, making the description efficient and easy to scan.

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?

The input schema, output schema, and annotations already cover most needed details. It would be slightly stronger if it supplied allowed status values or explicitly directed users to a sibling tool, but for a simple, optional-parameter listing operation the description is adequate.

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%, so the schema already explains limit, offset, and status. The description adds no additional parameter semantics, which matches the baseline score of 3 when structured data carries the parameter documentation.

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 ('List') and a well-defined resource ('outbound call campaigns') scoped to the authenticated business. This clearly distinguishes it from sibling tools like create_campaign, list_agents, or list_numbers without relying on the tool name alone.

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 context is clear—an agent should use this when listing the current business's outbound call campaigns. However, it does not explicitly name alternatives or state when not to use it, though the read-only listing nature makes the intent obvious.

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 cover read-only/idempotent safety, and the description adds genuine behavioral detail: results are hashed and redacted, version history includes rollback lineage, and passing version returns a full redacted config_snapshot. No contradiction with annotations.

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 terse sentences front-load the core operation, then explain the alternate mode and endpoint correspondence. 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?

With an output schema and read-only/idempotent annotations present, the description covers the key behaviors: history listing, snapshot retrieval, and hashing/redaction. No critical missing info for a tool this simple.

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 describes all parameters (100% coverage), so baseline is 3. The description adds meaning by explaining the version parameter's effect (return single full snapshot vs list) and noting the data is hashed/redacted.

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 action and resource: 'List an agent's hashed, redacted assistant config version history (rollback lineage included).' This distinguishes it from every sibling tool, and the added behavior for single-version fetch is explicit.

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?

Clearly describes what the tool does and the conditional use of the version parameter to fetch a single config snapshot. It doesn't explicitly name alternatives or exclusions, but the context is clear enough that an agent knows when to call 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 already cover read-only, idempotency, and non-destructive behavior, so the bar for adding behavioral context is lower. The description adds useful context about ordering ('most recent first') and the scope ('authenticated business'), but it does not go into pagination or return details. This is acceptable given the output schema and annotations.

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 with no wasted words. The key action and scope are front-loaded, and the API mirror line provides a useful reference without padding. 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?

For a simple read-only list tool with one optional parameter and an output schema, the description is nearly complete. It specifies the resource, scope, and ordering, and the complexity is low, so little more is required. A slight improvement would be to mention that this returns threads, not individual messages, but that is already implied by 'threads' and the sibling list.

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% for the single optional limit parameter, which is fully documented with min/max and default. The description adds nothing beyond the schema, so a baseline of 3 is appropriate.

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 (list), the resource (SMS conversation threads), and the scope (authenticated business, most recent first). It also distinguishes itself from siblings like list_sms_messages and get_conversation by specifying 'threads' and 'counterparty timeline metadata', and maps to a precise API endpoint.

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 provides no guidance on when to use this tool versus alternatives such as get_conversation or list_sms_messages. It simply states what the tool does without any conditions, exclusions, or references to sibling tools, leaving the agent to infer selection criteria.

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?

The annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context beyond that by clarifying that 'evals' are canned mock-conversation scenarios and by noting the API mirror ('GET /api/v1/evals'), which helps the agent understand the nature and scope of the operation.

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 contain the essential purpose, scope, and API correspondence with no filler. The primary action and resource are front-loaded, making the intent immediately clear.

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 simple, optional-filter list tool, the description plus schema and annotations cover what an agent needs: the resource type, the filtering behavior, and the safety profile. The output schema is present, so return-value documentation is handled structurally. It could mention pagination or permissions, but these are minor against the low complexity.

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 for the single parameter is 100%, so the baseline is 3. The description adds meaningful nuance by stating that omitting agent_id returns all accessible agents, which the schema's 'optional' wording does not fully convey. This enriches the parameter semantics beyond the schema alone.

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 uses a specific verb ('List') and a specific resource ('canned mock-conversation eval scenarios'), with clear scoping ('for an agent (or all accessible agents)'). This distinguishes it from siblings like run_eval, which would execute rather than list evals.

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 clearly implies when to use the tool: when you need to view predefined eval scenarios rather than run them. However, it does not explicitly name run_eval as the alternative or state when-not-to-use, leaving the routing to inference from the sibling list.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description carries little additional safety burden. 'Mirrors GET /api/v1/knowledge' adds an HTTP-method mapping but no further behavioral detail such as pagination or result limits.

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 with no filler; the main action is front-loaded and the API mirror reference provides a useful anchor without redundancy.

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 simple, read-only list operation with all parameters documented in the schema, an output schema present, and safety annotations covering side effects, the description is complete enough. Nothing essential to calling the tool 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?

Schema description coverage is 100%, with each parameter already explained in the input schema. The description adds no extra meaning to query, category, or business_id beyond what is in the schema, so the baseline score of 3 is appropriate.

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 names a specific verb ('List') and resource ('agent knowledge base entries for a business'), and the 'Mirrors GET /api/v1/knowledge' line anchors it to a concrete API operation. It is clear enough to distinguish from siblings like upsert_knowledge, though it does not explicitly name the alternative.

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 tool's purpose makes it obvious it should be used when listing knowledge entries, but the description gives no explicit when-to-use/when-not-to-use guidance or alternatives. Context is clear but exclusions are absent, leaving usage to be implied rather than stated.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable context by noting it includes the latest AI lead score when available, which is beyond the structured annotations and informs the agent about data content. No contradictions with annotations.

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 concise sentences with zero filler. The primary purpose is stated first, followed by a single highlight (AI lead score) and a note on filters. Perfectly front-loaded and every word 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?

Given the tool has an output schema and annotations covering read-only/idempotent behavior, the description is sufficient. It covers scope and filters, and the schema documents pagination. It doesn't mention ordering or edge cases, but with the output schema present and no nested objects, nothing essential is missing for correct invocation.

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% and each parameter already has a clear description (limit, offset, source, status, agent_id). The tool description adds only a grouping phrase ('optional status/source/agent filters') which restates the schema without adding new meaning. Baseline 3 is appropriate since the schema handles the semantic load.

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 ('List') and a concrete resource ('leads') scoped to the authenticated business, and it names the optional filters (status/source/agent). It clearly distinguishes from the sibling 'get_lead' (single lookup) and 'upsert_lead' (create/update) without needing to open their 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?

The description makes clear it lists multiple leads for the current business, which implies it is for browsing/filtering rather than fetching a single lead. It doesn't explicitly name alternatives or state when not to use it, but the context is unambiguous enough that an agent would not confuse it with get_lead or upsert_lead.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuine behavioral nuance beyond annotations: the assignment-vs-activation caveat, the requirement that an owner phone be on file, and forwarding verification. It also discloses the API correspondence ('Mirrors GET /api/v1/numbers'). No contradiction with annotations.

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, with the core purpose front-loaded and every subsequent clause earning its place — the caveats prevent misinterpretation and the sibling references guide follow-up. The second sentence is dense, but each clause is non-obvious and operationally relevant. Slightly more verbose than strictly necessary, but no waste.

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 low-complexity tool (1 optional filter param, full annotations, output schema present), this is nearly complete. The main risks — misreading assignment as activation and skipping owner-phone setup — are explicitly addressed. Minor omissions like pagination or ordering behavior are acceptable given the output schema and the tool's simplicity.

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% — the single optional parameter business_id is already documented in the schema with its filtering meaning. The description's 'accessible business(es)' phrasing loosely aligns with the param but adds no syntax, format, or semantic detail beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter burden.

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+scope: 'List phone numbers assigned to the accessible business(es), with capability and compliance flags.' This clearly distinguishes it from sibling tools like search_available_numbers (unassigned numbers), get_activation_status (setup state), and get_extra_number_status (status of a specific number). An agent can tell exactly what this tool returns.

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 provides clear context on when this tool's data is insufficient: 'Assignment does not prove inbound routing, activation, or customer coverage' and explicitly routes the agent to get_activation_status / set_owner_phone for full setup verification. It doesn't formally name an exclusion for searching unassigned numbers, but the 'assigned to' scope plus the caveats make the boundary obvious.

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?

Beyond the readOnly/idempotent/destructive annotations, the description adds meaningful behavior: events are 'compact', integration-delivery attempts are 'redacted', and pagination is 'bounded keyset'. These details tell the agent about response scope and paging mechanics, which annotations alone do not convey.

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 tight sentences: the first states the core purpose and scope, the second adds endpoint equivalence and pagination behavior. No filler or redundancy; key 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?

For a 17-parameter tool with no required params and a rich schema plus output schema, the description supplies the essential orientation: business scope, redaction, and paging behavior. It does not enumerate filter grouping, but the 82% schema coverage and output schema fill most practical gaps.

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 82%, so the schema already carries most parameter meaning; the baseline of 3 applies. The description adds only a high-level 'business-scoped' and 'bounded keyset pagination' signal that corroborates the business_id and cursor/limit parameters without detailing them.

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-object pair—'List a business-scoped timeline of compact call-runtime events and redacted integration-delivery attempts'—which clearly identifies the resource and scope. The endpoint mirror (GET /api/v1/observability-events) reinforces that this is uniquely the observability-events listing tool among 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?

The description conveys that this is the right tool for reading business-scoped observability events, but it never states explicit when-to-use/when-not-to-use conditions or names alternative tools. Usage is implied by the event-domain vocabulary rather than stated as guidance.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the legacy scope and ledger-vs-aggregate semantic, but does not disclose pagination behavior or how status filtering behaves; this is acceptable but not additive beyond annotations.

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, each earning its place: scope, contrast with the aggregate endpoint, and API mirror. No filler; key scoping is 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?

Output schema and annotations cover return shape and safety, while the description adds the crucial domain context (legacy-only, ledger rather than aggregate). It does not mention default limit or status implications, but those are visible in the schema, leaving only a minor completeness gap.

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 20% (only business_id has a description), and the description does not compensate. From/to are only implicitly tied to 'per-period,' and limit/status are left unexplained. With five optional parameters, this is a notable gap.

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?

Description identifies a specific resource (billing_overage_charges ledger) and scope (legacy per-minute-overage tiers). It explicitly distinguishes this from the aggregate returned by get_balance, so an agent can tell it apart from sibling tools without inspecting 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?

States a clear legacy-only condition and contrasts with get_balance, which only returns an aggregate. This tells the agent when to use this tool and when to prefer a different one, with no 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 mark it read-only and idempotent, but the description adds behavioral specificity: it returns the canonical public catalog including monthly USD prices and allowances, and explicitly disclaims selection/checkout/billing effects.

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 with the core action front-loaded. No filler, no repetition of the tool name, and every clause adds 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?

For a zero-parameter, read-only list tool with an output schema available, this description is complete: it states what the agent will retrieve, the format/scope (monthly USD prices and allowances), and what will not happen.

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 has zero parameters, so there is no parameter ambiguity. The description adds useful context about the returned data (monthly USD prices and allowances), which is the baseline expectation for a parameterless catalog lookup.

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 and object: 'Read the canonical public KaiCalls plan catalog.' It also clarifies what the tool does not do (select a plan, create checkout, or change billing), distinguishing it clearly from action-oriented 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?

Provides clear read-only context and explicitly excludes side-effect actions like checkout creation and billing changes. It stops short of routing the agent to a specific sibling tool for those actions, so it is not a full 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 already provide readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Mirrors GET' only confirms read-only behavior. It does not add useful behavioral context such as pagination, authentication requirements, or response implications, but it also does not contradict the annotations.

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 with no filler: the first names the action and resource, the second maps it to the actual API endpoint. Every word contributes value and the main purpose is 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?

Combined with the full input schema, informative annotations, and output schema, the description is mostly sufficient for invocation. It lacks guidance on when to choose this tool over sibling mutations and does not mention pagination or return-value caveats, but these are secondary given the structured metadata.

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%, so the schema already documents all four parameters including the nuance around business_id. The description does not add parameter-specific meaning, but with full schema coverage the baseline score of 3 is appropriate.

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 the verb 'List' and the specific resource, 'a business's agent product catalog,' and reinforces it with 'Mirrors GET /api/v1/products.' This read-only retrieval framing clearly distinguishes it from the sibling upsert_product mutation tool and other list tools.

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?

No explicit when-to-use guidance or alternative routing is provided. Given many sibling list_* and upsert_* tools, an agent has no stated criteria for choosing this tool over alternatives such as upsert_product, though the read-only wording implies retrieval.

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 convey readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'recent' time scope and 'authenticated business' boundary, but it does not disclose ordering, time-window semantics, or pagination behavior beyond what the schema already provides.

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 a single front-loaded sentence with no filler or redundant restatement of the title. It communicates the core action and scope efficiently, earning 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?

For a simple list tool with fully documented parameters and an output schema, the description is mostly sufficient. However, it leaves 'recent' undefined and does not help the agent decide between this tool and sibling call-related tools, which creates a meaningful contextual gap.

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 every parameter documented (limit, offset, status, agent_id). The tool description adds no additional meaning to these parameters, so the baseline of 3 is appropriate.

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 uses a clear verb and resource: 'List recent calls for the authenticated business'. It distinguishes the tool from list_sms_messages, list_voicemails, and list_conversations by the resource type, but it does not define 'recent' or explicitly differentiate it from call-status or recording 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?

There is no guidance about when to use this tool versus related siblings like check_call_status, get_call_recording, or get_transcript. The description provides no alternatives, exclusions, or preconditions, leaving the agent to infer the appropriate context from the tool name alone.

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, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context by disclosing the dry_run -> notified -> (kept | applied | superseded) lifecycle and the per-period nature of the results. No contradictions with annotations.

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 tight and front-loaded, with an effective one-line purpose followed by useful lifecycle and API context. The 'Mirrors GET /api/v1/rightsize-recommendations' sentence is slightly redundant but still informative and not fluff.

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 a rich input schema, output schema, and strong read-only/idempotent annotations, the description provides enough behavioral framing: what is listed, the lifecycle, the filtering period, and the role of the tool. It does not explain optional filter defaults, but those are already visible in the schema.

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 17%, so the description carries extra responsibility. It adds 'per-period' meaning for the from/to filters and the lifecycle states align with status, but it does not explain the action enum, limit pagination, or business_id semantics beyond the minimal 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 description names a specific action and resource ('List ... auto-right-size decisions'), ties it to a concrete state lifecycle, and states the human-facing question it answers. It is clearly distinct from generic list_plans or list_subscription_history siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.