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?

Annotations declare destructive/openWorld/non-idempotent, and the description meaningfully adds to that: mandatory agency roles, client memberships and owner approvals, an explicit pre-approval preview step, idempotency-key reuse, and per-action scope requirements (agents:write, evals:write, sms:write). This is real operational context beyond the structured flags, though several statements are too abstract to act on ('Configuration, test proof, activation, collection and outcomes stay distinct').

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 dense and front-loaded with the authentication framing, and the preview/idempotency instruction earns its place. But it carries apparent shared boilerplate that does not apply to this tool (enrollment/installation, simulation, and care scope lines reference sibling domains), diluting the signal.

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 exists, so return values need not be described, and the auth/scope/approval context is covered. That said, for a destructive nine-action command tool, omitting any enumeration or disambiguation of the actions leaves a significant 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 0% and the schema is a complex oneOf over nine action variants with many sub-fields. The description compensates only marginally by naming idempotency-key reuse; it never explains the command actions, the meaning of amountCents/reason/document, or the union structure, so an agent still has to reverse-engineer 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?

Verb+resource are stated ('Manage billing-periods'), and the framing 'same strict authenticated service as the dashboard' narrows the domain. However, the description never enumerates the nine command actions (retry_collection, record_adjustment, set_plan, freeze_period, collect, etc.) that define what this tool actually does, leaving the purpose generic for a multi-action dispatcher.

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 partial guidance: 'Inspect the command schema, review exact previews before approval and reuse the same idempotency key' is a usable procedure, and the role/membership/approval requirements hint at prerequisites. But nothing tells the agent when to pick this tool over the billing-adjacent siblings (agency_care, agency_enrollments, agency_offers) or when an action is inappropriate.

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 annotations (destructiveHint=true, idempotentHint=false), it discloses the required permission scopes (agents:write, evals:write, sms:write), role/membership/owner-approval prerequisites, and the preview-before-approval safety flow. This is substantive context the annotations do not carry, though it leaves the actual mutation effects vague.

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 permission and prerequisite content is front-loaded usefully, but sentences like "Configuration, test proof, activation, collection and outcomes stay distinct" are cryptic and their value is unclear. Density is high with some filler that does not obviously earn 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?

An output schema exists so return values need not be described, and the auth/permission context is reasonably complete. But for a destructive tool with a complex nested input and 0% schema coverage, the parameter-level behavior is left entirely unaddressed.

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% and the nested command object (action enum, partnerId, installationId, milestones, expectedRevision, minimumDays) is unexplained. The description only gestures at "inspect the command schema" and the idempotency key, so it does not compensate for the coverage 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?

The verb is the vague "Manage" and the resource "care" is never defined, so an agent cannot tell what domain object this operates on. The action enum (preview_review, prepare_review, launch_review) is only hinted at via "review exact previews before approval," and nothing distinguishes it from siblings like agency_enrollments or agency_offers.

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 real procedural guidance (inspect the command schema, preview before approval, reuse the idempotency key, mandatory roles/memberships), which helps an agent execute correctly. However it never states when to choose this tool over alternatives, so the when-vs-which dimension is missing.

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 only give a coarse profile (destructive, non-idempotent, open-world). The description goes further, disclosing mandatory agency roles/client memberships/owner approvals, required scopes (agents:write, evals:write, sms:write), and the preview-before-approval convention that matters for a destructive tool. The remaining gap is that it never says which actions actually destroy data or whether revoke/rotate_owner_link are reversible.

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 purpose and the two most operative instructions (preview, idempotency key), so the ordering is sound. However, sentences like "Configuration, test proof, activation, collection and outcomes stay distinct" and "Bootstrap and owner self-service use verified dashboard sessions" are jargon-heavy and low-information, diluting an otherwise dense block.

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 exists, so return values need not be explained, and auth/permission coverage is genuinely good for a high-complexity mutation tool. What is missing is lifecycle coverage: nothing tells the agent how the actions sequence (preview → approval → enroll) or which actions are terminal versus intermediate, leaving the agent to reconstruct that from the schema alone.

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% and the command parameter is a deep oneOf, so the description carries a heavier burden. It does clarify the role of the idempotency key (reuse it) and tells the agent to inspect the command schema, but it adds nothing about the action discriminator or the per-action required fields. Partial compensation only.

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 "Manage enrollments" — a verb plus resource, but it never enumerates what management actually means for a tool whose schema dispatches across eleven distinct actions (create, save, preview, enroll, approve_owner, revoke, etc.). It also does not distinguish this tool from siblings like agency_installations or agency_offers, which sit in the same agency namespace. An agent can guess the domain but not the operation set.

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 real workflow guidance — inspect the command schema, review a preview before approval, reuse the idempotency key — and per-capability permission requirements are spelled out. But there is no explicit when-to-use-this-instead-of-a-sibling, and no guidance on which of the eleven actions to pick for a given situation. Usage is implied rather than routed.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true and readOnlyHint=false, and the description usefully adds the authorization prerequisites (current agency roles, client memberships, owner approvals) and per-family write scopes. It does not say what 'offboard', 'revoke_approval' or 'apply_update' actually destroy or whether they are reversible, so the destructive surface stays opaque. The instruction to reuse the idempotency key sits oddly against idempotentHint=false, though the explicit key parameter mitigates rather than contradicts it.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Length is moderate, but the opening sentence is vague scene-setting and 'Configuration, test proof, activation, collection and outcomes stay distinct' is opaque jargon that costs a sentence without telling an agent anything actionable. The genuinely useful content (auth requirements, scopes, preview-before-approve) is buried mid-paragraph.

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 exists, so return values needn't be explained, but for a destructive, multi-action, permission-gated tool the description omits the per-action semantics and the meaning of the required concurrency/fingerprint parameters. An agent still cannot tell what each command variant does or what guarantees apply after calling it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% against an eleven-variant oneOf with fields like expectedRevision, fingerprint, subjectHash, choices, updateId, sessionId and rollbackRevision. The description mentions the command schema and idempotency key but explains none of these fields, their formats, or the preview-then-approve sequencing between fingerprint and expectedRevision, so it does not compensate for the coverage 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?

