Vendo AI

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

With no annotations the description carries the full burden, and it does disclose the key behavioral risk: on an active campaign, REAL connection invites begin within the next cycles. It also notes the side effect of adding linkedin to the channels. Missing are reversibility (e.g., pause_channel to stop) and any error/idempotency behavior.

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

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

Three sentences, front-loaded with the action and consequence, each carrying real information. The first sentence is somewhat run-on and could be split for clarity, but nothing 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 2-param mutation tool with no annotations and no output schema, the description covers the action, the fallback for account_ids, the real-world consequence, and the approval prerequisite. Return-value explanation is unnecessary since no output schema exists.

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

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

The schema documents `id` fully, and the description compensates for the undocumented `account_ids` by stating "given (or selected/all connected) accounts", which conveys the default fallback. The word "selected" remains slightly ambiguous about where that selection originates.

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

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

States a specific verb+resource: queues the campaign audience for LinkedIn and adds LinkedIn to the channels. It is clearly the LinkedIn counterpart to activate_campaign_phone by naming the channel explicitly, though it doesn't draw that distinction in prose.

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

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

"Only after the user approved preview_activate_campaign_linkedin" is an explicit precondition naming the sibling preview tool, and "On an active campaign REAL connection invites start within the next cycles" frames when the effect is consequential. It stops short of naming exclusions (e.g., already-active channel) or contrasting with add_campaign_linkedin_account.

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 no annotations, the description carries the burden of disclosing risk. It clearly warns that calls are REAL, that credits are charged per call minute, and that preview approval is required. It stops short of explaining permissions, irreversibility, or behavior on insufficient credits, so it is strong but not exhaustive.

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 core action and cost warning. Every sentence adds distinct value: purpose, preview prerequisite, and pause 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?

The description covers purpose, cost, approval prerequisite, and pause routing, which is adequate for a high-risk mutation. However, with ten parameters at 10% schema coverage and no annotations or output schema, it omits parameter semantics and several safety details an agent would need.

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 10% (only id is documented), so the description should compensate for the ten parameters. Instead it defers with 'Same args as preview_activate_campaign_phone', which is a useful pointer but leaves timezone, call_objective, talking_points, phone_number_ids, max_calls_per_day, working hours, and max call duration unexplained.

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

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

States a specific verb, resource, and scope: scheduling REAL outbound AI calls to every audience contact with a phone number. It distinguishes itself from preview_activate_campaign_phone via the approval condition and names pause_channel as the control alternative.

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

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

Explicitly states the key precondition: use only after the user approved preview_activate_campaign_phone. It also names pause_channel channel=phone_call as the tool to use for pausing, giving a clear alternative 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?

With no annotations, the description carries the full burden and does well: it discloses the allowed formats, the 10 MB size cap, the two source modes (public URL or base64), the deferred effect at next script generation, and that the operation is free. It omits what the tool returns and whether there is a per-agent document limit.

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 with the material/accepted-formats/size constraint front-loaded and the lifecycle note second. Nothing is redundant and nothing needs to be re-read.

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 annotations and no output schema, the description supplies formats, size limit, source modes, timing of effect, and cost — enough to call it correctly. Missing pieces are minor: response shape and any cap on attached documents.

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 still adds real constraints the schema does not state — the whitelist of file extensions and the 10 MB maximum — which directly govern how filename/file_url must be populated. The URL-vs-base64 exclusivity is already in the schema, so no extra credit there.

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 (upload) plus resource (a knowledge material the agent learns from), with the accepted file formats enumerated. It is clearly distinct from remove_agent_document, but it does not differentiate itself from the related sibling generate_knowledge_from_url, leaving some ambiguity about which ingestion path to pick.

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 'Used the next time the script is generated (generate_agent_script)' tells the agent when the effect takes hold, which is useful timing context. However, there is no explicit when-to-use/when-not guidance and no mention of the alternative knowledge-ingestion tool (generate_knowledge_from_url).

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 no annotations, the description carries the full burden. It usefully discloses side effects — pending contacts are rebalanced and backfilled, invites start in next cycles, and no credits are consumed — but it omits permission requirements, reversibility, and behavior when the campaign or account is in an unexpected state.

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-load the core action and then add operational consequences and cost. Every sentence adds useful information without repetition.

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

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

For a mutation tool with no annotations and no output schema, the description covers the main side effects well. It is still incomplete regarding prerequisites, error cases, and any return/response expectations an agent might need before invoking it.

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

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

The schema documents 'id' as coming from list_campaigns but leaves 'account_id' undocumented. The description implies 'account_id' is a connected LinkedIn account, but does not state where to obtain valid account IDs or how duplicates are handled.

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

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

The description gives a specific verb and resource: add a connected account to a running campaign. It clearly distinguishes this as a campaign-account attachment operation, though it does not explicitly name alternatives such as connect_linkedin_account or remove_campaign_linkedin_account.

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 'running campaign' implies the campaign must be active, and the description notes that invites begin in later cycles. However, it gives no explicit when-to-use guidance versus connecting an account to the workspace, nor does it state prerequisites or exclusions.

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

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

With no annotations, the description carries the behavioral burden well: it discloses deduplication keys, silent skipping of duplicates and contact-less records, the return counts, and that no credits are consumed. Missing are permission/auth requirements and whether skipped rows are reported in detail.

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, front-loaded clauses with no filler; the limit, dedup rule, and return values each earn their place. Slightly compressed notation ("Returns added / skipped / total_contacts") is terse but readable.

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 summarizes the returned counts, which covers the main post-call concern. Combined with the dedup/skip rules, an agent has enough to invoke and interpret the result; only auth and error behavior are unaddressed.

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

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

Schema coverage is 50%, so the schema already documents the audience id (UUID) and contacts array. The description adds that email, linkedin_url and phone are the dedup identity fields and that the array is capped, but doesn't clarify how other fields (position, company_name) participate.

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 (append), resource (contacts to a custom audience), and an explicit cap of 5000. This clearly distinguishes it from delete/update contact siblings and from create_custom_audience.

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 word "append" implies adding to an existing audience, which nudges the agent away from create/upload flows, but it never names alternatives such as upload_custom_audience or update_custom_audience_contact, nor states prerequisites like the audience needing to exist.

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 no annotations provided, the description carries the full behavioral burden and does so well: it discloses the state transition, that outreach halts, that the record is hidden from default lists, that history remains readable via include_archived, and that the action is not reversible. Those are exactly the consequences an agent needs before triggering a 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?

Two sentences, zero waste, and the irreversible/state-change consequences are front-loaded before the approval gate. Every clause carries operational meaning.

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 mutation with no annotations and no output schema, the description covers effects, reversibility, and the required approval workflow. Nothing an agent needs to call it safely 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?

There is a single parameter and schema coverage is 100%, with the schema already saying it is a UUID from list_campaigns. The description adds no additional per-parameter meaning, so the baseline 3 applies; the mention of include_archived refers to a listing flag elsewhere, not to this tool's 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?

The description leads with a specific verb and resource ('Archive the campaign') and immediately states the resulting state change (status becomes completed, outreach stops, hidden from default lists). The contrast with a destructive delete is implicit but clear from 'history stays readable with include_archived', so an agent can tell this apart from delete_campaign without opening another 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 gives an explicit prerequisite chain: call preview_archive_campaign first and obtain the user's explicit approval. That is strong when-to-use guidance. It stops short of naming alternative siblings (pause_campaign, delete_campaign) or when-not-to-use conditions, which keeps it at 4 rather than 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?

With no annotations, the description carries the full behavioral burden and does the most important part: it discloses the credit spend rate (2 per contact), flags it as a mutation that copies contacts into the workspace, and imposes an approval precondition. It does not cover auth requirements, reversibility, or failure/refund behavior, but the critical cost and mutation facts are 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?

Three short sentences, front-loaded with the credit-cost warning so the highest-risk fact is read first. Every sentence earns its place; nothing is redundant with 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 one-parameter mutation with no output schema, the description covers the essentials an agent needs: cost, effect on the workspace, and the required preview/approval gate. The only meaningful gap is the undocumented 'id' parameter, but no return-value explanation is needed.

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

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

Schema description coverage is 0% and the single 'id' parameter is entirely undocumented in both schema and description. The tool name implies it is an audience set id, but the description never names or explains the parameter, so it fails to compensate for the coverage gap.

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

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

Specific verb (purchases) plus resource (the audience set) plus concrete effect (snapshots its contacts into the workspace). It also distinguishes itself from the sibling preview_buy_audience_set by casting that tool as the required prior step, so an agent can route between them 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?

States the exact condition that gates invocation: only call after the user reviewed preview_buy_audience_set output and explicitly approved the cost. This is an explicit when-to-use rule with a named prerequisite alternative, not an implied one.

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 no annotations, the description carries the full burden and does well: it discloses that the calendar event stays, that the action is irreversible ('No undo'), and that user approval is required. It omits authorization details and what a successful response looks like, but the core behavioral impact is clear.

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

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

Four short sentences, each adding distinct information. The key constraint (agent does not join, event stays) is front-loaded, followed by eligibility, irreversibility, and the required preview/approval step.

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

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

