callingly

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

Beyond the destructiveHint=false annotation, it adds meaningful behavior: the note is attached to the timeline, attributed to the authenticated user, and synced to connected CRMs. These are real side effects an agent should know.

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, no filler; the core operation is front-loadedentukan and each subsequent sentence adds a distinct fact. Excellent efficiency.

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, non-destructive action, the description explains the target, identification method, attribution, and sync side effects. It doesn't describe return/error details, but there is no output schema to clarify anyway.

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 high; the description mostly restates the lookup alternatives already present in the parameter docs. It doesn't add new meaning to the content parameter beyond what the schema says.

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 names the operation ('Add a note'), the target ('a lead's timeline'), and the lookup options (lead_id or phone_number). It is specific enough to distinguish from sibling tools like add_tag, though it does not explicitly name the alternatives.

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 explains how to identify the lead, which is helpful, but it gives no guidance on when to prefer this over siblings like add_tag, add_to_sequence, or schedule_sms, nor any exclusions or 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 provide idempotentHint=true and destructiveHint=false. The description adds meaningful non-obvious behavior beyond those hints: missing tags are created automatically, duplicate tagging is a no-op, and connected CRMs are kept in sync. No contradiction with annotations.

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

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

Three sentences, all informative: the action, identification method, auto-creation behavior, idempotency, and integration side-effect. Front-loaded and free of 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?

Good for the common case, but it never explicitly states that exactly one of lead_id or phone_number is required, and it does not describe the outcome if neither is provided. Since only tag is marked required in the schema, this ambiguity is a real completeness gap despite the description saying 'Provide this or...'.

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%; each parameter already has a descriptive comment. The description adds the high-level relationship between lead_id and phone_number (one-or-the-other identification) but does not add much 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 opens with a clear verb and object ('Tag a lead by tag name'), then explains how to identify the lead via lead_id or phone_number. It does not explicitly contrast with sibling tools like remove_tag or add_note, but the operation itself is unambiguous.

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 operational context (which parameters to use, that unknown tags are auto-created, that duplicate tagging is a no-op), but it does not explicitly distinguish when to use this tool versus alternatives. No mention of remove_tag or when not to use this action.

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 destructiveHint: true. Description adds that Callingly handles calls, texts, retries, and timing, which is behavioral context beyond the annotation. However, it doesn't disclose potential side effects like lead removal from other sequences or required permissions.

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: first defines action, second adds context. No wasted words, front-loaded with key information. Highly 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 tool with 7 parameters and no output schema, the description gives a high-level understanding but omits prerequisities (e.g., team existence, lead duplication handling) and results of the operation. It's adequate but not 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 coverage is 100%, so parameters are fully described in the schema. The description does not add any additional meaning or usage notes for individual parameters, so 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?

Description clearly states 'Add a lead to a team's automated follow-up sequence' and distinguishes from siblings like 'make_ai_call' and 'send_sms' by contrasting with 'rather than a single call'. It's a specific verb+resource with sibling differentiation.

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 'Use this to start a persistent follow-up cadence rather than a single call', which implies when to use. It could explicitly state when not to use (e.g., for immediate calls use sibling tools), but provides clear context.

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 and destructiveHint, but the description adds real value beyond them: it discloses the return contract ('returns what was cancelled; status nothing_scheduled means it was a no-op'), the role gate ('owners and admins only' for bulk), and the side effect of ending the lead's sequence. The idempotent no-op semantics are especially useful given destructiveHint=true.

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 dense sentence front-loads the core action and enumerates modes, with the bulk-confirm warning placed last. Every clause carries information, though the run-on structure is slightly heavy for readability.

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 100% schema coverage and no output schema, the description successfully covers what's needed: it explains the return/status semantics, the permission requirement for bulk cancellation, and the sequence-ending side effect. An agent has enough 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 coverage is 100%, so individual parameter docs are complete and the baseline is 3. The description earns above-baseline credit by explaining how the parameters interrelate: lead_id or phone_number identify one lead, scheduled_call_ids selects several (up to 500, each sequence ending too), and all scopes to team_id with an admin restriction.

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 (cancel) and resource (a lead's pending scheduled call), and goes further to clarify that it also ends the lead's follow-up sequence. The three distinct modes (single lead, by scheduled_call_ids, or all/team) are spelled out, letting an agent distinguish it from siblings like reschedule_call or delete_lead.

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

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

It clearly delineates the three invocation modes and when each applies (lead_id/phone_number vs scheduled_call_ids vs all with team_id), plus the operational guardrail 'Confirm bulk cancels with the user first.' It stops short of naming alternatives such as reschedule_call for a callback the agent wants to move rather than cancel.

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 only destructiveHint=false provided, the description adds useful behavioral detail: it returns the field's slug, shows how that slug is used in update_lead via custom_fields, and explains the text interpolation syntax. It does not cover permissions, rate limits, or duplicate-name handling beyond what is in the 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?

The description is short, front-loaded with the core action, and uses its remaining clauses efficiently to cover return value, downstream integration, and the deletion alternative.

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, one-parameter creation tool with no output schema and minimal annotations, the description is largely complete. It explains the returned slug and how to use it, though it could mention duplicate-name behavior even though the schema notes uniqueness.

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 single name parameter is fully documented in the schema as the label with max 255 and a derived unique slug. The description adds no parameter-specific detail beyond what the schema already supplies, so the baseline 3 applies.

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

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

The description states a specific verb and resource: 'Add a custom field to the account's leads.' It also distinguishes this tool from siblings by naming update_lead for setting values and delete_setup_item for deletion.

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 clear alternative for removing the field ('delete one with delete_setup_item') and explains downstream usage in update_lead and text templates. However, it does not explicitly state when to create a new field versus using existing tags, stages, or other setup items.

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 supply destructiveHint=false, so the description bears most of the burden, and it delivers real behavior: duplicate phone numbers are refused, the call returns the created lead's id, and no call/text side-effects fire. It omits auth/permission requirements and rate limits, which keeps it from a 5.

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

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

Three short sentences, no filler, with the core action and its distinguishing constraint front-loaded. The dashboard-form analogy and the get_settings pointer each earn their place by resolving ambiguity.

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

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

With no output schema, the description correctly compensates by declaring the return value (the new lead's id) and the duplicate-refusal failure mode, plus team_id defaulting. For a 9-param creation tool it is nearly complete; explicit mention that phone_number is required and any permission prerequisites would close the 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 coverage is 100% so the schema already defines all nine fields, but the description adds meaning the schema lacks: team_id originates from get_settings called with no arguments and otherwise falls back to the primary team. That is a genuine workflow addition beyond the 'defaults to primary team' note 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?

States a specific verb and resource (add a new lead to a team) and immediately scopes it against the call/SMS siblings with 'without calling or texting it.' The dashboard New Lead form analogy and the distinguishers from get_lead/update_lead/search_leads let an agent identify this tool 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?

Clearly frames the context: use this to create a lead record without initiating any call or text, unlike make_ai_call/schedule_call/send_sms. It also gives workflow guidance that team_id should come from get_settings. It does not name explicit alternatives for editing or looking up leads, so it stops short of full when/when-not routing.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond that by disclosing the side effect on any pending scheduled call, the all-or-nothing atomicity ('Nothing is deleted unless every lead is found'), the 100-item cap, and the confirmation requirement. These are the exact behavioral facts an agent needs before invoking a destructive 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 tight sentences, front-loaded with the action and scope, then the side effect, then the guardrail. No 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?

For a destructive batch tool with no output schema and full schema coverage, the description supplies everything else needed: cascade effect, atomicity semantics, batch limit, and a user-confirmation requirement. Nothing material 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 properties already document lead_id, lead_ids, and phone_number, including the 100-item limit. The description restates the one-of selection model but adds no format, syntax, or precedence detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete a lead'), and immediately quantifies scope ('or up to 100 leads at once'), which distinguishes it from sibling update_lead, get_lead, and delete_note. The cascade behavior is also named up front.

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 triggering conditions: use one identifier (lead_id or phone_number) for a single lead, or lead_ids for a batch, and explicitly instructs 'Confirm with the user first.' It does not name sibling alternatives (e.g., delete_number_item or update_lead) or state when not to use it, so it falls short of a 5.

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

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

The destructiveHint annotation already signals the write/destroy nature, so the bar is lower; the description adds meaningful context beyond it by disclosing the ownership restriction (only your own notes) and how to source the identifier. It does not mention irreversibility or post-delete effects, but the key behavioral constraint is present.

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

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

Three short sentences, front-loaded with the action, then the constraint, then the id-sourcing tip. Every sentence earns its place with no redundancy.

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

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

For a single-parameter destructive tool with a destructiveHint annotation and no output schema, the description covers action, authorization precondition, and identifier sourcing — nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value by explaining that note_id comes from get_lead's recent-notes listing, giving the parameter provenance the schema alone does not.

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 (Delete) plus resource (a note) and scope (from a lead's timeline), which cleanly separates it from sibling add_note. An agent can distinguish this destructive operation without consulting any schema.

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

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

Gives a concrete precondition ('Only notes you wrote can be deleted') and routes the agent to get_lead to obtain the required note_id. It stops short of explicitly contrasting with alternatives, but the usage context is 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 only declare destructiveHint=true; the description adds the details that matter: deletion is permanent, deleting a pool leaves its numbers intact, affected teams fall back to their own caller ID, and in-use caller IDs are rejected. This is exactly the 'what gets destroyed / what happens to dependents' context the annotation cannot carry.

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

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

A single dense sentence with the destructive scope front-loaded and the confirm-first rule attached. Every clause carries meaning, though the stacked parentheticals make it slightly harder to parse at a glance.

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?

Two required parameters, full schema coverage, no output schema, and the description covers both deletion modes, side effects on numbers and teams, and the blocking precondition. Nothing an agent needs before calling it 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% and the enum is declared in the schema, so both parameters are already documented. The description restates the id source (get_numbers) but adds no format or value-syntax detail beyond the schema, 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?

States a specific verb (permanently delete) and two concrete resources (number pool or caller ID), and enumerates them explicitly. An agent can distinguish this from delete_setup_item, manage_number, and delete_team without opening any schema.

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

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

Gives clear operating context: confirm with the user first, and the precondition that a caller ID still used by a rep, team, or AI agent cannot be deleted. It also points to get_numbers as the id source. It stops short of routing the agent to an alternative tool when deletion is blocked (e.g., manage_number to unassign first), so it isn't a full when/when-not/alternative 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 only declare destructiveHint=true; the description goes further by stating the deletion is permanent, requiring user confirmation, and disclosing two blocking preconditions for sequences. This is exactly the extra behavioral context annotations cannot carry.

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

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

Two tight sentences: the destructive action and scope come first, then the safety and precondition caveats. Nothing is padded or 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?

For a two-parameter destructive tool with no output schema, everything needed to invoke it safely is present: what gets deleted, where ids come from, confirmation requirement, and the blocking conditions.

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 fully documented (id plus a 4-value enum for type). The description restates the source of ids, which the schema already says, adding no syntax or format detail beyond it. Baseline 3 is correct.

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 ('Permanently delete') and enumerates exactly which resources are covered (lead tag, pipeline stage, custom field, follow-up sequence), which separates it from sibling mutators like remove_tag or manage_stages. An agent can identify the operation 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 explicit operating guidance: confirm with the user first, and take ids from get_account_setup. It also names failure conditions (sequence still used by a team, or the account's last sequence). It stops short of explicitly contrasting itself with sibling remove_tag/delete_* tools, so it misses a 5.

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

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

Annotations only declare destructiveHint=true, and the description goes well beyond that by enumerating the exact entities affected (leads, scheduled calls, phone numbers, integrations, webhooks, fallbacks), stating reps are removed rather than reassigned, and calling out the primary-team guard and the confirmation requirement. This is exactly the side-effect disclosure a destructive tool needs.

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 core action and side effects, followed by the guard condition and the safety instruction. No filler; 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?

For a two-parameter destructive tool with no output schema, the description covers consequences, constraints, and required confirmation, which is everything an agent must know before invoking. Nothing material is left unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that reassign_team_id absorbs leads/calls/numbers/integrations/etc. while reps are explicitly NOT moved there, resolving an ambiguity in the schema's own wording. This is meaningful added semantics over 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?

States a specific verb (Delete) and resource (a team) and immediately disambiguates scope by describing the cascade of reassignment and rep removal. An agent can distinguish this from siblings like manage_team or update_team_members 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?

Provides a clear when-not ('The primary team cannot be deleted') and a procedural precondition ('Confirm with the user first'), which is exactly what an agent needs before a destructive call. It stops short of naming alternatives for non-delete team operations, so it is clear context rather than a full routing guide.

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

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

The destructiveHint annotation already warns of destruction, but the description goes much further by explaining exactly what is deleted or changed: leads stop flowing, webhooks and credentials are removed, and CRM ids may be unlinked if this was the last integration. It also discloses that reconnection requires the dashboard.

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 dense sentence with no wasted words, front-loading the core action and following with consequences and caution. Every clause adds operational value.

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 destructive single-parameter tool with no output schema, the description is complete: it states what the tool does, what gets destroyed, the required caution, and the post-disconnect reconnection path. No critical decision information 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 input schema already documents integration_id and its source. The description repeats 'id from get_integrations' but adds no syntax, format, or constraint detail 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?

States a specific verb and resource ('Disconnect and delete an integration') and immediately distinguishes the operation from siblings like update_integration by describing deletion and disconnection effects. The parenthetical reference to get_integrations clarifies input sourcing without ambiguity.

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 when-to-use context: confirm with the user first, and reconnecting must be done via the dashboard. It does not explicitly name update_integration or another alternative, but the destructive nature and confirmation prerequisite are strong usage guidance for this operation.

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=true already declaring a safe read, the description still adds real behavioral value: sequences are returned with ids and 'in the format save_sequence takes', signaling round-trip compatibility between read and write. It does not cover ordering guarantees for the other collections or failure behavior for an invalid sequence_id.

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, no filler. The listing scope comes first, then the optional-parameter behavior, which is exactly the order an agent needs to decide how to call it.

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

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

No output schema exists, yet the description enumerates what comes back (tags, ordered stages, custom fields, sequences with ids, sequence settings and steps) and flags the save_sequence-compatible format. Nothing needed to invoke it correctly appears to be 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, and the description earns above baseline by explaining the dual semantics of sequence_id (single-sequence detail vs. full setup listing) and tying the returned shape to save_sequence's expected input.

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') plus the exact resources returned: lead tags, pipeline stages in order, custom fields, and follow-up sequences with their ids. An agent can tell this is the account-config read tool. It does not explicitly contrast itself with the mutation siblings (manage_tags, manage_stages, save_sequence), so it stops short of a 5.

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?

Documents both operating modes clearly: omit sequence_id to list account setup, or pass it to read a single sequence's settings and steps. It gives no explicit 'use X instead' routing to siblings that mutate the same resources, but the read vs. write boundary is inferable from the schema.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description adds real context beyond that: results are live-fetched from the external CRM ("Fetch live lists", "Calls the CRM"), implying an external dependency and freshness, and the platform/kind matrix signals which calls require an integration_id. It does not mention latency or rate limits, keeping it from a 5.

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

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

Purpose and downstream destinations are front-loaded, and the dense "Supported:" list is scannable rather than prose. The platform enumeration is long, but every entry carries routing information an agent can use to decide whether the tool will work for a given platform.

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

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

For a read-only lookup with no output schema and 100% parameter documentation, the description is largely complete: it covers purpose, downstream consumers, and platform constraints. A brief note on the 200-item cap or the auth/integration precondition would close the remaining 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 coverage is 100%, so baseline is 3. The description earns above baseline by adding a per-kind supported-platform matrix (e.g., stages only Pipedrive, pages/forms only Facebook, inboxes only Follow Up Boss Inbox App), which is not stated in the schema's kind enum. It does not clarify the search/object_type/reference_to interactions, which remain schema-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?

Specific verb (fetch) plus resource (live option lists from a connected CRM), with the exact value kinds enumerated (fields, tags, users, stages, pages/forms, inboxes, ponds). It also states where the results go (ids passed to update_integration or manage_user), which distinguishes it from siblings like get_integrations or manage_user without needing either schema.

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

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

It clearly frames the use case: fetching ids that downstream tools (update_integration field mapping/routing/tag rules, manage_user links) require, and the schema ties integration_id back to get_integrations. There is no explicit when-not or exclusion (e.g., that get_integrations is the prerequisite discovery step), but the context is strong.

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 already declaring the safe-read profile, the description adds real value: it discloses that include_importable triggers an outbound call to Follow Up Boss, and that the returned settings/field mapping/routing/CRM user shapes mirror what update_integration accepts. It does not cover pagination or list-size limits, so it falls short of a full 5.

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

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

Two dense sentences, front-loaded with the list/read duality before the optional importable mode and the sibling routing. Every clause carries distinct information with no filler.

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

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

With no output schema present, the description compensates by naming the list fields and pointing at update_integration as the shape contract for single-integration reads. It also covers the enum parameter's purpose, so an agent has everything needed 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 description coverage is 100%, so both parameters are already fully documented in structured form; the description largely restates the omit-vs-supply behavior of integration_id. Its only marginal addition for include_importable is the Follow Up Boss backend call, which is more behavioral than semantic, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the account's connected integrations') and enumerates the returned fields (platform, name, status, primary CRM), then clarifies the alternate read mode when integration_id is supplied. It explicitly distinguishes itself from the sibling get_crm_options by naming it and the condition that selects it.

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

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

Gives explicit branching instructions: omit integration_id to list all, pass it to read one integration's configuration, use include_importable for Follow Up Boss users/groups. It also names the alternative tool (get_crm_options) and the condition under which that one is correct, leaving nothing 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 indicate readOnlyHint=true (safe read). The description adds value by detailing the exact data returned (custom fields, recent notes, etc.) and the two lookup methods, going 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?

Two efficient sentences. The first sentence front-loads the action and output; the second covers parameters. Slightly verbose with listing all fields, but overall concise and well-structured.

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 optional parameters and no output schema, the description adequately explains what it does, what it returns, and how to identify the lead. Lacks mention of behavior when both identifiers are provided, but otherwise 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 coverage is 100% with clear descriptions for both parameters. The description reiterates the identification options but adds minimal new semantic meaning 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 clearly states 'Read a lead's full profile' using a specific verb and resource, and explicitly lists the fields returned (name, phone, email, etc.), distinguishing it from sibling tools like update_lead or add_note.

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 'so your AI and CRM stay in sync' implies when to use (for synchronization), and the description provides clear identification methods (by lead_id or phone_number), but does not explicitly state when not to use or compare to alternatives.

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?

readOnlyHint=true already covers the safety profile, and the description goes beyond it by disclosing what each mode returns: ids and key settings for the list, and full call/SMS settings plus greeting-capable voices for the detail read. That return-shape context is valuable given there is no output schema, though it doesn't address pagination or rate limits.

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

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

Two tight sentences: the list behavior is front-loaded and the conditional detail-read mode follows. No filler, redundancy, or buried 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 read-only listing/detail tool with annotations covering safety and no output schema, the description is nearly complete, explaining both the default and id-driven modes and their return contents. Only minor gaps remain (result format for the list, how large the list can get).

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 already documents both parameters and the baseline is 3. The description reinforces the effect of passing number_id/number_pool_id and adds return-scope detail, but introduces no new syntax or constraints 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 (List) and explicit resources (phone numbers, number pools, caller IDs) plus the detail-read mode. It is clearly distinguishable from mutation siblings like manage_number and delete_number_item. It stops short of naming a sibling directly, so it lands just under a 5.

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

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

It gives clear context for the two modes (no args to list, pass number_id or number_pool_id to drill in), which is genuine when-to-use guidance. However, it never names an alternative (e.g. manage_number for editing) or any when-not-to-use condition, so alternatives must be inferred from the sibling list.

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

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

Annotations already declare readOnlyHint=true. Description adds info on return data and filters, but doesn't disclose additional behavioral traits like rate limits or pagination beyond 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?

Two sentences, front-loaded with purpose, no redundancy, every sentence adds value.

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?

Describes return fields, filtering options, and purpose. Lacks pagination details but limit parameter covers that. Overall adequate for a read tool with simple parameters.

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

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

Schema covers parameter details (100% coverage). Description adds practical usage guidance (e.g., 'filter by lead_id to see how a specific lead's calls went'), going beyond schema definitions.

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 'Read recordings, transcripts and outcomes of recent calls', specifies return fields, and distinguishes tool from siblings that are write/action oriented.

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?

Implicitly indicates usage for reading call data to sync AI/CRM, and filters are clearly explained. Could be more explicit about when not to use it.

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

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

readOnlyHint=true already establishes this is a safe read, but the description adds valuable auth and routing context: teams are listable by any user while settings require owner/admin, and it discloses that calls, AI calls, callbacks and sequences all route through a team. It does not describe pagination or return formatting, so not a full 5.

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

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

Front-loads the two operating modes before any detail, and the entity glossary is a pragmatic, scannable structure rather than padding. It is on the long side, but every section earns its place; slightly dense.

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

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

No output schema, yet the description compensates by naming what a team record returns (id, business-hours status, AI agent, follow-up sequence). Combined with the entity catalogue and permission notes, an agent has enough to call it correctly; only pagination/error behavior is 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 100%, so baseline is 3, but the description adds genuine semantics beyond the schema: omitting id lists records of an entity while supplying id shows one record's editable fields, and the account entity needs no id. This explains how the two params combine, which the schema alone does not.

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 verb+resource with two clear modes: list teams (no arguments) or show the fields update_settings can change. It names the distinct sibling update_settings and explains the relationship, so an agent can differentiate without opening any schema.

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

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

Explicit when-to-use: call with no arguments to list teams, use it to find the team_id that call/AI-call/sequence tools need, and call it before update_settings to learn exact field names and current values. It also states the permission model (any user for teams; owners/admins for settings), leaving nothing 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, so the safe-read profile is covered. The description adds value by tying the user_id mode to manage_user's edit surface, but says nothing about pagination, ordering, or result limits. With annotations carrying safety, a 3 is appropriate.

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

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

A single front-loaded sentence that packs the list behavior, returned fields, and the user_id variant with no wasted words.

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

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

With no output schema, the description carries return-value burden and does reasonably by enumerating ids, roles, teams, and availability. Gaps remain around result size/ordering for a potentially unbounded account list, but the core is complete.

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

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

Schema description coverage is 100%, so every parameter (role, search, team_id, user_id, availability) is already documented in the schema. The description reinforces the user_id toggle but adds no syntax or format detail beyond the structured data, so baseline 3 holds.

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 (account's users), enumerates the returned fields, and covers the single-user variant. It separates itself from siblings by noting user profile fields come 'as manage_user edits them,' distinguishing read from edit.

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

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

Clearly conveys the two modes (omit user_id to list, supply it to see one profile) and links to manage_user for the edit context. It stops short of explicit when-not or naming other alternatives such as query_account_data, so it is clear context without 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?

readOnlyHint=true already declares the safe-read profile, and the description adds genuinely new context by naming the fields returned (id, name, gender, age, description, preview URL) even though no output schema exists. It omits any note on result size or pagination, keeping it below a 5.

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

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

Two tightly packed sentences, front-loaded with the core action and followed by the one integration detail that matters. No 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?

With no output schema, the description compensates by listing the returned fields, and the single optional parameter is documented at 100% in the schema. Coverage is strong for a simple read tool; only pagination/result-size behavior is 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 100%, so the 'search' parameter is fully documented in the schema with matching examples ('british', 'female'). The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the voices an AI agent can speak with') and further fixes the scope by enumerating what each voice record contains (id, name, gender, age, description, preview URL). No sibling tool lists voices, so there is nothing to confuse it with, and it references manage_ai_agent to anchor its role.

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 downstream context: 'Pass a voice_id to manage_ai_agent (set_voice) to use one,' which tells the agent this is the lookup/prerequisite step. It stops short of explicit when-not or alternative-selection guidance, but there is no competing voice-listing tool to exclude.

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 destructive behavior (destructiveHint=true). The description adds value by explaining the AI agent's actions (qualifies, answers questions, warm-transfers). No contradiction; the description does not need to repeat the annotation.

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

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

The description is two sentences, front-loaded with the core action, and every sentence adds necessary context. No wasted words.

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

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

Despite no output schema, the description explains the full workflow (AI agent calls, qualifies, warm-transfers) and includes prerequisites. For a tool with 7 parameters, this is comprehensive.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds no additional semantic detail beyond what is in the schema (e.g., phone_number format is already in schema). Baseline 3 is appropriate.

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

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

The description clearly states the action: 'Make a call to a lead with an AI voice agent.' It specifies the verb (make), resource (call), and context (AI voice agent, qualification). It distinguishes from siblings like 'make_dispatch_call' and 'schedule_call' by focusing on automated qualification.

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 usage context: 'Use this to qualify a lead automatically before a rep gets involved' and includes a prerequisite ('The team must have an AI agent configured'). It does not explicitly state when not to use or name alternatives, but the context is 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?

Description details the process: rings sales rep(s), plays lead details, bridges to lead. Adds context beyond destructiveHint annotation. No contradictions.

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

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

Three concise sentences: purpose, process, usage guidance. Front-loaded with core action. No unnecessary text.

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

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

Covers purpose, process, and usage well. Lacks mention of return values or error states, but without output schema this is acceptable for a simple action tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds no additional parameter information beyond schema, which is acceptable.

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 makes a dispatch call to a lead via a human rep, distinguishes from siblings like make_ai_call by emphasizing human involvement and immediate 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?

Explicitly says 'use this for speed-to-lead when a lead should be contacted by a human right now', providing clear guidance on when to use. Does not explicitly name alternatives but implies them.

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 only destructiveHint=false, leaving the read/write boundary to the description, and the verbs make the mutation nature clear. The description adds a little context about what set_primary means (the account's fallback agent), but says nothing about permissions, reversibility, or side effects on existing agents, so it does not go much beyond the schema's own action descriptions.

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 waste: the first front-loads the full action set, the second handles routing to the correct sibling tools. 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 no output schema but full parameter coverage in the schema and a non-destructive annotation, the description covers the action scope and sibling routing well. It omits prerequisite/permission context and what happens to existing agents on create/set_primary, but is largely sufficient 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 all four parameters are already documented in the schema, and the baseline is 3. The description adds only a cross-reference that voice_id values come from list_voices, which is marginal value beyond the structured fields.

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 specific verbs (create, duplicate, rename, set voice, set primary) against a specific resource (an AI agent), and routes the agent away from siblings by naming update_settings for wording/knowledge and list_voices for voice selection. An agent can distinguish this tool from update_settings and list_voices without opening either schema.

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

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

It explicitly names the alternative for adjacent tasks ('Edit an agent's wording and knowledge with update_settings (entity ai_agent)') and where voices come from ('pick voices from list_voices'), which is clear routing guidance. It stops short of stating prerequisites, permissions, or when NOT to use the manage actions themselves, so it is strong but not complete.

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

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

Annotations supply only destructiveHint=false, so the description carries most of the burden. It discloses the read-before-write prerequisite and the breadth of mutations, but is silent on permission requirements, reversibility, and the fact that reset_welcome discards custom audio (that detail lives only in the action enum). Adequate but with clear gaps for a 9-action mutation 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?

The action inventory is front-loaded in one dense sentence followed by a short imperative prerequisite, so the agent sees scope before the setup step. The enumeration is long but each action listed earns its place in a dispatcher-style tool.

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 12-parameter tool with a nested `changes` object and no output schema, the description plus the rich schema give enough to call it correctly, and the get_numbers prerequisite closes the main gap. It could still say more about mutation side effects and per-action requirements to be fully self-sufficient.

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

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

Schema description coverage is 100%, so the schema already documents all 12 parameters and the per-action enum semantics. The description only adds the provenance hint that ids come from get_numbers, which the schema largely implies already; 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 names concrete verbs and resources across the full action space: change call/SMS settings, rename a number/pool/caller ID, generate or reset greetings, set dispatch, create a pool, and add/remove pool members. It also clearly scopes the tool to both numbers and number pools, which distinguishes it from read-only siblings like get_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?

It gives an explicit prerequisite — "Read ids and current settings with get_numbers first" — which routes the agent to the correct read tool before mutating. It does not, however, state when-not conditions or how to choose between this tool and adjacent mutating siblings (e.g. delete_number_item, update_settings).

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 destructiveHint=false. The description adds real behavioral detail beyond that: create appends at the end of the pipeline, and reorder consumes every stage id in the account. It doesn't mention permissions or what happens on a partial/incorrect reorder payload, so it stops short of a 5.

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

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

One dense, front-loaded sentence covering all three actions plus the two sibling redirects. No filler and no repetition of the title.

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

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

No output schema exists, and the description adequately covers all actions, their required inputs, and routing. Minor gaps remain around error/partial-reorder behavior and required permissions, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds the provenance pointer 'ids from get_account_setup' and reinforces the append-at-end semantics for create, which the schema does not convey.

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

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

States three specific operations (add at end, rename/recolor by stage_id, reorder all stages) against a concrete resource. It explicitly distinguishes itself from the similarly named update_stage and delete_setup_item, so an agent can pick correctly without opening schemas.

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

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

Names the two nearest alternatives and the conditions that select them: 'To move a lead to a stage use update_stage; to delete a stage use delete_setup_item.' Each action's scope is also stated inline, leaving nothing 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 only supply destructiveHint=false, so the description carries most of the burden. It usefully discloses that tag ids come from get_account_setup, but says nothing about permissions, whether a rename affects existing lead associations, or the response shape.

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

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

Two short sentences, zero filler, with the tool's own scope stated first and the sibling routing second. Nothing is redundant or padded.

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

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

For a create/update tool with full schema coverage and no output schema, the description covers scope, id sourcing, and sibling routing adequately. The only real gap is behavioral detail around permissions and the effect of renames, which is minor here.

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 four parameters (including the create/update enum semantics and the keep-current behavior on omitted fields) are already documented in the schema. The description only adds the origin of tag_id values, so it sits at the baseline.

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

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

States specific verbs (create, rename, recolor) and the resource (lead tag), and pins the update path to tag_id. It is instantly distinguishable from add_tag and delete_setup_item, which it names directly.

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

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

Explicit routing is provided: use add_tag to tag a lead, delete_setup_item to delete a tag, and this tool only for creating or editing tag definitions. Both alternatives are named with the condition that selects them.

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 destructiveHint=false, so the description carries most of the burden. It adds real behavioral context beyond annotations: the new team inherits 'the primary team's numbers and whispers,' and duplicate copies reps and hours. It does not restate auth (deferred to the schema) or note confirmation/irreversibility semantics.

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, no filler, with the create-vs-duplicate split front-loaded and the ID-source caveat trailing. 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?

For a 6-param mutation tool with no output schema and only a destructiveHint annotation, the description covers the two actions, inheritance behavior, and ID provenance. It leaves permissions (owners/admins only, present in the schema) and any response/return expectations unaddressed, but is close to sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: it tells the agent where sequence_id and team_id originate (get_settings), which affects how the tool will be invoked in practice. No format/syntax detail beyond that is added.

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 specific verbs and resource: 'Create a new team (ring group)... or duplicate an existing team with its reps and hours.' It distinguishes the two modes of operation and names the relevant configuration artifacts (follow-up sequence, ring mode, reps), so an agent can immediately separate it from delete_team and update_team_members.

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 provides a prerequisite pointer ('sequence_id and team_id come from get_settings'), which is useful, but gives no explicit when-to-use / when-not-to-use guidance against siblings such as delete_team or update_team_members. Usage is implied by the tool name and action enum rather than stated.

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

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

Annotations only assert destructiveHint=true, and the description adds real side-effect context beyond that: inviting emails a login unless calls-only, reset emails a new password the user must change, and both should be confirmed with the user. It does not describe what an update overwrites, but the added email/confirmation behavior is genuine value.

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 three actions before the workflow note. The field enumeration is dense but every clause maps to real parameters, 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?

For a 35-parameter mutation tool with no output schema, the description covers the action set, key side effects, and the read-before-write plus confirm-before-invite/reset workflow. Remaining parameter behavior is fully carried by the 100%-covered schema, so nothing critical 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 description goes beyond the schema by cross-referencing sibling tools for id sources ('find the ids with get_crm_options kind users', get_users, get_settings), which helps an agent supply valid values.

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 three specific actions on a specific resource: invite a user, edit a profile, reset a password. It is clearly distinguishable from siblings like get_users (read) and remove_user (delete), and the field enumeration makes the scope of 'edit' concrete.

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 gives a prerequisite and workflow: 'Read current values with get_users first; confirm invites and resets with the user,' naming the alternative read tool. It stops short of stating when-not-to-use (e.g., use remove_user for deletion), so it is strong but not fully exhaustive.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower. The description still adds non-obvious behavior: stored times are UTC while group_by time buckets are converted to the account's timezone, the date range binds to a resource-specific default date column, and transcript columns are flagged as long and should only be selected for a few calls. It stops short of describing result size/pagination limits beyond `limit` being capped at 200.

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?

Very large, but front-loaded correctly (purpose → alternatives → modes → date rules → syntax → resource catalog) and almost every sentence carries operational detail an agent needs. The per-resource column listing is the bulk of the length; it is justified only because the schema enumerates resource names without documenting columns, though it does make the description unwieldy.

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 18-resource, 11-parameter generic query tool with no output schema, the description supplies the missing pieces: every resource's default date column, its columns with types and cross-resource id mappings (calls.user_id → users.id, profile_id → teams.id), plus the advice to resolve ids by querying the referenced resource and to discover column values by grouping on them.

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

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

Schema description coverage is only 45%, so the description must compensate, and it does: it documents group_by (column or `bucket:column` with the full bucket vocabulary), aggregates (`count` or `function:column` with the function list and output naming like `avg_seconds`), filters ({field, op, value?, values?} with the full op enum and the 1/0 boolean convention), order_by/order_dir (including ordering by an aggregate output name), and date_from/date_to/date_field semantics down to the America/Phoenix timezone and inclusivity.

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 verb+resource ('Read this account's data. Returns JSON rows.') and immediately scopes it ('counts, breakdowns and lists across leads, calls, texts, reps and teams'). It differentiates itself from siblings by enumerating the four specialised tools it is not (query_reports, search_leads, get_lead, get_recording).

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 to prefer specialised tools 'where one fits' and names each alternative with its selection condition (report metrics, finding a lead, one lead's profile, a call's recording). This is textbook when-to-use/when-not 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 only declare readOnlyHint=true, so the description adds useful operational context: account-level scope, the specific metric set returned, and the role restriction on the alternative data tool. It does not cover pagination or date-range timezone behavior, but the annotations already establish the safe read-only profile.

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

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

Three sentences, each earning its place: purpose plus metric list first, usage examples second, alternative routing third. Front-loaded and free of filler.

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

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

No output schema exists, so the description's enumeration of returned metrics (call volume, connection rate, voicemail/missed counts, talk time, per-rep performance) does the work of describing the result shape. Combined with annotations covering safety, an agent has everything needed 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 description coverage is 100%, so the start, end, and team_id parameters are already fully documented in the schema. The description implies a date range but adds no syntax or format detail, and it never mentions the team_id filtering parameter at all. Baseline 3 is appropriate when the schema carries parameter semantics.

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 (query call reports) with clear scope (account, date range) and enumerates the metrics returned: call volume, connection rate, voicemail/missed counts, talk time, per-rep performance. It also explicitly distinguishes itself from the sibling query_account_data for breakdowns it does not cover.

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 concrete example questions that select this tool, and names the alternative (query_account_data) with the condition under which it applies (counts/breakdowns this tool does not offer) plus a role constraint (owners and admins). Both when-to-use and when-to-use-something-else are 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?

The description explicitly states that removing a non-existent tag is a no-op, which adds behavior beyond the idempotentHint annotation. The annotations already cover idempotency and non-destructiveness, but the description reinforces and clarifies this, adding value.

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, concise and front-loaded with the primary purpose. It includes the important no-op caveat without extraneous detail. It could be slightly more structured but is 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?

The description covers the core action and the no-op behavior, essential for any lead with or without the tag. However, it does not detail prerequisites (e.g., whether the lead must exist) or any side effects beyond the no-op. The output is likely void, so return format isn't critical. Adequate for a simple 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?

The input schema already has 100% coverage for all three parameters. The description does not add extra meaning beyond the schema—it simply restates that identifiers can be lead_id or phone_number, which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action (remove a tag), the target (a lead), and the identifier options (lead_id or phone_number). It is specific enough to distinguish from sibling 'add_tag' and other lead operations, though it doesn't explicitly name a sibling tool.

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 it (removing tags from leads) but does not provide explicit guidance on when not to use it or mention alternatives like 'add_tag'. The no-op behavior for missing tags is a useful usage note but not a full comparison with siblings.

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 annotation only declares destructiveHint=true, and the description goes well beyond it: irreversibility ('cannot be undone from the dashboard'), downstream consequences ('can no longer log in or receive calls'), and a protected-object constraint ('The owner cannot be deleted'). These are exactly the traits an agent needs before firing a destructive 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?

Three short sentences, each carrying distinct information: what happens, what is forbidden, and the required confirmation step. The destructive nature is front-loaded, and no sentence 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?

For a one-parameter destructive tool with no output schema, the description covers irreversibility, side effects, and a guardrail, which is close to sufficient. It stops short of noting permission requirements or what happens to data (leads, calls) owned by the deleted user, which would matter for a permanent account change.

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 user_id parameter is already documented as 'The user to delete (ids from get_users)', which even points at the discovery tool. With the schema doing the work and no additional semantics offered in the description, 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 ('Permanently delete a user from the account') with the added qualifier 'permanently', which distinguishes it from a soft-disable. However, it never names or contrasts with the sibling 'manage_user', which plausibly overlaps in scope, so the agent must still infer the boundary.

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 instruction 'Confirm with the user first' is a genuine precondition on invocation, so this is more than nothing. But there is no guidance on when to prefer remove_user over manage_user or how it relates to delete_team, leaving alternative-selection entirely 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral constraints beyond that: only *pending* calls can be moved, and the target time is bounded to 'within the next year.' It doesn't describe error behavior (e.g. completed or cancelled calls) but the added constraints are meaningful.

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 its scope, then the identification methods, then the alternative. Every clause carries information; no filler.

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

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

For a 4-parameter mutation tool with no output schema, the description covers what moves, how to identify the target, the time bound, and the alternative tool. A note on precedence among the three identifiers or on non-pending calls would close the remaining gap, 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?

Schema description coverage is 100%, so all four parameters (lead_id, phone_number, scheduled_at, scheduled_call_id) are already documented in the schema, including the ISO 8601 offset/timezone rule. The description restates the identification options without adding format or precedence semantics (e.g. what happens if both lead_id and scheduled_call_id are supplied). Baseline 3 is appropriate.

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

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

States a specific verb and resource with scope: 'Move a lead's pending scheduled call (a booked callback or the next follow-up) to a new time.' The parenthetical clarifies exactly what a 'scheduled call' is, and it explicitly contrasts itself with the sibling schedule_call, so an agent can pick it without opening schemas.

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

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

Gives explicit routing: use this when a call is pending, use schedule_call when the lead has none. It also spells out the three accepted identification paths (scheduled_call_id, lead_id, phone_number). The only gap is that it doesn't explicitly distinguish itself from cancel_scheduled_call or update_schedule, but the alternative-and-condition pattern is fully present.

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 supply destructiveHint=false, so the description carries real weight: it discloses that during_steps/outside_steps are whole-list replacements, that a team removed from team_ids is moved to another sequence, that duplicate produces "<name> (copy)" with no teams, and that update only mutates the arguments passed. These are non-obvious side effects and mutation semantics beyond any structured field.

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, zero padding, with the three supported actions and the critical edit-steps workflow front-loaded before any detail.

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

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

For a 7-parameter mutation tool with no output schema and only a single annotation, the description covers actions, step syntax routing, and side effects. Remaining gaps are minor: no auth/permission requirements and no statement of what is returned.

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 goes further by tying the editing workflow to sequence_id and describing what the step arrays replace, adding meaning on top of an already thorough 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?

Names a specific verb set (create/update/duplicate) on a specific resource (follow-up sequence), and enumerates the three modes so an agent can distinguish it from siblings like add_to_sequence or update_schedule at a glance.

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

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

Gives explicit context for the update path: read steps with get_account_setup(sequence_id), modify the list, and send the whole list back. It does not, however, name alternative tools an agent might confuse it with (e.g. add_to_sequence for attaching a lead versus editing the sequence definition).

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 include destructiveHint: true, but description does not address destructive behavior. Description adds positive details about dialing, reminders, retries, which is useful but doesn't fully explain side effects. No annotation 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?

Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.

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?

Missing explanation of return value (e.g., whether it returns a call ID). No output schema provided. Also lacks error cases or prerequisites. Acceptable for a simple tool but incomplete.

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

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

Schema covers all 8 parameters with descriptions. Description adds valuable context: E.164 format for phone_number, timezone-dependent string format for scheduled_at, and example values. Greatly aids correct parameter entry.

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?

Clearly states the tool schedules a callback instead of immediate calling, with specific verb 'schedule'. Distinguishes from sibling tools like schedule_sms and make_ai_call by focusing on callbacks.

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 'Use this to book a callback for later', providing clear usage context. Does not explicitly list alternatives or when not to use, but implies contrast with immediate calling.

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 discloses that messages are 'rendered and sent' at the scheduled time, and notes that 'past times are bumped to now.' This adds important behavioral context beyond the 'destructiveHint: true' annotation, which only indicates side effects.

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

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

The description is two sentences long, front-loads the core purpose, and wastes no words. Every sentence adds value.

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

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

The description covers the main purpose and usage but does not explain what the function returns (no output schema). It also omits details like whether scheduling can be edited or cancelled. Given the tool's simplicity, it is adequate but not 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 baseline is 3. The description does not add new meaning beyond what the schema already provides for each parameter.

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 verb ('schedule'), resource ('SMS text message'), and key differentiator ('at a future time instead of sending immediately'). It distinguishes from the sibling tool 'send_sms' which likely sends immediately.

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 explicitly provides a use case: 'time a reminder or follow-up to the lead's timezone.' It also implies when not to use it (immediate sending) via the phrase 'instead of sending immediately.' However, it does not explicitly name alternatives like 'send_sms'.

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 readOnlyHint=true, so the description adds real value: default ordering (newest first) and the return shape (short summary per lead). It also notes the permission constraint on the alternative tool. It omits pagination/limit behavior detail, keeping it just short of a 5.

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

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

Three tightly written sentences: purpose front-loaded, then matching/filtering semantics, then alternative routing. No filler, every sentence earns its place.

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

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

With no output schema, the description still explains the return format (short summary per lead) and how to get more detail via get_lead. Annotations cover the safety profile, so 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 100%, so the schema already documents all five parameters with examples. The description restates the matched fields and filters but adds no syntax or format details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Find leads'), plus scope details: which fields free text matches and which filters (team, tag, stage) narrow results. It also distinguishes itself from siblings by naming get_lead for full profiles and query_account_data for counts.

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 routes the agent: use this tool for search, get_lead for a full profile by id, and query_account_data for counting/breakdowns (with the owner/admin caveat). The when-to-use-which-tool decision is fully 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 indicate destructiveHint=true, and the description aligns by stating 'send' (a write operation). It adds useful prerequisites (lead existence, must use own number). No contradictions.

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 that front-load the core action and constraints, followed by usage examples. No wasted words.

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

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

Given the tool's simplicity (3 parameters, no output schema) and the presence of annotations, the description adequately covers purpose, prerequisites, and usage scenarios. Missing details like return values or error handling are acceptable for this type of 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?

The input schema has 100% description coverage, so the description adds little beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the action (send an SMS), the target resource (existing lead), and the source (your Callingly numbers). It also provides example use cases, making the purpose unmistakable.

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

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

The description explicitly says when to use the tool ('introduce an agent, confirm a callback, or follow up') and includes a prerequisite (lead must exist). It does not mention when not to use or alternatives, but the context is 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 and idempotentHint=true, so the safety profile is partly covered. The description adds genuinely useful context beyond that: stop_follow_up and block also cancel the pending scheduled call and end the sequence, and resuming does not restore them — an irreversible side effect the annotations alone do not convey.

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

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

Three dense sentences, front-loaded with the tool's scope before the action list and the side-effect caveat. Nearly every clause earns its place, though the second sentence is long 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 no output schema, the description does need to carry behavioral weight, and it covers scope, identification, and irreversible cancellation effects. It stops short of stating permission/auth requirements or what happens to in-flight calls, which a destructive multi-action tool could reasonably include.

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%, including a detailed enum explanation for action, so the schema already carries the parameter semantics. The description restates identification via lead_id or phone_number but adds no syntax, format, or precedence detail beyond what the schema provides — 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?

Names a specific verb pair (stop/resume) and resource (automated contact with one lead), then enumerates the exact channels covered: follow-up calls, texts, AI calls/texts, and full block. An agent can distinguish this from siblings like cancel_scheduled_call or add_to_sequence 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?

Usage is implied through the action enumeration and the lead-identification instructions, and the side-effect note ('stop_follow_up and block also cancel...') helps an agent choose. However, it never contrasts itself with adjacent tools such as cancel_scheduled_call or add_to_sequence, nor states when one action should be preferred over another.

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 idempotentHint and destructiveHint=false; the description adds real behavioral context: snooze is self-terminating after fixed durations, and do_not_disturb_off cancels an active snooze. It doesn't state permission requirements or how calls are routed, but the interaction between actions is well disclosed.

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 core on/off action before the snooze nuance. The parenthetical duration list is dense but earns its place by mapping to the enum; slightly long but no wasted filler.

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

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

With no output schema, the description covers the state transitions and targeting rules an agent needs to call it correctly. It stops short of describing the resulting state response or who may change another rep's availability, which are minor gaps for a simple availability toggle.

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 already documents every parameter, including the enum meanings and the user_id/email targeting rule. The description restates the same targeting detail and duration list rather than adding new semantics beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Turn Do Not Disturb on or off for a rep') plus the snooze variant, so the agent knows exactly what operation it performs. No sibling tool covers rep availability, so differentiation is implicit but unambiguous.

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?

Explains the three actions and when each applies, including that turning off also ends a snooze, and how to target the rep ('omit both for yourself'). It lacks explicit exclusions or pointers to alternative tools, but none exist for this capability.

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 destructiveHint=false, so the description carries the rest and does so well: it discloses that 'rules' replaces the entire ordered list (omit to keep, [] to clear), that 'settings' merges nested objects but replaces lists/scalars, and that null unmaps values. It stops short of stating permissions or reversibility.

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

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

Three sentences, front-loaded with the operations it supports, then the required read-first workflow. Dense but every clause earns its place; it does not wander or repeat the title.

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 14-parameter, nested-object mutation tool with no output schema and full schema coverage, the description supplies the missing operational context: capability scope, read-before-write workflow, and the sibling sources for valid CRM values. Only auth/permission behavior is 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 100% so the baseline is 3, but the description adds genuine cross-parameter value: the instruction to read via get_integrations and send values back 'in the same shapes', plus the pointer to get_crm_options for CRM-derived keys/ids, which the schema alone does not convey.

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

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

The first sentence names the verb ('Change') and the exact resource (a connected integration) and enumerates the distinct editable surfaces: settings, field mapping, routing rules, CRM user mapping, primary-CRM toggling, and Follow Up Boss imports. That scope makes it clearly distinguishable from siblings like disconnect_integration or get_integrations.

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 an explicit prerequisite workflow: read the integration with get_integrations first, and pull CRM-sourced values from get_crm_options. It does not state when to avoid this tool or contrast it with update_settings/update_team, so it falls short of full when/when-not 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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: partial updates only, the lead can be identified by either lead_id or phone_number, and custom field slugs not defined on the account are ignored and reported back. This goes beyond the annotations and helps the agent predict side effects.

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

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

Three sentences with no waste. The core action and field list are front-loaded, the identification and partial-update semantics come next, and the sibling routing is at the end. Every sentence earns its place.

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

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

For a 10-parameter tool with no output schema, the description covers the essential invocation semantics: what fields can be updated, how to identify the lead, partial-update behavior, and how to route to siblings. It doesn't describe the return value, but with no output schema and idempotentHint=true, that's a minor gap. The custom_fields behavior is well explained.

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 meaning beyond the schema by explaining the partial-update behavior, the lead_id-or-phone_number identification requirement, and the custom_fields behavior (ignored/reported back). It also tells the agent to call get_lead to discover available slugs, which is genuinely useful parameter-level guidance.

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 ('Update') and resource ('a lead's profile fields'), enumerates the exact fields, and explicitly distinguishes itself from sibling tools like update_stage and add_tag/remove_tag. An agent can tell exactly what this tool does and what it does not do.

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 explicitly says when to use this tool ('To change the lead's stage use update_stage; to manage tags use add_tag / remove_tag') and provides identification guidance ('Identify the lead by lead_id or phone_number'). It also clarifies partial-update semantics ('Only the fields you provide are changed'), which is critical for correct invocation.

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 and destructiveHint=false, and the description adds real merge semantics: only passed days change, omitted days keep current hours, and an omitted timezone keeps the current one. It does not disclose permission requirements for editing a team's schedule versus your own.

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 mutation and immediately followed by the identification and partial-update rules. No filler or restatement of the tool title.

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

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

No output schema is needed for a setter, and the annotations cover the safety profile, so the remaining burden is minimal. The description covers entity resolution, partial updates, and timezone defaulting, leaving only error behavior for invalid ids/timezones unstated.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds provenance not present in the schema: where team ids come from (get_settings with no arguments) and the self-schedule case for entity=user. The timezone parameter's 'optionally the timezone they are read in' phrasing also clarifies its role beyond the schema text.

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 ('Change the weekly hours') plus the two entity types it applies to (team calling hours vs rep availability) and the timezone side effect. It does not name or differentiate against the sibling set_user_availability, which appears to overlap for the 'user' branch, so sibling differentiation is incomplete.

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 identification guidance: team by team id sourced from 'get_settings with no arguments', rep by user id, and self-schedule when entity=user with no id. It also states the partial-update rule ('Only the days you pass change'). It stops short of saying when to prefer this over set_user_availability.

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 idempotence and non-destructiveness, and the description adds genuinely new behavior: it returns what was saved, and on validation errors nothing is persisted. That failure-atomicity detail is exactly the kind of context the annotations do not supply.

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 dense paragraph, front-loaded with the operation and scope, followed by the read-first prerequisite, the batching rule, and the return/error contract. Every clause carries functional information with no padding.

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

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

For a nested-object mutation with no output schema, the description supplies the prerequisite lookup, payload discipline, batching, and the success/failure outcome, which is enough to call it correctly. It leaves the semantics of individual settings fields to get_settings, which is a reasonable handoff.

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% and the schema already documents the changes payload format (booleans, full replacement lists) and that id is unneeded for the account. The description's main addition is the instruction to reuse exact field names from get_settings, which is useful but overlaps heavily with the schema text.

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 (change) plus the resource (settings) and enumerates the four record types it can target (account, team, AI agent, user), which mirrors the entity enum. It does not, however, distinguish itself from overlapping siblings such as manage_user, manage_team, manage_ai_agent, or update_team_members, so an agent still has to infer whether those handle different concerns.

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 real operational guidance: read field names from get_settings first, send only changed fields, and batch multiple changes to the same record into one call. It stops short of stating when NOT to use this tool or which sibling to prefer for non-settings mutations.

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 the prerequisite that the stage must exist and discloses the side effect that the change syncs to connected CRMs, going beyond the idempotentHint and destructiveHint annotations. It is slightly light on failure behavior but sufficient for this simple mutation.

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

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

Three concise sentences, front-loaded with the core action and identifier options, with no filler or repeated schema text.

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

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

For a simple three-parameter tool, the description covers the prerequisite, identifier choice, and downstream side effect. It does not specify behavior when both identifiers are provided, but that is a minor edge case.

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 description does not need to re-explain each parameter. It adds a small amount of context about the stage-must-exist requirement and the identifier alternatives, but the schema already carries the core semantics.

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: 'Move a lead to a pipeline stage by stage name.' It clearly identifies the operation and the two accepted lead identifiers, making the tool's purpose unambiguous and distinct from siblings like get_lead or update_lead.

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 invocation guidance: use the stage name, the stage must already exist, and the lead is identified by lead_id or phone_number. It does not explicitly contrast with update_lead, but the usage context is clear enough.

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 and destructiveHint=false, so safety is partly covered. The description goes further by disclosing that 'set' replaces the whole roster and that the tool also rewrites ringing/lead-routing behavior, and it names the return value. There is mild tension between the roster-wiping 'set' action and destructiveHint=false, but no data is deleted, so this is not a true 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?

One dense, front-loaded sentence covering capability first and operational details after; the closing sentence about the returned roster is useful rather than filler. Slightly long but no wasted phrasing.

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

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

No output schema exists, and the description compensates by stating that the team's roster is returned. Combined with annotations covering idempotency/destructiveness and a fully documented schema, an agent has everything needed to invoke this tool 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 already 100%, and the schema spells out every enum value, cap period, and priority default. The description only adds that team_id originates from get_settings and reps are identified by user_id, which is marginal value over the schema baseline.

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

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

States concrete operations (add / remove / replace roster) on a specific resource (team reps), plus the adjacent settings it mutates (call_mode, lead_owner_routing). An agent can distinguish it from siblings like manage_team, delete_team and remove_user without opening any schema.

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

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

Gives clear usage context, including that the team_id must be obtained from get_settings with no arguments, and that reps are keyed by user_id. It does not, however, explicitly say when to prefer this tool over manage_team or remove_user, so the alternative-selection guidance is implicit rather than stated.

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