The verb is generic ('Manage') but the resource (installations) and lifecycle stages (configuration, activation, collection, outcomes) are indicated, so the domain is inferable. However the description never enumerates or characterizes the action set (preview/approve/pause/offboard/apply_update) that the schema actually exposes, and it doesn't clearly separate this tool from siblings like agency_enrollments or agency_offers beyond a passing mention of scopes.

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 does prescribe a workflow: inspect the command schema, review exact previews before approval, reuse the same idempotency key, and it states which scope gates which action family. What is missing is any explicit 'use this instead of X' routing versus the many agency_* siblings, and no statement of when a given action (preview vs approve vs offboard) applies.

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 destructive=true, readOnly=false, so the safety profile is known; the description goes further and adds real operational context: per-domain permission requirements (agents:write for enrollment/installations, evals:write for simulations, sms:write for care), the mandatory role/membership/approval gate, the preview-before-approval workflow, and bootstrap/self-service via verified dashboard sessions. This is meaningful disclosure beyond the annotations. The one tension is 'reuse the same idempotency key' against idempotentHint=false, though that is a request-level mechanism rather than a strict contradiction.

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 opening sentence front-loads the tool's identity, and the permission-scope sentence is genuinely informative. But the paragraph is a run-on of comma-spliced clauses ('Configuration, test proof, activation, collection and outcomes stay distinct'), and phrases like 'the same strict authenticated service as the dashboard' add atmosphere rather than actionable content.

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 exists, so return values need no explanation, and the permission/prerequisite coverage is solid. But for a tool this complex (four action variants over a deeply nested command object), the description never enumerates the actions or the save-versus-publish boundary, so an agent still has to infer core workflow from 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 0%, so the description must compensate for the parameters, and it largely does not. It never explains the command oneOf variants (save/preview/publish/archive) nor the fields nested inside the draft object. The only parameter value it adds is the instruction to reuse the same idempotency key, and it explicitly defers the rest to 'inspect the command schema', leaving the agent to reverse-engineer the action semantics from 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 title and opening clause establish the resource (agency offers) and imply a lifecycle (save/preview/publish/archive), but the verb 'manage' is generic and the four actions are never named outright. The dense mid-sentence clause about 'configuration, test proof, activation, collection and outcomes' gestures at distinct stages without telling the agent what the tool actually does. It does not clearly differentiate itself from siblings like agency_care or agency_enrollments, which are only referenced obliquely via their permission scopes.

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 procedural guidance ('review exact previews before approval and reuse the same idempotency key') and stated prerequisites (current agency roles, assigned client memberships, owner approvals mandatory), which is more than most. However, it never says when to use this tool versus the sibling agency_* tools, nor which of the four actions applies in which situation.

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 destructiveHint=true and openWorldHint=true, but the description meaningfully adds the governance context: it runs through the same strict authenticated dashboard service, mandates current agency roles, client memberships and owner approvals, requires exact previews before approval, and tells the caller to reuse the same idempotency key. That is real behavioral value beyond the structured hints, though it stops short of stating what an update or revoke actually destroys.

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 six sentences and reasonably front-loads the authenticated-service context, with the useful 'review exact previews... reuse the same idempotency key' instruction intact. However, terse fragments such as 'Configuration, test proof, activation, collection and outcomes stay distinct' are opaque and refer to sibling domains, so the sentence does not clearly earn its place here.

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 exists, so return values need not be described, but this is a highly complex command-dispatcher with nine action variants and zero schema description coverage. The description covers auth, permissions and idempotency but never explains the actions themselves, leaving an agent unable to use the tool correctly from the description alone.

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 burden falls on the description, yet it explains no parameter semantics at all. The only concrete parameter guidance is 'reuse the same idempotency key,' and 'Inspect the command schema' explicitly defers to the schema rather than documenting the action variants, which is a significant gap for a nine-branch oneOf.

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 'Manage profile,' which essentially restates the name (agency_profile) and title ('Manage agency profile') without specifying what profile operations exist. Crucially, it never enumerates the nine command actions (bootstrap, update, invite, accept_invite, revoke_invite, assign, unassign, revoke_member, issue_key) that define the tool, leaving the actual scope of work opaque.

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 siblings such as agency_support, agency_reports, or agency_offers. The scope requirements ('Enrollment/installations additionally require agents:write; simulations require evals:write; care requires sms:write') describe permissions for OTHER areas, not when to select this tool, which adds confusion rather than 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?

Beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false), the description adds real operational context: mandatory roles/memberships/owner approvals, the preview-before-approval workflow, and required scope strings. The 'reuse the same idempotency key' advice complements rather than contradicts idempotentHint=false (client-supplied dedup for a non-idempotent call).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

It opens with authentication plumbing rather than purpose, and includes low-value jargon ('stay distinct') plus scope rules belonging to other tools. Five dense sentences where a front-loaded statement of what generate/configure do would earn far more.

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 exists, so return values needn't be explained, but with 0% parameter documentation and no explanation of the oneOf command variants, an agent cannot reliably construct a valid call. The approval/idempotency context is present; the command semantics are entirely absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden — and it does not explain any parameter. The 'generate' vs 'configure' actions, partnerId, installationId, expectedRevision, recipients and cadence are all undocumented; only the idempotencyKey's reuse pattern is hinted at.

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 generic verb 'Manage reports' plus an unclear scope sentence ('Configuration, test proof, activation, collection and outcomes stay distinct') never states what the tool concretely does — the schema's real actions (generate, configure) are never named. It does identify the resource ('reports') and the service, but it does nothing to distinguish this tool from reports-adjacent siblings like agency_billing_periods, agency_care or 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?

There is no explicit when-to-use / when-not-to-use guidance. The scope sentences (agents:write, evals:write, sms:write) reference other surfaces rather than selecting this tool, and 'Bootstrap and owner self-service use verified dashboard sessions' only vaguely implies a boundary without telling the agent which tool to call instead.

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

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

Annotations only declare the safety profile (destructive, open-world, non-idempotent, read-write); the description goes well beyond that by disclosing the authentication requirement, mandatory role/membership/approval prerequisites, per-category OAuth scopes, and a preview-before-approval workflow. It does not explain the consequences of the destructive operations or the approve/execute lifecycle in detail, so 5 is not warranted.

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 opening sentence is front-loaded and the permission mapping is compact, but sentences like 'Configuration, test proof, activation, collection and outcomes stay distinct' are cryptic and consume space without conveying actionable meaning. The paragraph is dense jargon rather than efficiently structured guidance.

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 exists, so return values need no explanation, and annotations cover the safety profile. However, for a polymorphic command dispatcher with three undocumented action variants, the description omits the single most important thing: what each command actually does. Auth and permission context is complete; operation semantics are not.

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, and it largely does not. The three command variants (acknowledge, measure, complete_exercise) and their fields (incidentId, businessId, exercise, note, minutes, amountCents) are never described in prose; only the idempotencyKey gets any coverage via the reuse instruction. The agent is left to reverse-engineer the union 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 frames the tool as managing agency support through an authenticated service, and hints at domains (configuration, activation, collection) and permission categories (enrollment/installations, simulations, care). But it never states the actual operations the dispatcher performs, and it does not clearly separate itself from sibling tools like agency_care or agency_enrollments, which its permission sentence indirectly references.

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 concrete procedural guidance: inspect the command schema first, review exact previews before approval, and reuse the same idempotency key. It also maps action categories to required scopes (agents:write, evals:write, sms:write) and states that roles, client memberships and owner approvals are mandatory prerequisites. It stops short of explicitly routing between 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?

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 goes far beyond the annotations, which only indicate destructiveness and idempotency. It discloses that the tool is approval-gated, bills immediately on execution, only prepares a request, that caller-supplied authorization fields are never sufficient, and that a review URL must be relayed. This is rich, non-obvious behavior that the agent must know, and it 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?