For a simple one-parameter mutation tool with no annotations and no output schema, the description covers behavior, preconditions, and irreversibility well. However, it leaves the agent without guidance on sourcing the required 'meeting_id', which is a notable gap given the empty schema description.

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

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

The schema has 0% description coverage for the single parameter 'meeting_id', and the description does not explain where to obtain it, what format it takes, or how it relates to tools like 'list_meetings'. The parameter name is self-descriptive, but the description adds essentially no semantic 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?

States a specific verb and resource ('cancel_meeting'), and clarifies the exact effect: the agent will not join, but the calendar event remains. This distinguishes it from deleting a calendar event, though it does not explicitly compare against the nearby 'remove_agent_from_meeting' sibling.

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

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

Gives clear preconditions: only scheduled meetings that have not started, and only after 'preview_cancel_meeting' and user approval. It says when not to use it (started or unscheduled meetings) but does not name alternative tools for adjacent scenarios.

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 no annotations the description carries the full burden, and it does disclose two real behavioral facts: the invite link stops working and admin permission is required. It does not say whether the invitation can be re-issued, what happens if the id refers to an accepted invitation, or what a failure looks like, so the mutation's edge behavior remains opaque.

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, zero filler, and the highest-value facts (what it does, the effect, the permission gate, the id source) are ordered front to back.

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 mutation with no output schema, the definition covers purpose, effect, permission gate, and argument provenance. The only real gap is error/edge behavior for non-pending or invalid ids, which is minor for a tool this narrow.

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% (id is documented as a UUID), so the baseline would be 3. The description adds value beyond the schema by stating the provenance of the id — get_workspace.pendingInvitations — which the schema does not, giving the agent a concrete path to a valid value.

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

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

States a specific verb and resource ('Cancel a pending invitation') and immediately clarifies the scope word 'pending', which separates it from remove_workspace_member or invite_workspace_member in the sibling list. The parenthetical effect makes the operation 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?

'Admins only' gives a hard precondition, and 'Invitation ids come from get_workspace.pendingInvitations' tells the agent exactly where to obtain the required argument in a large sibling set. It stops short of naming the alternative for removing an already-accepted member, but the pending-only framing covers most of the ambiguity.

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

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

With no annotations, the description carries the full disclosure burden. 'Nothing is sent' usefully rules out an outbound email, but it says nothing about permissions required, whether the close is reversible, whether it is idempotent, or what happens to queued AI replies -- all important for a 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?

Two short sentences with zero filler, leading with the action and following with the key consequence. Nothing is wasted and nothing important is buried.

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 mutation tool with no output schema, the description covers the action and one behavioral fact but omits the return value and the source of thread_id. It is adequate but leaves the agent guessing about where to get the id and what comes back.

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?

There is exactly one parameter, thread_id, and its schema description coverage is 0%. The description does not explain what a thread id is or where to obtain one (for example, from list_campaign_threads), so it adds no meaning beyond the bare schema.

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

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

The description states a specific verb and resource ('Mark the conversation closed') and clarifies the effect on the AI ('no more AI replies'). It is clear on its own, though it never names the sibling actions it is distinct from, such as takeover_campaign_thread or reply_in_campaign_thread.

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

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

'(no more AI replies)' implies the outcome an agent chooses this tool to achieve, but there is no explicit when-to-use guidance, no prerequisites, and no mention of the alternative tools (takeover, reply) that a reader must choose between.

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 no annotations, the description carries the full burden and does most of it: it warns that the app password transits the conversation, that the password is never returned, and — most importantly — that 'WARM-UP STARTS IMMEDIATELY' so the real mailbox will send and receive warm-up mail. It omits whether an existing mailbox is replaced, how to undo (disconnect_client_mailbox exists but is unnamed), and any failure/permission behavior.

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 highest-risk facts (own mailbox, app password through the conversation, warm-up starts immediately) before the reference data. Dense but every clause carries information; the all-caps emphasis is slightly noisy but functional rather than decorative.

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

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

For an 8-param, 6-required connection tool with no annotations and no output schema, the description covers credential format, security handling, host/port reference values, and the immediate side effect. Remaining gap is lifecycle context — replacement of an existing mailbox, reversibility, and what a successful call yields.

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

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