The description is well-structured, front-loading the core purpose, then explaining the approval-gating and ordering constraints. Every sentence carries essential information; there is no filler or repetition. The length is justified given the tool's complexity and the critical safety implications.

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 high complexity (10 params, nested objects, output schema) and the absence of output schema details in the description, the description still covers the essential workflow: the approval requirement, the billing consequence, the ordering with set_owner_phone, and the caveat about not claiming purchase prematurely. The output schema handles return values, so nothing critical 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 coverage is 100%, so the baseline is 3. The description adds crucial semantics for the 'authority' parameter by explaining that caller-supplied modes (human_confirmed, dashboard_session, system_policy) cannot authorize execution and are attribution-only. This goes beyond the schema description and helps the agent avoid misuse of that field.

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 ('Request a real phone-number purchase') and clearly distinguishes its scope: it prepares a request rather than executing a purchase. It also names the ordering requirement with set_owner_phone and the approval-gating, making it unmistakably different from sibling tools like attach_number or search_available_numbers.

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 clear context for when to use the tool (whenever a number must be acquired) and explicitly states that set_owner_phone must run first on the acquisition surface. It also warns against claiming purchase before approval. However, it does not explicitly name alternative sibling tools or state when NOT to use this tool in favor of another, leaving some inference to the agent.

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 declare destructiveHint=true, idempotentHint=true, and openWorldHint=false, but the description adds real value: it is APPROVAL-GATED, it unlocks the command center without claiming customer coverage, and selected routes stay pending until independently verified. This state/approval context goes meaningfully 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?

Front-loaded with the critical 'APPROVAL-GATED' constraint, then three dense sentences with little waste. Some domain jargon ('command center', 'customer coverage') slightly muddies otherwise tight prose.

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 an approval-gated mutation tool with an output schema (so return values need no explanation) and annotations covering the safety profile, the description supplies the key behavioral state semantics. The remaining shortfall is the undocumented non-choice parameters, which keeps it from full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 17%, so the description should compensate, and it does explain the 'choice' enum values and that testing preserves the private-test result. However, it leaves business_id, activation_session_id, idempotency_key, and the nested 'authority' object unexplained, so the low-coverage gap is only partially filled.

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 concrete action (save a customer-route choice) on a specific resource (forwarding/published_number/both/testing) after private-test proof. The core operation is identifiable, but terms like 'command center' and 'customer coverage' are domain jargon that a cold agent may not fully resolve, and no sibling tool is named for contrast.

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 an explicit precondition ('After private-test proof is complete') and an approval gate, plus clarifies that 'forwarding is optional' and 'testing keeps the existing private-test result.' It gives clear invocation context but names no alternatives or explicit when-not conditions.

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 already declare idempotentHint=true, destructiveHint=false, and openWorldHint=true, and the description enriches this: the link stays valid up to 3 days, the tool 'creates nothing billable and connects nothing by itself', and it warns not to claim WhatsApp is connected until status confirms. This adds auth and workflow constraints 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?

Front-loaded with the core purpose, then layers caveats and the follow-up step. It is dense and every sentence carries information, though slightly long and working hard to pack in constraints.

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 exists so return values need no explanation. Combined with the auth requirements, line-selection default, validity window, and explicit next-step routing, the definition is complete for correctly invoking the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, with business_id undocumented. The description compensates for phone_number by explaining the default-to-oldest-line behavior, which the schema does not convey, though business_id's role remains implicit as the account scope.

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: 'Get the one link a business owner opens to put WhatsApp on their KaiCalls number.' It distinguishes itself from the sibling get_whatsapp_status by explicitly noting it 'connects nothing by itself' and pointing to the status tool afterward.

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 who may call it ('Owner or admin only'), the default line selection ('oldest KaiCalls line unless phone_number names another'), and the follow-up requirement ('call get_whatsapp_status after the owner finishes'). When-to-use and the alternative flow are both spelled out.

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 the safety profile (destructive, non-idempotent, open world), and the description adds meaningful context on top: required scopes (calls:write plus admin role), the launch precondition of an assigned agent, the partial nature of pause ('already running calls may finish'), and the warning that a queued result is not delivery proof. This is exactly the extra behavioral detail annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four tight sentences, front-loaded with the action/scope, then preconditions, then side effects. Nothing is redundant with the schema or annotations and every clause carries operational 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?

With an output schema present, return details are correctly omitted. For a destructive, open-world mutation tool the description supplies auth requirements, preconditions, side-effect timing, and a caveat about the meaning of a queued result – enough 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 coverage is 50%: agent_id and business_id carry descriptions, while action and campaign_id do not. The description compensates for the undocumented enum by explaining what each action value does (launch queues pending calls; pause halts pending work), and reinforces the agent_id precondition. It adds only an implied naming for business_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?

States a precise verb pair and resource: 'Launch or resume an existing outbound call campaign, or pause it.' It also explicitly excludes a sibling domain ('This is not an email campaign tool'), letting an agent separate it from email_campaign and create_campaign without opening a schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for the two actions: launch requires an agent assigned to the business and queues pending calls; pause stops pending work. It rules out the email campaign sibling, but does not explicitly route the agent to create_campaign/list_campaigns for the adjacent cases (creating vs. inspecting 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 (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 only cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds substantial non-obvious behavior: the tool returns a checkout link, nothing is charged and no number exists until the owner pays, the caller is added as admin by default, and it fails on duplicate email. It even clarifies partner_code semantics (a partner never passes its own code for its own workspace).

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 purpose, then lifecycle, then parameter guidance. Dense but nearly every sentence carries decision-relevant information; the 'The owner signs in with their own email' sentence slightly restates the ownership point already made up front.

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 exists, so return values need not be explained, yet the description still usefully signals the checkout link is the payoff. For a 10-parameter mutation with no annotations on permissions/charges, it covers the critical behavioral edges but leaves the five undescribed parameters unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50% across 10 parameters. The description meaningfully elaborates join_as_admin (default true, admin added so caller can finish setup) and partner_code (referral crediting, never self-referential), but city, state, website, business_type, and business_name receive no explanation in either the description or the schema. Baseline 3 is appropriate given the partial 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?

Starts with a specific verb+resource ('Create a KaiCalls workspace for a business') and immediately scopes the ownership model ('owned by the business owner's own email'), which separates it from generic setup siblings like set_up_business. An agent can tell what this creates and for whom without opening the schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for invocation — a partner setting up a customer, or anyone setting up a business for its owner — plus the explicit failure precondition ('Fails if the email already has an account') and a follow-up pointer (get_setup_checklist). It stops short of naming alternatives (e.g. set_up_business, create_checkout) or stating when-not to use this 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 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?

Goes well beyond the annotations: it discloses the consent gate, do-not-email exclusion, verified sending domain requirement, owner approval with fingerprint binding to an exact revision, daily send caps tied to Kai level, and which three actions send nothing. It also explains that a sender turns ready asynchronously, and forbids claiming delivery from the result — all behavior an agent cannot infer from destructiveHint/openWorldHint alone.

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 purpose before the action list, and every clause carries real constraint information, so length is largely earned by the 8-action surface. However, it is delivered as one dense run-on paragraph with semicolon chaining, which makes the per-action rules harder to scan than a structured list would be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-action, 18-parameter, nested-object tool with an output schema present, the description covers sequencing, permissions, sending constraints, and the boundaries of what does and does not dispatch mail. Return values need not be explained because an output schema exists, and nothing an agent needs before calling 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 already 94%, so the baseline is 3, and the description still adds value by grouping the 18 parameters under their owning action (e.g. 'draft (sender_id, subject, text, lead_ids, optional design and daily_limit)') and clarifying the purpose of fingerprint, sender_id, and evidence_ref. It stops short of adding format or syntax detail beyond the schema, so it does not reach a 5.

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 ('Email a business's customers') and then enumerates each of the eight actions with its own parameters and effect, so an agent can tell exactly what this tool does. It explicitly names the sibling read tool get_email_campaign as the separate source of visibility, distinguishing it from that and from the other campaign/send 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 an implicit workflow (request_sender -> check_sender -> record_consent -> draft -> approve -> launch/cancel) and states which action to pick for each need. It also states per-action permission requirements (any member / admin / owner) and routes visibility queries to get_email_campaign, leaving little to inference.

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 goes beyond that by explaining it 'cannot assert or advance proof' and clarifying that a completed private test is separate from customer-route coverage and that forwarding is optional. That added context is valuable, though return shape is left to the output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Information is front-loaded with the primary purpose in the first sentence, but the paragraph is dense and some sentences (the forwarding/customer-route distinction) are hard to parse and could be tightened.

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 complete schema coverage, full annotations, and an output schema, the description covers the key behavioral caveats an agent needs—eligibility, non-advancement of proof, and the optional nature of forwarding. Sufficient, with minor room to clarify return values.

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 all five parameters are already documented (including business_id optionality and session rejection). The description adds no per-parameter meaning beyond that; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (read) and resource (current call readiness and persisted private-test proof) scoped to one business. It is clearly a read/status tool distinguishable from setup siblings like set_up_phone_system or get_setup_checklist, though it doesn't name an explicit 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?

Provides clear context on what qualifies (entitled owner with coherent assigned number, completed private test) and what does not (missing entitlement, incomplete setup, stale sessions). No explicit when-to-use-this-vs-sibling routing, but the eligibility conditions are strong 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, and the description adds useful context: it notes that billing access requires the 'billing:read' scope, that access is limited to an 'authorized client,' and that 'suggestions and unknowns remain explicit.' This goes beyond the annotations, though it does not cover pagination behavior despite the 'after' parameter.

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 and front-loads the action ('Read') and the resource options. It is dense but contains no obvious filler; the second sentence about suggestions and unknowns is short and relevant.

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 exists, so return values need not be explained. However, with four parameters at 0% schema coverage and no usage alternatives provided, the description is not complete enough for an agent to confidently call this tool without inspecting the schema further.

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 the full burden of explaining parameters. It clarifies the meanings of the 'resource' enum values, which is helpful, but gives no information about the required 'partnerId' or the optional 'businessId' and 'after' parameters, leaving three of four parameters undocumented.

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 clear verb ('Read') and enumerates the resources it covers (installations, support, billing, discovery), which distinguishes it from many siblings. However, it does not differentiate itself from the more specific sibling tools like agency_installations or agency_support, leaving overlap ambiguous.

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 no explicit guidance on when to use this tool versus the many sibling tools that cover the same resources. The only implied usage is selecting the 'resource' parameter, but no conditions, prerequisites, or alternatives are 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?

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 cover read-only, idempotent, non-destructive, and closed-world behavior, so the bar is lower. The description adds genuine context beyond that: it discloses that the output carries a next_step pointer naming the next tool to call, which is useful routing behavior not captured in 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, front-loaded with what is returned before the usage condition. Every sentence carries weight, though the middle clause is slightly more verbose than necessary.

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 zero-required-parameter getter with an output schema and full annotation coverage, the description is complete enough: it covers purpose, entry condition, and the next_step routing signal. Nothing essential to 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 coverage is 100% and the single business_id parameter is fully documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 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 clear verb+resource ('Read back what a business already has') and enumerates the returned content: profile details, agent count, and recent call volume. It is unambiguous, though it does not explicitly differentiate itself from adjacent getters like get_usage or get_analytics.

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 a concrete entry condition ('Start here when someone wants a business number that answers missed calls') and explains the intent of avoiding duplicate creation. It also names the follow-up behavior via next_step when no working phone line exists, giving clear context without 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?

With readOnlyHint/idempotentHint already covering the safety profile, the description adds what the annotations cannot: what is NOT returned (no file bytes, storage paths, signed URLs or tax identifiers) and the admin/auth requirement plus the rejected-then-correctable lifecycle. The prompt-injection warning about reviewer notes is a genuinely valuable behavioral caveat.

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 purpose, then tacked-on qualifiers and cautions in short sentences. Dense and mostly earning its place, though the stacking of negations and the reviewer-notes warning makes it read more like a checklist than a tight brief.

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 exists, so return values need not be restated; the description instead covers scope, states, exclusions and the surrounding upload workflow, which is what an agent needs to call it correctly. Only the business_id parameter's meaning remains uncovered.

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 0% for the single business_id parameter, so the description would need to carry the load. It implies tenant scoping with 'tenant-scoped', which loosely maps to business_id, but never defines the parameter, its format, or where the value comes from.

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 (Read) and resource (tenant-scoped business-verification document references) plus the review states it surfaces. It explicitly distinguishes itself from the nearby siblings by noting internal staff verification is separate from carrier registration, so an agent can tell it apart from get_text_registration and get_trust_level.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete operational context: upload happens on the secure owner page as an admin, and rejected documents can be corrected and re-uploaded. It differentiates from carrier registration, but does not name a specific sibling tool as the alternative or state explicit when-not-to-use conditions.

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 cover readOnly/idempotent/non-destructive, so 'Read-only; changes nothing' earns no credit. Beyond that, the description adds real behavioral depth: readiness requires the same proof the channel's own tool needs (approved text registration for texts to callers, verified number for WhatsApp), and email readiness is split between managedEmail campaign sender readiness and a connected mailbox. This is meaningful context an agent cannot get from the annotations alone.

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 verb, resource, and state vocabulary in the first sentence, followed by row semantics and caveats. Some sentences (the managedEmail campaign sender nuance) are long and dense, but each carries non-redundant information, so little is wasted.

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 exists, so return structure needn't be re-explained; the description instead supplies the interpretive layer (state definitions, proof requirements, next-step routing) that makes the output actionable. The only gap is that it doesn't position itself against the per-channel status siblings an agent might otherwise pick.

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 (business_id) with 0% schema description coverage, and the description never mentions it or its format. The parameter is largely self-evident from its name, so this is not a severe gap, but the description adds nothing over the schema here.

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 resource (every customer channel a business can have) plus the enumerated states it returns (ready, needs_setup, blocked, not_available). This clearly marks it as the aggregate channel-readiness view, distinguishable from narrower siblings like get_whatsapp_status, get_phone_system_status, and get_activation_status.

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 strong interpretation context: each row says whether a message can go out and whether customers can reach the business, and names the next-step tool to use. It does not explicitly state when to prefer this tool over the per-channel status siblings, so it stops short of the when/when-not/alternatives bar.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful authorization context ('any member of the business can read') and notes the consent/do-not-email filtering on returned customers, which is behavioral detail beyond the structured fields.

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 read purpose, then the parameter routing, then the read-only/auth note. Every clause earns its place, though the middle sentence packs a dense list of returned fields that could be tightened.

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 exists, so return-value exposition is optional, yet the description still summarizes what comes back, plus auth scope and the three input modes. Nothing an agent needs to call this 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 67% (business_id is undocumented in the schema), so the description carries real weight by explaining the optional-branch semantics of campaign_id (one campaign) and sender_id (domain DNS records). It adds mode meaning beyond the schema's terse descriptions, though it does not restate business_id, which is already required.

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 ('Read') and resource ('email campaigns') and enumerates exactly what the response surfaces: sending addresses with setup readiness, recent campaigns with status and outcome counts, and email-eligible customers. This lets an agent distinguish it from siblings like list_campaigns, create_campaign, and email_campaign without opening any schema.

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

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear mode-selection guidance: pass campaign_id for a single campaign, or sender_id for that domain's DNS records. It does not, however, contrast the tool against list_campaigns or the single-campaign view siblings, so the routing decision between tools is left partly to inference.

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 establish readOnly/idempotent/non-destructive, and the description adds genuine behavioral context beyond them: a 30-minute source lag, the access prerequisite, and precise definitions for 'connected phone calls' (>30s duration) and 'responsiveness' (previous 90 days). These metric definitions materially affect interpretation of the result.

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 purpose, followed by access, date semantics, freshness, and metric definitions in a tight sequence. Every sentence carries information, though the density of the metric-definition clause is slightly harder 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?

An output schema exists, so return values need not be described. For a read-only aggregate report, the description covers purpose, access requirements, date bounds, freshness, and metric definitions adequately; only the identity parameters remain unexplained.

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 carries the burden, and it partially delivers: 'Dates are calendar dates inclusive at both ends' clarifies start_date/end_date semantics. However, business_id and connection_id receive no explanation at all, leaving half the parameters undocumented in both schema and description.

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 ('Read the authorized advertiser's live Google Local Services aggregate account report') and names what it is not (signed-case revenue or lead-rating reporting), which routes away from rate_lsa_lead. It does not, however, explicitly distinguish itself from the sibling get_lsa_report, leaving some ambiguity between the two report 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?

Provides a prerequisite ('Requires linked manager-account access') and a negative disambiguation ('not signed-case revenue or lead-rating reporting'), which is useful context. It stops short of stating when to choose this over get_lsa_report or get_lsa_conversations, so selection guidance remains implied rather than 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile needs no restating. The description adds genuinely useful context beyond that: a hard 200-event cap and a staleness caveat telling the agent results only reflect previously synced data unless sync_lsa is run.

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 compact sentences that front-load what is returned (latest 200 synced events) before the prerequisite caveat. No redundant restatement of the tool name or title, 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?

An output schema exists, so return structure need not be described. The description covers scope limit, content, and the sync dependency; the only meaningful gap is the undocumented business_id, which is a schema-side deficiency rather than a description omission.

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% and neither parameter is documented in the schema, so the description must carry the burden. It only weakly implies lead_id via "for an LSA lead" and says nothing about business_id or the UUID format requirements, leaving one of two required identifiers unexplained.

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 (read) and resource (synced Google LSA conversation events for an LSA lead) with an explicit scope limit of 200 events and the content type (customer and advertiser messages). It differentiates itself from generic siblings like get_conversation/list_conversations by tying the resource to LSA leads and to the sync pipeline, though it doesn't name a sibling explicitly.

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?

"Sync first for current history" implies a prerequisite without naming the sync_lsa sibling or stating when this tool should be chosen over get_conversation. The condition is suggested but not spelled out, so usage is inferable rather than 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 establish this as a safe, idempotent read, so the bar is lower. The description adds meaningful context beyond them: sync freshness and completeness are included, the window is UTC with start-inclusive/end-exclusive semantics, and certain metrics are categorically unavailable in this source.

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 dense sentences with the scope stated first, then window semantics, then limitations. Every sentence carries information and none is redundant, though the unavailability clause is somewhat long.

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 exists, so return values need not be described; the description instead supplies the scope, window boundaries, data-freshness caveat, and the explicit list of metrics that cannot be derived. What remains missing is only routing guidance relative to sibling LSA tools.

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 carries the burden, and it partially does: it clarifies the start/end window semantics and that the window is UTC. However, it adds nothing about business_id (a uuid scoping the report) or the date-time string format expected by start/end.

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 (report) and enumerates the resource contents (LSA lead counts, types, statuses, ratings, credit counts), which is far more informative than the title. It is distinguishable from siblings like list_lsa_leads or get_lsa_account_report by being an aggregate count report, though it never names those siblings explicitly.

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 implies the usage context (aggregate LSA lead reporting over an explicit UTC window) and adds a strong data-interpretation guardrail ('never infer' financials/signed cases/response times), but it gives no explicit when-to-use versus the other LSA tools such as list_lsa_leads or get_lsa_account_report.

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 by structured data. The description adds genuinely new behavioral context beyond that: that saved configuration is not proof of a live workflow, and that production access must be verified in Google Cloud rather than in this tool.

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 with no filler, and the core purpose is front-loaded before the caveats. The wording is abstract in places but nothing is redundant.

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 exists so return values need not be explained, and annotations carry the safety profile, but the description still leaves the single required parameter unexplained and gives no context for when this inspection should be run versus related LSA tools.

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% and the sole parameter business_id (a UUID) is never mentioned in the description. The description does not compensate for the coverage gap, leaving the meaning and allowed source of that ID undocumented.

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 and resource: inspecting Google LSA account selection and sync freshness. It is distinguishable from siblings like get_lsa_account_report or sync_lsa, though it does not explicitly say how it differs from them.

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 explicit when-to-use guidance and no named alternative. A sibling like sync_lsa or get_lsa_account_report could plausibly be reached for the same goal, and the description offers no routing logic to disambiguate.

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, non-destructive, and closed-world. The description adds useful behavior beyond that: results are newest-first, a single fetch includes live status and quota consumption, and it mirrors GET /api/v1/meetings. It omits pagination/limit behavior for the list mode.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence packs both modes and the quota side-effect with no filler, though it is dense and could be split for easier parsing by an agent. Every clause 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?

With an output schema present, return-value structure need not be explained, and the description covers both invocation modes plus quota context. What's missing is list-mode behavior (count, pagination, date bounds) that an agent might need to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are already documented in the schema, including the multi-business condition for business_id. The description restates the list-vs-single mode but adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (list meetings / get one meeting by id) and enumerates what the single-meeting mode returns: live status, minutes used, summary, and plan's remaining minutes. This distinguishes it clearly from siblings like join_meeting, leave_meeting, and get_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 explains the two modes and the condition that selects them ('omit to list recent meetings'), and the schema reinforces that id is optional. It does not name alternative tools for adjacent needs (e.g., transcripts), 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.