Schema coverage is only 13% (only 'password' documented), so the description must compensate and largely does: it explains the password must be an APP PASSWORD and supplies concrete smtp_host:port and imap_host:port values for Gmail and Outlook, covering four weakly documented required params. It adds little for 'email', 'from_name', or why 'provider' (the one enum) matters.

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 ('Connect') and a narrowly scoped resource ('the user's OWN mailbox for sending'), which separates it from connect_content_account, connect_google_meet and the auth-flow siblings. The 'OWN' qualifier also distinguishes it from reconnect/list/disconnect mailbox tools in the same family.

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?

'prefer asking the user to connect it in the app (Settings → Email Sending) unless they explicitly give you the password' gives an explicit preferred path, an alternative, and the exact condition that licenses this tool. That is the when-to-use-vs-alternative guidance an agent needs for a credential-handling tool.

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

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

With no annotations, the description carries the burden well: it discloses that the return value is a URL, that a human must open it in a browser, and that no connection exists until the user completes the flow — the key side-effect semantics for this tool. It omits link expiry/reuse, whether repeat calls invalidate earlier links, and any permission prerequisites, which are meaningful gaps for an OAuth-link endpoint.

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 return value and the human-in-the-loop constraint front-loaded. Every clause carries information an agent needs.

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 correctly explains what comes back (a hosted URL). For a 2-parameter tool this is nearly complete, with only link lifetime and repeat-call behavior left unspecified.

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

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

Schema coverage is 50%: redirect_path is documented in the schema while provider is only constrained by an enum. The description adds the mapping that provider is LinkedIn or Instagram, but contributes nothing about redirect_path behavior or whether other providers are supported, so it is roughly at 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 a specific verb and resource: it returns a hosted authorization URL for a LinkedIn or Instagram publishing account. The 'publishing account' framing and the human-in-browser requirement make it distinguishable from most siblings, but it never disambiguates against the near-named connect_linkedin_account, which an agent could easily confuse it with.

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?

'Give the link to the user; nothing is connected until they finish' gives clear operational context: this is step one of a two-party flow and the agent must hand off rather than attempt the connection itself. It stops short of naming alternatives (connect_linkedin_account, reconnect_* flows) or stating when not to call it, so it is not a full 5.

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

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

No annotations exist, so the description carries the full burden and does well: it discloses that the call returns (not completes) a URL, that a HUMAN must approve in a browser while logged in, a 20-minute expiry window, and that the connection finalizes server-side. It does not cover what happens if the window lapses or what error/auth states polling can return, hence not 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 sentence plus a short imperative follow-up; the return value and human-approval constraint are front-loaded, and every clause (20-minute limit, server-side completion, polling target, Kommo prerequisite) carries actionable 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 small, annotation-free tool with no output schema, the description supplies the return shape, the human-in-the-loop requirement, the timeout, the next tool to call, and a prerequisite — enough to invoke and drive it correctly. Only the failure/expiry path is left unspecified.

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

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

Schema coverage is 0%, but there is only one parameter and it is enum-constrained, so the schema largely self-documents. The description still adds provider-specific meaning by noting Kommo's save_kommo_credentials prerequisite while HubSpot has no such step.

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-result ('Returns an authorization URL') and resource (Kommo/HubSpot CRM OAuth connection), and makes the human-in-browser requirement explicit. An agent can immediately distinguish this from get_crm_integration, disconnect_crm_integration, and save_kommo_credentials among its many siblings.

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

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

Gives clear operational sequencing: hand the URL to the user, then poll get_crm_integration, and for Kommo call save_kommo_credentials first. It does not state the negative case (e.g. don't call if an integration already exists — check list_crm_integrations first), which is the only missing routing guidance.

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

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

With no annotations, the description carries the full burden and does well: it discloses auth requirements ('No Google login needed'), side effects ('Also saves the meeting settings'), and billing ('Free to connect; meeting minutes are billed'). It omits idempotency or behavior when the channel is already enabled, but the essential behavioral traits are surfaced.

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

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

Four tight sentences, front-loaded with the action and its return value, followed by operational and billing notes. Nothing feels bloated, though the 'Free to connect' clause is somewhat marketing-flavored.

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, but the description explicitly tells the agent what is returned (the invite address), and it covers auth, billing, and the settings-save side effect. For a 6-parameter setup tool the main remaining gap is the meaning of optional parameters, but overall an agent has enough to call it correctly.

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

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

Schema coverage is 67% and the description adds essentially no parameter-level meaning — it does not explain auto_join, greeting_message, meeting_mode, or join_before_minutes, and only vaguely gestures at 'meeting settings'. The schema does the work for the documented params, but the uncovered ones get no help.

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

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

The description uses a specific verb+resource ('Turn on the Google Meet channel') and states the concrete output (the agent's invite address). It is distinct from sibling tools like get/update_google_meet_settings or disconnect_google_meet, though it does not name any sibling explicitly, relying on the reader to infer the contrast.

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

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

It explains what to do with the result ('Invite that address to any Google Calendar event with a Meet link'), which gives workflow context. But it never states when to prefer this over the related settings, analytics, or disconnect tools, nor what to do if the channel is already connected; usage is implied rather than directed.

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 no annotations, the description carries the full burden and does it well: it discloses the human-in-the-loop requirement (a person must open a browser), that the tool cannot finish the connection, and that no account exists until the flow completes. It omits link expiry or permission requirements, keeping it short of a 5.

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

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

Three tight sentences, each earning its place, with the core behavior (returns a URL a human must open) front-loaded. 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 one-parameter, no-output-schema tool, this is essentially complete: it explains the return (a hosted URL) and the required follow-up action. It could note what happens after authorisation (e.g. where the account surfaces), but nothing needed 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% and the single optional campaign_id is documented in the schema, so the baseline is 3. The description adds no further detail about that parameter, but it doesn't need to given the schema does the work.

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

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

The description states a specific verb and resource: it returns a hosted URL to authorise a LinkedIn account, and clarifies why it cannot act on its own. It distinguishes itself implicitly from reconnect-style siblings by stressing that no account exists yet, though it does not name those alternatives explicitly.

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

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

It gives clear workflow guidance ('give the link to the user', 'cannot complete the connection itself') but never states when to choose it over reconnect_linkedin_account, disconnect_linkedin_account, or list_linkedin_accounts. Usage is implied rather than contrasted.

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 no annotations, the description carries the full burden. It does disclose the resulting behavior — all messages to the bot are answered by the agent — which is genuine value. But it omits permissions/auth requirements, idempotency or replacement semantics for an existing connection, and error behavior on an invalid token.

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 that front-load the setup steps and end with the effect of connecting. No filler, though it could be slightly more explicit about the id parameter without extra length.

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 mutation with no annotations and no output schema, the description covers the workflow and the post-connection behavior but leaves the 'id' parameter and the success/error outcome semantics unaddressed. Adequate but with clear gaps.

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

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

Schema coverage is only 50%. The description's token guidance ('gets the HTTP API token, and passes it here') largely restates the schema's own 'Telegram Bot API token from @BotFather' description, and the required 'id' parameter is never explained in schema or description. Little net meaning 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 a specific verb+resource (connect a Telegram bot) and describes the end-to-end setup flow, so the agent knows exactly what the call accomplishes. It is implicitly distinguished from siblings like disconnect_telegram_bot and get_telegram_bot_info, though it never names them.

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

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

The description gives useful prerequisite context: the user must first create a bot with @BotFather and obtain the HTTP API token before calling. However, it never states when to use this versus disconnect_telegram_bot or get_telegram_bot_info, nor what happens if a bot is already connected.

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?

No annotations exist, so the description carries the full burden and does well: it discloses that the operation is out-of-band (user must open a link and scan), that it links a REAL phone number, that it is asynchronous and must be polled to completion, and that it costs nothing ('Free'). That covers side effects, workflow shape and cost — the traits an agent most 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 compact sentences, front-loaded with the return value and the user action, then the polling step, then the precondition. Every clause carries distinct operational information; nothing is repeated from the title or schema.

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

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

With no output schema and no parameters, the description must supply return shape, user-side steps, completion check and cost — and it does all four. An agent can execute the whole flow from this text alone without opening another definition.

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

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

Zero parameters, so the baseline is 4; there is nothing the description could add. Its mention of the returned link is output information rather than parameter guidance, which is appropriate here.

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

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

States a concrete verb and artifact ('Returns a hosted link') plus the exact user action that completes it (scan QR code via WhatsApp Linked devices). It also names the real-world effect — linking an actual phone number to the workspace — which separates it from siblings like connect_telegram_bot or connect_linkedin_account.

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 gating: 'Only after preview_connect_whatsapp_account and the user's approval' names the required predecessor tool and the consent condition. It also names the follow-up tool (list_whatsapp_accounts) and the success state to poll for ('ok'), 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?

No annotations exist, so the description carries the full burden and does so well: it discloses that the agent starts in DRAFT, contacts nobody, that the credit check is performed but not charged, and the exact plan-limit failure mode. It still omits what the response returns (e.g., the new agent ID) and any permission/role prerequisites.

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

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

Front-loaded with the core action, then state, then constraints, then next steps — a sensible information order. It is dense but nearly every clause carries operational value; the 'like step 1 of the app's builder' analogy is the only slightly decorative phrase.

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 creation tool with no output schema and no annotations, this covers state, side effects, cost, failure mode, and follow-on calls. The one real gap is that it never tells the agent what object comes back, which matters since no output schema exists to compensate.

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 and the baseline is 3. The description adds genuinely new information: the default for purpose is 'sales', which the enum description never states, and it signals that avatar can be set later via set_agent_avatar_from_url.

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 ('Create an AI agent'), names the builder step it corresponds to, and enumerates the direction values with a default. An agent can distinguish this from duplicate_agent or update_agent 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?

Explicitly sequences the tool in a workflow ('Next: set_agent_company → generate_agent_script → channels') and routes plan-limit questions to get_agent_plan_limits. It does not say when to prefer duplicate_agent over creating from scratch, but the primary 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?

With no annotations, the description carries the behavioral burden and does so well: it discloses cost ("Free"), default behavior (new widgets get app defaults / Modern design), merge semantics for widget_config, and an important non-obvious side effect (a second widget for the same URL updates the existing one instead of creating a duplicate). It does not mention permission/auth requirements or what the call returns (connection object vs id), which is the remaining gap.

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

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

Front-loaded with the core action and then organized per type, with no filler sentences. The telegraphic style (arrows, semicolons, sentence fragments) is dense but every line carries a distinct rule; slightly more structure would make the type-by-type rules easier to scan.

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

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

For a 7-parameter, nested-object tool with no annotations and no output schema, the description covers the ambiguous decisions: which type to pick, which params matter per type, what happens on duplicate URL, and the follow-up call for embedding. What it lacks is the return value and any error/permission behavior, though the rich schema absorbs most of the parameter burden.

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 57% with heavy nested objects, so the description must compensate, and it does for the highest-value parameter semantics: it says website_url is required specifically for WEBSITE_WIDGET, optional for PRESENTATION_WIDGET, and unnecessary for WEBSITE_BUTTON, and it constrains design/voice settings by scenario. It adds little on the config sub-objects beyond what the schema already documents, so it is not a 5.

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

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

States the operation (add a channel/connection to an agent) and then spells out what each of the five enum types produces. It explicitly routes away from siblings (GOOGLE_MEET → connect_google_meet, PHONE_CALL → setup_phone_agent, Telegram → connect_telegram_bot, WhatsApp → connect_whatsapp_account), so an agent can tell this apart from every adjacent 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?

Gives per-type when-to-use rules and named alternatives for four channel types, plus the required follow-up step (get_widget_embed_code) and the styling split between WEBSITE_WIDGET and WEBSITE_BUTTON. It also states the interactive-card prerequisite (design "modern" in chat, screen_cards=true in voice), which is genuine decision guidance rather than description of the payload.

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 no annotations, the description carries the full burden and does well: it discloses that nothing is contacted until launch_campaign, that the operation is free (no credit spend), that ids are validated against the workspace, and that managed emailSenderMode requires a paid plan. It omits permissions requirements and what the response contains (e.g. the new campaign id), so not 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?

The critical facts (DRAFT, audience, agentId, branchId) are correctly front-loaded. However, the trailing run-on enumeration of thirty-plus setting names duplicates the schema and inflates the description without adding meaning, diluting the useful signal.

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

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

For a tool with nested objects, no output schema and moderate schema coverage, the description covers the hard prerequisites, the draft safety semantics and the cost profile. The main remaining gap is that it does not say what is returned or what to call next with the created id, though the DRAFT/launch framing implies it.

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

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

At 57% schema coverage the description partially compensates, and it does clarify the audienceId vs customAudienceId choice and that settings are all optional. But its long settings enumeration largely restates field names already documented in the schema, and several parameters (speedTier, trackLinks, stopOnNegative, clientEmailProvider) are never mentioned at all.

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 plus the resulting lifecycle state ("Create a classic campaign in DRAFT") and immediately distinguishes it from launch_campaign. An agent can tell this is the creation step, not the activation step, without opening any schema.

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

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

Gives explicit prerequisites: an audience via audienceId (from save_audience/list_audiences) OR customAudienceId of a READY list, an agentId, and branchId from crm_list_branches. It also names the AGENT_REQUIRED failure mode if agentId is skipped. It does not contrast with update_campaign for the modify case, but the create-then-launch flow is unambiguous.

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

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

No annotations are provided, so the description carries the full burden. It does add real behavioral value — the audience starts empty and ready, costs no credits, and is filled via a separate call — but it omits whether the name must be unique, what identifier comes back (which the follow-up call presumably needs), and any permission prerequisites.

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

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

A single front-loaded sentence with two trailing clauses, each of which earns its place (next step, alternative path, cost). No repetition of the title or name.

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 creation tool with no output schema, the description covers purpose, prerequisites, cost, and the follow-up call. The main gap is the return value (audience id), which the chaining instruction implies exists but never names.

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

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

Schema description coverage is 0% for the single required `name` parameter, so the description is the only source of semantics. It conveys that the audience is 'named' but adds no constraints or rules beyond the schema's own minLength/maxLength, which an agent could read directly.

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?

A specific verb plus resource ('Create an empty, named custom audience'), with initial state disclosed ('status ready'). It also names the two siblings it is not — add_custom_audience_contacts and upload_custom_audience — so the agent can separate it from them without reading 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?

Explicit routing: use this first then fill it with add_custom_audience_contacts; use upload_custom_audience when the source is a file. The condition that selects the alternative is stated outright, 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?

With no annotations, the description carries the full burden. It does contribute two useful behavioral facts: the 20-active-link cap and that the call returns code and url. It omits permissions/auth, what happens when the cap is hit, and whether label is optional, leaving real gaps for a 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?

Two compact sentences, front-loaded with the action and followed by the constraint and return shape. 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 low-complexity tool with one optional parameter, the description covers purpose, a hard limit, and return values in lieu of an output schema. The main residual gap is the optionality of label and any auth requirement.

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 label parameter is fully documented with an example in the schema, so baseline is 3. The description adds nothing about the parameter, including that it is optional (0 required params), missing an easy opportunity.

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

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

The description states a specific verb and resource ('Create a new tracked referral link') that an agent can readily distinguish from update_referral_link and get_referral_overview. It stops short of explicitly naming the sibling boundary, but the create/update split is self-evident.

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

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

There is no explicit when-to-use guidance, no alternatives named, and no prerequisites beyond the incidental '(max 20 active)' note. The cap at least signals a precondition under which the call will fail, which is implied usage rather than stated 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?

With no annotations provided, the description carries the full burden and discloses important behavioral traits: the page is private and unlisted, the operation is idempotent in that it returns the existing page instead of duplicating it, only the creator can perform it, and it is free. It does not describe the return format, expiration, or lifecycle of the test page, 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?

The description is three short sentences with the action front-loaded and no wasted text. The authorization and cost notes are compact and each earns its place by adding operational context.

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 creation tool with full schema coverage and no annotations, the description covers the key context: privacy, idempotency, permission constraints, cost, and intended pre-deployment use. The main gap is that it does not say what the returned test page resource looks like, since no output schema exists.

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 required parameters are already well documented in the input schema with their source tools (list_agents and list_agent_connections). The description adds no parameter-specific detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description gives a specific verb and resource: create or return an existing private, unlisted test page with the website widget installed. It clearly explains the purpose (trying a widget before adding it to a real site), but does not explicitly distinguish this from sibling tools such as get_widget_embed_code.

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

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

It states clear usage context: use this to try the widget before adding it to a real site, and only the agent's creator can do it. It does not name alternatives or when-not-to-use conditions, but the intended scenario is evident.

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 no annotations, the description carries the full behavioral burden and it does disclose the one non-obvious side effect: mentioned users receive a CRM notification. It omits whether the comment is editable or deletable afterwards, whether the acting user's identity is recorded, and any permission requirements for commenting on a lead.

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, with the essential visibility constraint and the notification side effect front-loaded. Nothing is padding.

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

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

For a three-parameter comment-creation tool with no output schema and no annotations, the description covers who sees it, what side effect fires, and where mention ids come from. The main remaining gap is the return value or confirmation behavior, though with no output schema the agent can tolerate that.

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

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

Schema coverage is only 33%, so the description has to compensate, and it does: it explains that mentions must be user ids obtained from crm_list_workspace_members, which is more actionable than the schema's bare "User ids to @mention". The 'id' parameter is only implied by "lead card" and 'body' semantics are only sketched by "internal note", keeping it below a 5.

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

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

"Internal team note on the lead card (not visible to the lead)" states a specific verb and resource, and the visibility qualifier separates it from lead-facing siblings like crm_reply_to_lead and crm_send_email_to_lead. It stops short of naming a sibling outright, so an agent must infer the boundary rather than being told 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?

The "not visible to the lead" clause implies the internal-versus-external channel choice, and pointing at crm_list_workspace_members as the source of mention ids is genuinely useful routing. But there is no explicit when-to-use or when-not-to-use statement, and the comment-versus-reply decision is left 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?

No annotations exist, so the description carries the full burden, and it delivers the two traits that matter most for a mutation: the operation is additive (existing pipeline memberships survive) and it is reversible via a named tool. It omits permissions/authorization needs and undefined edge behavior (lead already in that branch), 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?

Two sentences, no filler, and the add-vs-move distinction is front-loaded in the first clause. Every phrase ('too', 'entry stage', 'stays in its current ones', 'Reversible via...') carries distinct information.

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

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

For a 3-parameter mutation with no annotations and no output schema, the description covers the essential semantics an agent needs to call it safely. Remaining gaps: no return-value indication and no statement of what happens on a duplicate add — modest for such a narrow operation.

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%: id, branch_id (with the 'general' or crm_list_all_branches guidance) and assignee_user_id (with its default) are all documented in the schema. The description's 'entry stage' adds context about where the lead lands but says nothing extra about any of the three parameters, 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+resource (place the lead in another pipeline) plus the critical scope qualifier ('too') and the entry-stage position. It explicitly contrasts with the sibling crm_move_lead_to_branch, so an agent can distinguish the additive tool from the moving one 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?

The word 'too' plus 'it stays in its current ones' tells the agent the use-case: additive assignment rather than relocation. It also names crm_move_lead_to_branch as the reversal path, giving an alternative. It does not state a negative rule (e.g. use move instead when the lead should leave its current pipelines), so it falls short of a full 5.

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

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

With no annotations, the description carries the full burden and does a solid job: it declares the tool read-only, free (no credits), and discloses that contact emails/phones are masked unless the caller holds the 'crm-contact-details' permission. It omits pagination behavior, default ordering and whether counters are lifetime or windowed.

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

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

Four short sentences, front-loaded with what a card is, followed by scope, permission masking and cost. Each sentence adds distinct information; the only mild inefficiency is the conversational parenthetical about CRM leads, which nonetheless serves a differentiating purpose.

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

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

With no output schema, the description must convey the return shape, and it does at a high level: one card per campaign/SDR search with outbound counters. For a one-parameter read tool this is nearly sufficient; only the result-field details and pagination semantics are absent.

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

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

The schema has 0% description coverage on its single parameter, and the description never mentions 'limit' at all — no default, no maximum, no effect on the result. The description therefore does not compensate for the undocumented 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 states the resource precisely: one card per campaign and per SDR search, carrying outbound counters. The parenthetical contrasts it with 'CRM leads', which contains only repliers, so an agent can tell the two lists apart. It lacks an explicit verb but the listing intent is unambiguous from the first sentence.

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 contrast with CRM leads ('everyone contacted, whether or not they replied') implicitly tells the agent to use this tool when it needs the complete outbound stream rather than only responding leads. However, it never states when NOT to use it, and does not route to the many other plausible siblings such as crm_communication_history, crm_communication_thread or sdr_outreach_summary.

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 no annotations, the description carries the full burden. It usefully discloses 'Read-only, free', which is real behavioral context (mutability and cost). But it omits pagination behavior and return-shape expectations for an 8-param history endpoint.

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

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

Two compact sentences, front-loaded with the core purpose and scope. Minimal waste; the id prerequisite is placed after the main statement, which is sensible.

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

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

For an 8-parameter tool with no annotations and no output schema, the description covers purpose, filtering, and read-only/free status but omits limit/offset semantics and return format. Adequate but with clear gaps against the complexity.

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

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

Schema coverage is only 38%, so the description must compensate. It maps to channel, replied, and date (from/to) filtering, and implies type via 'campaign or SDR search', but leaves limit and offset entirely undocumented and adds no syntax/format detail.

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

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

States a specific verb+resource ('Every outbound touch for one campaign or SDR search') plus its filter dimensions, which is clear and actionable. It distinguishes itself from crm_communication_cards by naming it as the id source, though it does not explicitly differentiate from crm_communication_thread or crm_get_conversation.

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 prerequisite workflow ('Use crm_communication_cards first to get the id'), which is genuinely useful guidance. However, it offers no when-to-use vs-when-not guidance against the related thread/conversation siblings, leaving the choice 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?

With no annotations, the description carries the full burden and discloses two valuable traits: "Read-only" (safe, no mutation) and "free" (no credit cost). Beyond that it says nothing about message ordering, pagination, thread-length limits, or what a 'complete thread' returns, which leaves meaningful behavioral gaps for a read 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?

Two compact sentences, front-loaded with the core purpose and followed by the key-sourcing prerequisite and safety/cost note. No redundant restatement of the name or 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 and no annotations, so the description must do more. It covers `key` sourcing and cost/safety but leaves two required parameters (id, type) unexplained and gives no sense of the return shape or volume for a potentially large thread.

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

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

Schema description coverage is only 33%: only `key` is documented. The description usefully expands on `key` by naming its form (email address or LinkedIn chat id), but `id` and the required `type` enum are never mentioned in either schema or description, so the agent gets no guidance on those required inputs.

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

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

States a specific verb+resource: retrieve the complete message thread with one contact. This distinguishes it from the sibling crm_communication_history (which yields rows and the `key`), though the phrase "inside a card" is vague and adds little. An agent can identify the operation without opening the schema, but sibling differentiation is only implicit.

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 useful prerequisite: `key` comes from a `crm_communication_history` row, implying this tool is used as a follow-up drill-down. However, there is no explicit when-to-use vs when-not guidance, and the id/type parameters are not framed as selection 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?

With no annotations, the description carries the full burden and covers several non-obvious traits: default stages are auto-created as a side effect, the operation is restricted to workspace admins/owner, and it consumes no credits. It omits what happens on duplicate names, whether the new pipeline is returned with its id, and reversibility (though a sibling delete_crm_branch exists).

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

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

Four short, telegraphic sentences with zero filler; the core action comes first, then visibility semantics, permissions, and cost. Every clause carries distinct information.

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

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

For a two-parameter mutation with no annotations and no output schema, the description covers the crucial gaps: permission gate, side effects, cost, and visibility model. The only thing an agent might still want (whether the created branch/id is returned) is unaddressed, but no output schema exists to imply it.

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

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

Schema coverage is 50%, so the description meaningfully compensates by explaining that member_user_ids controls visibility and that the General pipeline stays open to all users. The `name` parameter is left unstated, but its constraint (1-120 chars) is already in the schema and its meaning is self-evident.

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 ('Create an isolated pipeline (team / direction / client)') and clarifies the branch/pipeline naming ambiguity, which is the main confusion risk in this tool family. It does not name a sibling it differs from (e.g., crm_create_stage for adding stages, crm_update_branch for changes), so it falls short of maximum 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?

'Workspace admins/owner only' gives a prerequisite, and 'General stays open to all' hints at when member_user_ids matters. However, there is no explicit guidance on when to create a new pipeline versus using an existing one, nor any pointer to sibling tools such as crm_create_stage or crm_update_branch.

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 no annotations at all, the description carries the full burden and does meaningful work: it declares this is a write operation, that it costs no credits, and that it has no external side effect (no invites sent). It stops short of permissions, conflict/overlap behavior, or what is returned, so it is strong but not complete.

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, zero filler, and the core action is front-loaded ahead of the constraints. Every sentence contributes a distinct fact (what it does, its cost/nature, its lack of side effects).

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 unannotated create tool with no output schema, an agent still needs to know whether the created event's identifier is returned (so it can later update or delete it) and how lead_id changes behavior — neither is addressed. The cost and no-invites notes cover the most important gaps, leaving a middling but adequate result.

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 57% (title, all_day, and description are undocumented), and the description adds nothing about any of the seven parameters — not even that lead_id is how you attach the event to a CRM record. At this coverage level the description should compensate and it 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 and resource ("Add a custom event to the CRM planner") and implicitly separates itself from meeting/invite tools by noting it only records on the internal calendar. It does not name its closest siblings (crm_update_calendar_event, crm_delete_calendar_event, crm_list_calendar_events), so the differentiation is inferential rather than explicit.

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

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

The sentence "Does NOT send invites to anyone" gives one useful exclusion, steering agents away from this when they need to actually invite attendees. However, no positive trigger conditions, no prerequisites, and no named alternative (e.g. use crm_update_calendar_event to modify an existing event) are provided.

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 no annotations, the description carries the burden and does disclose the key traits: no deduplication, and the visible side effect that a card appears on the customer board. It does not cover failure modes (validation of email/phone, permission errors) or whether creation triggers integrations, which keeps it off 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, front-loaded with the action, then the field rule, then the dedup routing, then the side effect. No filler and nothing buried.

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 13-parameter, zero-annotation, no-output-schema create tool, it covers purpose, intake minimum, dedup alternatives, and visible effect. Remaining gaps are modest (whether a lead id is returned, validation behavior) but real for a mutation 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 only 46%, so the description must compensate, and it does the most valuable part: a cross-field constraint ('ALL fields optional … at least one of name/company/title/email/linkedin/phone') that no single schema property expresses. It still leaves notes, avatar_url, and branch_ids semantics to the schema, so it does not fully close the gap.

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

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

A specific verb-plus-resource ('Add a lead card to the entry stage of the chosen pipeline(s)') that names the exact object and where it lands. It is immediately distinguishable from crm_import_leads and crm_promote_contact_to_lead, which it explicitly points to.

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

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

States the alternative paths and the condition that selects them: bulk or deduplicated intake goes to crm_import_leads, converting an existing contact goes to crm_promote_contact_to_lead. It also spells out the create-time minimum (at least one of name/company/title/email/linkedin/phone), which is the practical gate on calling 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that the new column is inserted before terminal stages and explains is_terminal for Won/Lost-like end stages, but it omits authorization requirements, duplicate-name behavior, and what happens to existing leads or stage ordering.

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 and front-loaded, stating the operation first and then adding key semantic details. The branch clause largely repeats the schema description, which is a minor 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 mutation tool with no annotations and no output schema, the description covers the core operation and terminal-stage behavior but leaves several gaps: how the target pipeline is identified (only branch is mentioned), permissions, failure modes, and return value are not described.

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 50%, so the description must add meaning. It explains is_terminal as "Won/Lost-like end stages" and clarifies branch values/default, while color is simply described as optional hex, consistent with the schema.

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

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

The description states a specific verb and resource: "Add a custom kanban column to a pipeline." It is clear that this creates a pipeline stage, but it does not explicitly distinguish itself from siblings such as crm_update_stage, crm_reorder_stages, or crm_delete_stage.

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

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

There is no explicit guidance on when to use this tool versus alternatives like crm_update_stage or crm_reorder_stages. The description implies it is used to add a stage, but this is largely evident from the name and title, not from usage guidance in the description.

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 no annotations, the description carries the full burden and does well: it discloses that this destroys no history, needs no preview step, and cannot be undone. These are exactly the behavioral traits an agent needs for a destructive call. It stops short of stating permissions or what happens if the id is not found, so not 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 short sentences, front-loaded with the core action, then the distinguishing traits. Every clause earns its place with no waste.

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

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

For a one-parameter destructive tool with no annotations and no output schema, the description covers the salient behavioral risk (irreversible, no history impact) but leaves the parameter completely undefined and omits any permission or error context. Adequate but with clear gaps.

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

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

Schema description coverage is 0% and the single required id parameter is documented nowhere. The description says nothing about what the id identifies or its format. With one parameter at 0% coverage, the description should compensate and 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 (remove) and resource (a custom calendar event), and explicitly distinguishes itself from deleting a lead or a stage. An agent can tell it apart from crm_update_calendar_event or delete_crm_lead 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?

Implies when to use: it's a direct delete with no preview step needed, unlike lead/stage deletes. But it never names a specific prerequisite or a when-not condition, and the sibling set includes a preview_delete_crm_lead and preview_delete_crm_stage but no preview tool for this one, so the guidance is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses the budget/rate cost, warns against bulk looping, and flags that any returned email is an UNVERIFIED pattern guess keyed to email_confidence=pattern_guess. It does not cover auth requirements or failure behavior on invalid/non-profile URLs.

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 returned fields, then the email caveat, then the cost warning. Every sentence adds information an agent needs and none 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?

With no output schema, the description usefully enumerates the return fields and the confidence semantics of the suggested email, plus the budget cost. What is missing is any note on invalid-URL handling or how the unverified email should be treated downstream.

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

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

Schema description coverage is 0% for the single parameter, so the description must compensate, and it does by specifying the expected URL shape (linkedin.com/in/...). It could still clarify whether only profile URLs are accepted or whether company URLs are rejected, but the format guidance is meaningful.

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?

It states a specific verb and resource ('Fetch ... for a linkedin.com/in/... URL') and enumerates exactly which fields come back (name, title, employer, avatar, location). This leaves no ambiguity about what the tool produces, though it never names a sibling it should be chosen over (e.g. sdr_get_person_detail).

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

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

It gives concrete invocation constraints that function as usage guidance: the call costs one profile view from the workspace's shared daily LinkedIn budget and should not be looped over large lists. It stops short of stating when to prefer this over the SDR person-detail siblings, so it is clear context without explicit 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?

With no annotations, the description carries the full burden; 'Read-only' is the single most important disclosure for this tool and it is made clearly. It does not cover failure behavior for a missing id, permission requirements, or whether the default flag has side effects, so the disclosure is thin beyond the read-only statement.

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

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

Front-loaded with the access pattern, then the return fields, then the safety note; no filler. The phrasing 'One pipeline by id' is slightly elliptical but readable.

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, non-destructive read with no output schema, the description gives the lookup key, the projected fields, and the read-only nature. Only error/permission behavior is absent, which is a minor gap at this complexity level.

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 schema already documents the single 'id' parameter as a UUID. The description's 'by id' adds nothing beyond that, so the baseline of 3 for fully-documented parameters 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 retrieval action ('One pipeline by id') and enumerates the returned shape (id, name, is_default), which separates it from crm_list_branches and crm_list_all_branches by implying single-record lookup. It stops short of naming those siblings explicitly, and the branch/pipeline terminology swap between name and description adds minor friction.

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?

'By id' implies the precondition of already holding a pipeline id, which is sufficient context to pick this over the list tools. There is no explicit when-to-use statement, no exclusion of alternatives, and no note on what happens if the id is unknown.

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?

No annotations are provided, so the description carries the full burden. It does declare 'Read-only', which is genuinely useful safety context, and mentions the channel coverage. But it says nothing about pagination, truncation, empty-thread behavior, or return shape for a tool whose whole purpose is fetching a potentially long thread.

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 tight sentence that front-loads the resource and appends the channel list and the read-only tag. No wasted words; slightly dense parenthetical but efficient.

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

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

For a simple one-parameter read tool with no output schema, the description covers the resource and channels, which is the minimum viable content. It still omits what the id refers to and how the thread is returned, so 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 coverage is 0% and the description never explains the single 'id' parameter—whether it is a lead id, a conversation id, or something else. With one undocumented parameter, the description does nothing to compensate for the schema gap.

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

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

States a specific verb (get) and resource (full message thread with a lead) and enumerates the possible source channels. However, it fails to distinguish itself from very close siblings like crm_communication_thread, crm_communication_history, and crm_communication_cards, which leaves real ambiguity about which conversation tool to pick.

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

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

No guidance on when to use this versus the multiple other communication-related siblings (crm_communication_thread, crm_communication_history, crm_get_lead, crm_reply_to_lead). The agent is left to infer the routing condition entirely on its own.

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?

No annotations are provided, so the description carries the full burden, and it does supply the key safety trait 'Read-only'. However, it discloses nothing beyond that — no behavior on missing/invalid IDs, no auth or scope requirements, and no note on whether the record must exist — leaving most behavioral questions open for an unannotated 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?

A single tight sentence that front-loads the payload ('Full lead card:') followed by a compact field list and a trailing 'Read-only.' No wasted text, though the parenthetical quip about source is slightly loose.

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

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

For a simple single-record get with no output schema, the field enumeration usefully substitutes for a return-value spec, which is a real contribution. But with no annotations and no output schema, the missing id semantics and error behavior leave the definition adequate rather than 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 0% and the sole parameter (id) is never mentioned, so the description adds no meaning beyond the schema. The agent must infer that 'id' is the lead identifier from the 'Full lead card' phrasing alone.

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

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

The description states a clear resource ('Full lead card') and enumerates the returned content (identity, source, company enrichment, activities, comments, assignments), so the agent knows this fetches rich detail for a single lead. It does not explicitly differentiate from the sibling crm_list_leads, relying on the title's 'one' to convey the single-record scope.

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

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

There is no when-to-use guidance, no prerequisites, and no named alternative such as crm_list_leads or crm_get_conversation. Usage is only weakly inferable from the field enumeration.

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?

No annotations are provided, so the description carries the full burden; it does at least self-declare 'Read-only', which is the most important safety signal. It says nothing about behavior for a lead with no pipelines, whether archived/closed pipelines are included, or what happens if the id is invalid.

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

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

Two compact sentences, zero filler, with the return content front-loaded and the read-only note trailing. Nothing is redundant with the title or schema.

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

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

For a single-parameter read tool with no output schema, describing the returned fields (stage, owner per pipeline) is close to sufficient. Minor gaps remain around empty results and pipeline scope, but nothing an agent would likely get wrong when calling it.

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

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

There is a single required parameter and schema description coverage is 100% ('Lead id (UUID)'), so the schema fully documents it. The description adds no extra semantics about the id beyond what the schema states, 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-resource pair: returns every pipeline (branch) a lead sits in, plus stage and owner per pipeline, which also disambiguates the 'branches' naming in the tool name. It does not name sibling alternatives such as crm_get_lead or crm_list_branches, so an agent still has to 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?

There is no explicit when-to-use framing, no exclusion (e.g., use crm_get_lead for lead fields, crm_list_branches for all pipelines in the workspace), and no prerequisites. The usage is only implied by the phrase 'a lead currently sits in'.

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 no annotations, the description carries the full behavioral burden and does a solid job: it declares the operation read-only, explains the return payload structure (base64 content plus name and mime type), and discloses the 5 MB size ceiling. It stops short of covering auth, not-found behavior, or response size implications, but it adds meaningful context beyond 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?

One sentence, front-loaded with the return format, then the size constraint, then the read-only trait. Every phrase supplies information an agent would want, with no repetition or 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 two-parameter read-only getter with a fully described input schema and no output schema, the description is nearly complete: it explains the return shape, limit, and safety profile. The only meaningful omission is workflow context, such as pointing to crm_list_lead_documents for finding document IDs.

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 both parameters are fully documented as UUIDs in the schema. The description adds no further parameter meaning beyond the implied relation that document_id identifies the file. Baseline 3 is appropriate when the schema already does this work.

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

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

The description states a specific action and result: it returns a lead document's file as base64 along with name and mime type. That clearly separates it from upload/list/delete document siblings, though it does not explicitly name any sibling or say 'download a single document by ID.'

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 one concrete usage constraint: files up to 5 MB are supported, and larger files must go through REST. However, it does not explain when to call this versus crm_list_lead_documents, nor does it mention how to obtain the required document_id. Usage guidance is implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does disclose two meaningful traits: it is read-only (safe, non-mutating) and free (no credit cost). It stops short of stating any auth/permission requirements, but for a no-argument read tool this is solid coverage.

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, front-loaded with the core action and the cost/safety note in a compact trailing clause. No filler; every phrase adds information.

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

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

For a simple, parameterless read tool with no output schema, the description gives enough to act: what it returns at a high level (the notify_* toggles) plus read-only and free. It could note permissions or the shape of the settings object, but nothing essential is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly introduces no parameter semantics, and there is nothing for the schema to document beyond an empty object.

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

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

States a specific verb (Read) and resource (CRM settings) and adds a concrete detail: the notify_* toggles controlling email/notification events. Clear on its own, though it never names the sibling crm_update_settings to explicitly draw the read-vs-write contrast.

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

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

Usage is only implied — an agent infers you call this to inspect settings. There is no explicit when-to-use, no mention that crm_update_settings is the counterpart for changing them, and no prerequisites given.

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?

Since no annotations are provided, the description carries the full burden of disclosure. It successfully communicates the import limit (1000 rows), the deduplication mechanism, the update semantics, and the cost ('No credits').

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 highly concise, fitting complex operational logic (limit, deduplication, update behavior, cost) into three dense sentences without filler. The information is front-loaded and easy to scan.

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

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

Given the lack of annotations and the complexity of bulk lead processing, the description is extremely complete. It addresses failure modes (skipped/updated/created reasons) and limitations (1000 row limit) that the structured fields do not capture.

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

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

The schema coverage is only 50%, and the description primarily lists the field names without adding semantic context to the majority of the nine input fields. While it mentions the target 'pipelines (entry stage)', the parameter details remain largely reliant on the schema alone, meeting the baseline but not exceeding it significantly.

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 purpose is clearly stated: 'Import up to 1000 parsed rows as leads into the chosen pipelines (entry stage).' This specific phrasing distinguishes it from single-lead creation tools.

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

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

The description explicitly details the deduplication strategy ('Dedup by email/phone') and the critical update logic ('blank fields filled (never overwritten)'), which serves as a vital guideline for how the agent should expect the data to behave during execution.

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 no annotations, the description carries the disclosure burden and does state 'Read-only', which is the key safety signal for this tool. It also discloses the returned fields. It stops short of mentioning ordering, completeness/limits, or auth requirements, which keeps it from a 5 for an unannotated 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?

One compact sentence: the resource and scope come first, then the sibling comparison, then the intended consumers, then the safety note. Nothing is wasted and nothing important is buried.

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

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

For a zero-parameter read-only listing tool with no output schema, the description supplies everything needed to call it correctly: what it returns, why it exists versus its sibling, where to use the result, and that it is non-mutating.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter meaning the description needs to add. The mention of returned fields is redundant with the eventual response but not harmful.

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 concrete resource (every pipeline of the workspace) and enumerates the returned fields (id, name, is_default), and explicitly positions it against the sibling crm_list_branches as the wider variant. An agent can distinguish it from crm_list_branches and crm_get_branch without opening any schema.

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

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

It names the exact downstream tools that consume the result (crm_add_lead_to_branch / crm_move_lead_to_branch), so the selection condition is stated rather than inferred. It also explains why this variant is preferred over crm_list_branches, effectively covering the alternative.

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 no annotations, the description carries the full burden and does well: it declares the tool read-only and enumerates the exact return fields (id, name, is_default, member_user_ids), including the "General" default marker. It omits any note on auth/permissions or whether an empty list is possible.

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 ordered definition → return shape → usage, each earning its place. The parenthetical "(teams / directions / clients)" is slightly cryptic but acts as a quick synonym gloss.

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

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

For a zero-param list tool with no annotations and no output schema, the description supplies the missing return-value information and the downstream call pattern. Only the differentiation from crm_list_all_branches is left uncovered.

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

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

The tool takes zero parameters, so the schema baseline is 4. The only parameter-like guidance (passing branch=<id> or "general" downstream) is useful context for the follow-up calls rather than this one.

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 defines the resource precisely ("isolated pipelines inside one workspace") and lists the fields it returns, which makes the operation unmistakable. It does not explicitly distinguish itself from the close sibling crm_list_all_branches, so an agent must infer that one is workspace-scoped and the other cross-workspace.

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?

"Call before crm_stats / crm_list_leads when the user has more than one branch, then pass branch=<id>" gives explicit ordering, a precondition, and the follow-up action. No exclusion is stated against crm_list_all_branches or crm_get_branch, so the sibling routing is incomplete.

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?

No annotations were provided, so the description carries the full behavioral burden. It usefully declares 'Read-only, free', but omits pagination, ordering, and what happens when the optional from/to dates are omitted (0 required params). Adequate but incomplete for a no-annotation 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?

Two tight sentences: the core purpose is front-loaded and the caveat about SDR windows follows. No wasted phrasing and 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 read-only list tool with no output schema, the description covers purpose, safety profile, and the key routing caveat. Return shape and pagination are left unstated, but the essentials an agent needs to call it correctly are present.

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

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

Schema description coverage is 100%, so both parameters (from/to ISO dates) are already documented. The description only references 'a date range' generically and adds no syntax or format detail beyond the schema, so the baseline of 3 is appropriate.

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

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

States a specific verb (List) and resource (custom calendar events) with scope (CRM planner, date range) and even names the event types (meetings, reminders). This lets an agent distinguish it from sibling calendar tools like crm_create_calendar_event or list_google_meet_meetings 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 concrete routing rule: SDR sending windows shown in the UI calendar should be read via sdr_get_search instead, delimiting what this tool does not return. It stops short of stating when-not-to-use it versus the other CRM calendar tools, but the alternative is explicit for the main ambiguity.

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

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

No annotations are supplied, so the description carries the behavioral burden. It does disclose the read-only nature and enumerates the returned fields, which is genuinely useful given the absent output schema, but it says nothing about pagination, result limits, or permission requirements on the lead.

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

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

One sentence for content plus a two-word behavioral flag, both front-loaded with zero filler. Every element earns its place.

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

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

For a simple one-parameter read tool with no output schema, the description is largely sufficient: it names the return fields and states the operation is read-only. Only minor gaps (ordering, pagination, permissions) remain, which are low-stakes for this 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?

There is a single parameter with 100% schema description coverage ('Lead id (UUID)'), so the schema fully documents it. The description adds no meaning beyond that, which matches the baseline 3 for high-coverage schemas.

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

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

States the resource ('Files attached to a lead card') and pre-empts the return shape by listing fields (id, name, type, size, uploader, date). The list action is only implied by the tool name rather than the description, and it doesn't explicitly name the singular sibling crm_get_lead_document, 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?

There is no when-to-use guidance, no mention of the alternative crm_get_lead_document for fetching a single file, and no prerequisites such as required lead access. The agent must infer usage entirely from the name and the phrase 'attached to a lead card'.

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?

No annotations are provided, so the description carries the burden. It does disclose two important traits: the operation is read-only, and omitting branch means 'all branches visible to the user' (permission scoping). However it says nothing about result ordering, pagination behavior, or default page size, which matter for a 10-param list tool with a 200 limit.

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

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

Front-loaded with purpose, then a compact filter enumeration, then a behavioral note and usage hook. Dense with facts and free of filler; the parenthetical value sources earn their space.

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 10 params, no annotations and no output schema, the filter semantics are well covered. The remaining gap is the response shape — what a lead row contains and how pagination/order behaves — which the description leaves entirely implicit.

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

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

Schema coverage is only 40%, but the description compensates well: it names the value source for branch and owner, explains the omission default for branch, and clarifies q searches name/company/email. Only limit/offset lack added meaning beyond their integer bounds, but that is a small residual gap.

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

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

States a specific verb and resource ('List leads in the CRM pipeline') and immediately scopes it with the filter set, which cleanly separates it from single-lead siblings like crm_get_lead and from crm_list_stages / list_narrator_leads. An agent can pick this tool 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?

Provides real usage context: 'Read-only' plus 'Great first call for "who replied to me?"' tells the agent this is a broad entry point. It also routes the agent to crm_list_branches and crm_list_workspace_members for valid filter values. It stops short of explicit exclusions (e.g. use crm_get_lead for a single lead), so not 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?

With no annotations, the description must carry the behavioral burden. It does disclose two useful traits beyond the schema: the operation is read-only and incurs no cost. It omits return shape, ordering, or pagination, but for a zero-arg read-only list the disclosure given is reasonable.

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 clauses, front-loaded with the core purpose and followed by usage and the read-only/free traits. Nothing 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 zero-arg, read-only list tool with no output schema, the description covers purpose, usage, and cost/safety profile. It could say a bit more about what fields come back since there is no output schema, but it is largely complete.

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

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

The tool takes zero parameters, so there are no parameter semantics to explain; baseline for 0 params is 4. The description correctly implies no input is required.

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

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

States a clear verb+resource ('List the LinkedIn accounts connected to this workspace') so the agent knows exactly what is returned. However, the sibling 'list_linkedin_accounts' is near-identical, and the description does nothing to distinguish the two, which is the main clarity gap.

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?

Implied usage is given ('Useful to see which account owns a conversation'), which hints at when to reach for it. But there is no explicit when/when-not guidance and no mention of how it relates to the confusingly similar 'list_linkedin_accounts' sibling.

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?

No annotations are provided, and the description steps up: it declares read-only and free (cost/safety), discloses the hard 50-item window, and states that total and unread counts are returned alongside the list. It stops short of stating the ordering guarantee or what happens when more than 50 exist, which is the only remaining behavioral gap.

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

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

Three short sentences, each doing distinct work: what it returns, how to filter, and where to go instead. The differentiating content is front-loaded 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, the description correctly spells out the return shape (latest 50 items plus total and unread counts), and with no annotations it supplies the safety and cost profile. 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 0%, so the description must carry the single boolean, and it does: unread_only=true returns only unread notifications, implying the unfiltered default otherwise. The default value itself is never stated outright, which is the only shortfall.

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 CRM notifications), names the notification types covered, and explicitly delimits itself from the sibling list_app_notifications. An agent can pick it out of a very crowded namespace 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 an explicit routing rule: app-bell notifications (billing, meetings, invitations) belong to list_app_notifications, not this tool. It also explains the one filtering option's effect (unread_only=true returns only unread), so usage and alternatives are both covered.

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

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

With no annotations, the description carries the full burden and does disclose that the tool is read-only and returns ordered stages. It also explains that stages are per-branch, which is important behavioral context. It stops short of permissions, pagination, or error behavior, but for a simple read-only list this is substantial transparency.

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 definition is front-loaded with the resource and scope, then branch semantics, then safety and workflow guidance. Every sentence contributes useful information without repeating the schema verbatim.

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

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

There is no output schema, so the description appropriately lists the returned fields and the ordering. For a single-parameter read-only list, this is nearly complete; only minor operational details such as failure modes are absent.

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

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

Schema coverage is already 100%, but the description adds meaning by explaining that every branch has its own stages and that the branch value comes from crm_list_branches. It also reinforces "general" as the default, which helps an agent choose the parameter correctly.

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

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

The description states exactly what is returned: ordered kanban columns for ONE pipeline, with field names (id, name, color, is_terminal). It also distinguishes this from branch listing by making the ONE-pipeline scope explicit, so an agent can tell it apart from crm_list_branches or crm_list_all_branches.

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 use case ("Call before moving leads") and explains how to choose the branch parameter, including the default. It does not explicitly state when not to use it or name a direct alternative for stage lookup, but the workflow 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 no annotations, the description carries the burden, and 'Read-only, free' usefully discloses that the call has no side effects and no cost — a real addition. It says nothing about pagination, result ordering, or permissions, so it is only partially transparent for a no-annotation 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?

Two short sentences, zero filler, with the scope constraint front-loaded before the read-only/free note. Nothing is wasted and nothing is buried.

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

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

For a zero-parameter read tool with no output schema, the description covers what is listed, the scope of the workspace, and the cost/safety profile. Only the return shape is unaddressed, which is a minor gap given the tool's simplicity.

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

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

The tool takes zero parameters, so the schema has nothing to explain and the description has no parameter semantics to add. Baseline 4 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 AI agents in this workspace) and narrows scope with 'that CRM leads can be attributed to', which meaningfully separates it from the broader list_agents and list_agents_with_stats. It stops short of explicitly naming those siblings, so the agent must 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 clause 'that CRM leads can be attributed to' implies the use case (attributing CRM leads to an agent) but gives no explicit when-to-use, when-not, or named alternative such as list_agents. Usage is inferable 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?

No annotations are provided, so the description carries the burden — and it delivers the two most decision-relevant traits: 'Read-only' (safe, non-mutating) and 'free' (no credit cost). It does not describe the shape of each member record returned, which is the remaining gap for a listing tool.

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

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

Three short sentences, zero filler, and the ordering is right: what it lists, then the cross-tool workflow reason, then the read-only/cost caveat.

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

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

For a zero-param, no-output-schema tool with no annotations, the description covers purpose, safety profile, cost, and workflow placement — everything an agent needs to call it correctly. Only the return-field detail is left implicit.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description adds useful scope context anyway (members eligible to own leads).

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 (workspace members), and narrows scope with 'who can own a CRM lead' — a meaningful qualifier that distinguishes it from other list_* tools like list_agents or crm_list_workspace_agents.

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

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

Explicitly routes the agent: 'Use before `reassign_crm_lead` to get valid owner ids.' This names the dependent sibling tool and the condition that selects it, so the agent knows not just when to use it but why.

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?

No annotations are provided, so the description carries the full burden. It does disclose the side effect (badge cleared, all items read), which is useful, but it omits reversibility, whether the operation is workspace-wide, and any auth/prerequisite context for a 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?

A single efficient sentence with no filler, front-loading the effect. Slightly indirect by leading with the badge outcome rather than the action, but appropriately sized for the operation.

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

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

For a zero-parameter bulk mutation with no output schema and no annotations, the description conveys the action and its visible result. It could still note scope and irreversibility, but it is adequate for a tool this simple.

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

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

The tool takes zero parameters, so the schema has nothing to describe and the baseline of 4 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 ('marking ... read') and resource ('everything'/notifications) plus the observable effect (clearing the notification badge). The bulk scope distinguishes it from the singular sibling crm_mark_notification_read, though that sibling is never named explicitly.

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

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

The phrase 'marking everything read' implies bulk use versus the single-item sibling, so the usage context is inferable, but there is no explicit when-to-use/when-not-to-use guidance or named alternative.

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 no annotations provided, the description does carry the burden, and it does disclose two useful traits: this is a write operation and it costs no credits. However, it omits whether the call is idempotent, what happens if the notification is already read, and any permission requirements.

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, front-loaded with the action and followed by the cost/side-effect note. No filler, though the brevity is close to under-specification rather than economical conciseness.

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

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

For a trivial one-parameter mutation with no output schema and no annotations, the description covers the action and the credit/cost profile, which is roughly the minimum viable. It leaves the id's origin and the already-read behavior unspecified.

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

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

Schema description coverage is 0% and there is one required parameter, 'id', whose meaning the description never clarifies (notification identifier? which scope?). At low coverage the description is expected to compensate, and it 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 (mark read) and resource (CRM notification), and the qualifier 'single' implicitly contrasts with the crm_mark_all_notifications_read sibling. It stops short of naming that sibling explicitly, so differentiation requires a small inference.

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

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

No when-to-use guidance and no routing to crm_mark_all_notifications_read or crm_list_notifications is given. The word 'single' hints at the alternative but the description never states the condition that selects this tool over the bulk variant.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Reversible' is useful, but it does not say whether moving triggers notifications, automation side effects, required permissions, or what happens to existing stage history.

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 sentence pair: operation, routing key, id source, and reversibility. No filler; front-loaded.

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

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

For a 2-param mutation with no annotations and no output schema, the description covers the core action and id sourcing but omits side effects, permissions, and parameter formats that an agent would need to call it confidently.

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

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

Schema coverage is 0% and neither param is described in the schema. The description clarifies that stage_id is a stage identifier sourced from crm_list_stages, and that id is the lead, but does not state the format (integer/UUID) or that both are required strings.

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

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

States a specific verb + resource ('move a lead to a different pipeline stage') and the routing key ('by stage_id'). Distinguishes itself cleanly from crm_update_lead (full edit) and crm_reassign_crm_lead (ownership change).

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 prerequisite helper (get ids from crm_list_stages), which is the key when-to-use context. Does not explicitly exclude crm_update_lead for the same operation, so it falls short of 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?

No annotations exist, so the description carries the full burden. It usefully discloses that the operation is reversible and that the destination stage defaults to the entry stage, which is real behavioral context. It does not cover permission requirements, whether the lead remains in the source branch, or what the response contains.

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 compact sentence with the core action and the to_stage_id override parenthetically attached. Nothing is wasted and the key behavior is front-loaded.

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

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

For a 5-parameter mutation tool with no annotations and no output schema, the description covers the essential mechanics but leaves gaps: side effects on the source branch, assignee_user_id, and error/permission behavior. 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 coverage is 80%, so the baseline is 3, and the description genuinely adds meaning: it explains that to_stage_id is optional and defaults to the destination's entry stage, which the schema does not state. The only undocumented parameter, assignee_user_id, is left unexplained in both places.

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

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

The description names a specific verb (move) and resource (lead) and scopes it to branch/pipeline transfer, which separates it from stage-only movement. It stops short of explicitly naming how it differs from close siblings like crm_add_lead_to_branch or crm_move_lead, so it is clear but not fully differentiated.

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

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

The description implies the use case (taking a lead out of one pipeline and putting it into another) but never states when to pick this over crm_add_lead_to_branch, crm_move_lead, or reassign_crm_lead. With several near-identical siblings in the toolset, this omission forces the agent to infer the 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?

With no annotations, the description carries the full burden and does disclose the most important trait: it sends nothing, it only shows recipient, subject and body as they would be sent. It does not mention whether the lead must exist, whether validation errors are raised, or any permission requirements, but the critical safety profile is stated clearly.

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 dry-run framing and ending with the imperative workflow rule. No filler.

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

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

There is no output schema, but the description compensates by saying the preview shows recipient, subject and body exactly as they would be sent. Combined with the safety statement, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 75% and the schema already documents id, to (with its default) and body. The description only restates that recipient, subject and body are echoed, adding little beyond the schema and nothing about the one undescribed parameter (subject). 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 (dry-run preview of an email to a lead) and explicitly frames it as the non-sending counterpart to crm_send_email_to_lead. An agent can distinguish it from the send tool and from the many other preview_* siblings 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 an explicit directive — 'ALWAYS call first and show the draft to the human' — plus the alternative it precedes (crm_send_email_to_lead). The when-to-use condition is unambiguous and even encodes the required human-in-the-loop step.

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 no annotations, the description carries the full burden, and it delivers the key non-obvious traits: idempotent dedup behavior, the exact return shape { lead_id, already_existed }, the target stage (New), and zero credit cost. It omits permissions and whether the source communication row is mutated, but discloses the most decision-relevant behavior.

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 purpose and followed by dedup result, identifier requirement, and cost. 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 8 params, no annotations, and no output schema, it covers the return shape and identifier precondition well. But the majority of optional input fields go unexplained and permission/mutation side effects are unaddressed, leaving meaningful gaps for a multi-param mutation 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 only 13%, so the description should compensate, and it does partially by declaring the 'at least one of email/linkedin_url/phone' constraint that the schema itself does not encode (required is empty). The remaining five params (title, avatar_url, company_name, contact_name, assigned_user_id) are left undocumented.

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

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

States a specific transformation: turn a Communications-stream person (crm_communication_history row) into a CRM lead in the New stage. Naming the source explicitly separates it from the generic crm_create_lead sibling, so an agent knows it is promoting an existing contact rather than creating one cold.

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 real precondition ('Needs at least one of email / linkedin_url / phone') and cost context ('No credits'), which guides invocation. However, it never explicitly contrasts with crm_create_lead or states when this is preferred over that sibling, leaving the choice largely 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?

With no annotations, the description carries the full burden. It does disclose two important traits -- the call is a full replacement of ordering, and it is reversible -- but says nothing about required permissions, what happens if a stage id is omitted or duplicated (beyond the constraint), or the failure mode.

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

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

Two front-loaded sentences; the operation and its scope come first, followed by the id-sourcing constraint and the reversibility note. No filler.

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

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

For a two-parameter tool with no output schema and no annotations, the description covers scope, replacement semantics, reversibility, and how to obtain inputs. Only permission/error behavior is missing, which is a modest 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, and the description earns extra by adding semantics the schema does not: every stage id must appear exactly once, must belong to the same branch, and the ids should be sourced from crm_list_stages.

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 ("Set the full left-to-right order of one pipeline's stages") and scopes it to a single pipeline/branch, which distinguishes it from crm_update_stage, crm_create_stage, and crm_move_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?

Tells the agent where the ids come from (crm_list_stages with the same branch) and that the call applies to the whole workspace. It does not explicitly state when not to use it versus crm_update_stage, but the context needed to invoke it 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?

With no annotations, the description carries the full burden and does so well: it flags that a real external message is sent from the customer's own account (irreversible external side effect), discloses a state change (lead moved to 'Manager Dialog' stage), and imposes a human-approval gate. These are exactly the behavioral facts an agent needs before mutating state.

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 waste, and the highest-stakes information (this sends a real outbound message) is front-loaded, with the approval warning last. 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 mutation tool with no annotations and no output schema, the description covers the external side effect, the internal state change, and the approval prerequisite. It omits failure/error behavior and whether repeated calls resend the message, which would fully close the loop.

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?

Two required parameters with 0% schema description coverage, so the description must compensate. It implies the 'text' parameter ('the drafted text') but says nothing about the 'id' parameter's expected format or source, leaving half the parameters undocumented. It adds marginal but incomplete meaning beyond the bare 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 (sends/reply), resource (LinkedIn message or email reply to a lead), and scope (their source channel, from the customer's own account). The explicit 'REAL outbound message' framing distinguishes it from read-only or note-adding siblings like crm_add_comment and crm_get_conversation.

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 an explicit prescriptive precondition: 'ALWAYS show the drafted text to the human and get approval BEFORE calling this.' That is strong when-to-use guidance. It stops short of naming alternative tools (e.g., crm_add_comment for non-outbound notes) or when-not-to-use cases, 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?

With no annotations, the description carries the load well: it discloses the sender identity, that replies route to the user's own address, that the action is logged on the card, and the required permission — far beyond the name. It stops short of stating irreversibility/that a sent email cannot be recalled, or what happens on delivery failure, which matters for an external side-effecting action.

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 irreversible character of the action, then the operational constraints. No filler; every clause (sender, reply routing, permission, precondition) carries decision-relevant information.

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