LinkedNav

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavior: it runs validation checks before activating and returns the updated campaign status. It does not explain the downstream irreversible effect (launching outreach) that destructiveHint implies, 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?

Three short sentences, front-loaded with what the tool does, followed by preconditions and the return value. No filler, no repetition of the title, and each sentence carries distinct information.

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

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

There is no output schema, and the description compensates by stating that the updated campaign status is returned. Combined with the precondition list and full parameter coverage in the schema, an agent has what it needs to call this correctly; only failure behavior when validation rejects is unstated.

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

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

Schema description coverage is 100% and both parameters are documented there, including the conditional requirement on linkedinConnectionId. The description only alludes to the LinkedIn account via its validation sentence and adds no syntax, format, or default information, so the schema is doing all 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 uses a specific verb pair and resource ("Start or resume a LinkedNav campaign"), which is far more informative than the title alone and naturally separates it from pause_campaign, create_campaign, and delete_campaign. However, it never explicitly contrasts itself with those siblings, so it lands at clear-but-undifferentiated rather than top-tier.

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

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

It gives real context for invocation: use it to start or resume a campaign, and it discloses the preconditions that gate success (LinkedIn account, prospect/post count, subscription limits). There is no explicit when-not guidance or named alternative, which keeps it short of a 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is already covered. The description usefully adds that contacts must be 'existing' and identified by ID, plus the 50-item ceiling, but says nothing about partial-failure behavior or permission requirements. It adds some context over annotations but not rich behavioral 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?

A single tight sentence with zero filler, front-loaded with the verb and scope. Every clause (bulk, up to 50, by IDs, one call) carries 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 2-parameter write tool with full schema coverage, annotations, and no output schema, the description is essentially sufficient. The only minor gap is that it doesn't disambiguate against the singular add_lead_to_campaign sibling, which an agent might otherwise hesitate between.

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 both parameters (campaignId, contactIds) are already documented, including the 1–50 bound. The description's 'by their IDs' and 'up to 50' largely restate the schema rather than adding format or constraint detail beyond it. 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 (Add), resource (contacts), and scope (up to 50, by IDs, in one call). The 'bulk' / 'up to 50' / 'in one call' phrasing implicitly distinguishes it from the singular add_lead_to_campaign sibling, though it does not name that sibling explicitly.

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

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

Usage is implied: the 'bulk / up to 50 / one call' framing signals this is the batch alternative to add_lead_to_campaign, but the description never names the alternative or states when to choose it over a single add. No exclusions or prerequisites are 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true. The description adds real behavioral context beyond them: creating via profileUrl performs contact-creation-in-one-step, overrides are content-only and do not alter which stages fire, and overrides are ignored when adding by contactId. That is meaningful side-effect and scoping disclosure the annotations don't provide.

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

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

Three sentences, front-loaded with the primary action, then the two input paths, then override semantics. Every clause carries load — the parenthetical 'content-only; the campaign still decides which stages fire' prevents a plausible misinterpretation.

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 should stand on its own for input semantics, which it largely does for a mutation tool. It covers creation side effects, override scoping, and path selection; it stops short of stating auth/permission requirements or return shape, but the essential call-time guidance is present.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds value by clarifying the mutually-exclusive relationship between contactId and profileUrl (either/or) and the conditional applicability of the override parameters, which helps the agent disambiguate the 14-parameter surface beyond the per-field schema text.

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

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

States a specific verb and resource ('Add a single lead to a campaign') and implicitly distinguishes itself from the bulk sibling add_leads_bulk_to_campaign via 'single lead'. An agent can immediately tell what this does and how it differs from the batch variant.

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 conditional routing between the two input paths: 'Provide either a contactId... or a LinkedIn profileUrl + name', and explicitly scopes when overrides apply ('only ... when creating via profileUrl'). It does not name the bulk alternative as an exclusion, but the context for using this tool is unambiguous.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes far beyond them, disclosing skip-and-report behavior via `rejected`, intra- and cross-campaign de-duplication, plan caps, InMail double-send skipping, campaign resumption, and character clamping. This is exactly the behavioral context annotations cannot carry.

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

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

The key constraint (which URL form each send mode requires) is front-loaded, but the block is very dense and repeats override semantics that the schema already documents verbatim (customMessage, customSubject, customFollowUp2/3). Several sentences do not earn their place against the structured fields.

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 accepts the full burden and covers resolution rules, rejection reporting, dedup, caps, and overrides. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretation the schema lacks — how the three sources combine, why providerId is needed for InMail, and how overrides relate to messageSettings.template. It loses a point for restating several per-field semantics already spelled out in the nested schema.

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

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

States a specific verb and resource — 'Add recipients to a MESSAGE campaign — the people it will DM' — and immediately anchors it against the sibling add_lead_to_campaign for outreach. An agent can distinguish it from add_lead_to_campaign, add_post_targets, and add_monitor_targets 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 names the three combinable input sources (urls, contactIds, listId) and conditions each on campaign send mode, including the managed-session exception. It also routes the agent onward to check_inmail_open_profiles, giving genuine when-to-use 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 annotations only declaring readOnlyHint=false, destructiveHint=false and openWorldHint=true, the description carries real extra burden: URL validation rules, in-campaign AND cross-campaign de-duplication on the same LinkedIn account, per-campaign caps, credit/free-allowance economics, and the side effect that adding to a completed campaign resumes it. These are behavioral traits the annotations cannot express.

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

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

Front-loaded with the action and target type, then constraints, then cost. The paragraph is long but nearly every clause carries a distinct constraint; the credit-economics sentence is the softest, though still relevant to whether the call will succeed.

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

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

Covers mode restriction, validation, de-duplication, caps, cost, and the resume side effect — thorough for a two-parameter mutation with no output schema. It stops short of saying whether a partially invalid URL list fails the whole request or is filtered, which is the one decision an agent might still 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 100%, so both parameters and the 1–200 bound are already documented, establishing a baseline of 3. The description reinforces the /in/ vs /company/ URL shape and the 'not a post URL' rule but adds no syntax or format detail beyond the schema.

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

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

States a specific verb (add) plus the exact resource (LinkedIn profile/company URLs as monitor targets) and the campaign mode it applies to. It explicitly positions itself relative to siblings by calling itself 'the monitor-mode analog of add_post_targets', so an agent can discriminate it from add_post_targets, add_message_targets and remove_monitor_targets 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?

Provides a clear precondition ('Only comment campaigns created in monitor mode are supported') and a scope-escalation path ('create another monitor campaign to watch more'). It does not explicitly route the agent to alternatives for the non-monitor case (e.g. add_post_targets or add_message_targets), which is the only gap.

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

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

Annotations only declare it is a non-read-only, non-destructive, open-world mutation. The description goes well beyond that: exact accepted URL patterns and the profile-URL rejection, de-duplication both within the campaign and across the account's other comment campaigns, plan-based per-campaign caps, and the resume-completed-campaign behavior. These are exactly the side effects and constraints an agent needs before calling.

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

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

Front-loaded with the action and target, then layered validation, de-dup, caps, and resume behavior in one dense paragraph. Sentence count is low relative to information delivered, though the parenthetical analog and the long validation clause make it slightly heavy 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 3-param mutation with no output schema, it covers validation, de-duplication, plan limits, and the resume side effect. It leaves open what happens to an invalid or duplicate URL (hard error vs. silently skipped) and what the call returns, which is a minor but real gap for a batch operation accepting up to 200 URLs.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema — including the URL format list, which the description largely repeats. The description does add cross-campaign de-dup and plan-cap semantics for urls, but never mentions the watcher parameter's meaning or interaction. Per the high-coverage baseline, a 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?

Specific verb+resource ('Add LinkedIn post URLs to a COMMENT campaign') with scope stated immediately ('the posts it will auto-comment on'). It explicitly differentiates from siblings by framing itself as the comment-campaign analog of add_lead_to_campaign, and rules out profile URLs — an agent can place it against add_message_targets/add_monitor_targets 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 a clear when-to-use condition ('Only comment campaigns are supported') and names the outreach counterpart add_lead_to_campaign as its analog, plus a notable side effect (adding to a completed campaign resumes it if under the active-campaign limit). It stops short of explicitly routing the agent to remove_post_targets or the message/monitor target variants, so it is clear context rather than full when/when-not coverage.

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

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

Annotations already establish readOnly/non-destructive, and the description layers on substantive behavioral detail: results are judged against benchmark ranges, sample-size guards flag unreliable rates as insufficient-data, and promptComparison.best is the proven winner. This is real context beyond the safety profile.

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

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

A single dense paragraph, front-loaded with the tool's identity and trigger conditions before the return-value detail. It is long, but each clause carries selection-relevant information rather than filler.

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

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

With no output schema, the description carries the burden of describing return values and does so thoroughly (funnel rates vs benchmarks, weekly trends, segment breakdowns, guarded prompt comparison, bottleneck stage, prioritized recommendations). Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented, including the key nuance that funnel totals are lifetime while only the weekly trend honors the days window. The description adds no additional parameter meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource (expert analysis of outreach performance) and explicitly distinguishes itself from siblings: 'not raw stats' and 'For ranking the actual PEOPLE to contact, use analyze_pipeline instead.' An agent can select this over analyze_pipeline or get_performance_analytics 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?

Enumerates the triggering questions (how things are going, why results look that way, what to improve, best segment/industry, best prompt/message) and names the alternative tool for a related-but-different job. Both when-to-use and when-to-use-something-else are explicit.

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

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

Annotations only declare it is a safe, closed-world read. The description adds rich behavior beyond that: it discloses the ranking basis (AI-assessed conversion likelihood + ICP fit), the exact sections returned (waiting-on-reply, gone-quiet, warm bench, drafted-reply count), and that every row carries its evidence. With no output schema, this detail is essential and present.

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

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

Front-loaded with the primary scoping and intent examples, and every clause carries substantive content. It is dense and slightly run-on, but there is little genuine 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 read-only analysis tool with no output schema, the description fully covers what is returned and how to act on it. Nothing an agent needs to call and interpret 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 description coverage is 100%, so the schema already documents limit, campaignId, and minIcpScore. The description references ICP fit and the 'ICP 8+' warm bench, which loosely aligns with minIcpScore, but it adds no explicit param syntax or mapping. 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 (ranks) and resource (the actual PEOPLE/opportunities to act on), and the all-caps 'DEAL-CLOSING VIEW' frames its distinct purpose against siblings like analyze_performance or analyze_relationship. An agent can tell it apart 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?

Explicitly names the user intents it answers ('who are my hottest/highest-ICP leads', 'help me close deals') and routes downstream actions to named siblings (get_unibox, send_unibox_reply, get_pending_replies). This is a clear when-to-use with 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?

Annotations already cover the safety profile (readOnlyHint, destructiveHint false, openWorldHint), and the description adds substantial operational context beyond them: the ~20s LinkedIn re-sync latency, the daily caching rule when a prior re-sync found nothing, and the meaning of conversationCheck:'unverified'. These are real behavioral traits an agent cannot infer from structured fields.

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

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

It is front-loaded with a clear opening clause, and most clauses carry genuine information. However, the entire definition is a single run-on sentence with deeply nested parentheses (the conversation/InMail clause), which impairs parsing and makes the informative caveats hard to extract on a quick 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?

With no output schema, the description must describe returns, and it does list the output fields (connection, invite, conversation, reply ownership, recent posts, next action). Latency and edge-case semantics are covered, but the response format/shape and how to read each field's values remain somewhat 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 description coverage is 100%, so both parameters are already documented in the schema. The description only restates the required input ('Pass the person's profile URL') and says nothing about connectionId or which sender's relationship gets analyzed. Baseline 3 is correct when the schema carries the semantics.

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

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

States a specific verb and resource ('analyze your relationship with ONE person') and enumerates exactly what it returns: connection status, pending invite, conversation/InMail, who owes a reply, recent posts, and a suggested next action. This makes it clearly distinguishable from siblings like get_conversation, get_linkedin_connection, or get_recent_posts, which each cover only a slice.

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 positions itself as 'the one call to make before writing a personalized message or deciding how to follow up,' which gives a clear usage trigger. It also names an alternative behavior (get_conversation with refresh:true) for forcing a re-sync, but does not state when NOT to use this tool or how it compares to composing the individual sibling calls.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=true, so the write/irreversible profile is partly covered. The description usefully clarifies that approval queues the comment rather than posting it immediately, but it does not explain the destructiveHint=true consequence (public irreversible posting) or any auth requirements, leaving the most important behavioral trait undisclosed.

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

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

A single front-loaded sentence with no filler, which is good. It is arguably too terse for a mutation tool, but there is no wasted prose.

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

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

For a mutating, irreversible-flagged tool with 0% parameter coverage and no output schema, the description omits the editedComment contract, what happens after approval, and any post-approval behavior. An agent cannot call this confidently without guessing at the edit path.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden and does not. Crucially, it never mentions that editedComment lets the caller modify the AI text before approval — arguably the most important semantic of this tool — leaving both parameters undocumented.

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

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

States a specific verb (approve) and resource (AI-generated LinkedIn comment) plus the effect (queue to be posted), which distinguishes it from the reply-oriented siblings like approve_pending_reply. It does not explicitly name alternative tools, but the resource noun does the differentiation work.

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

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

The description gives no when-to-use guidance: nothing about the relation to get_pending_comments, deny_pending_comment, update_pending_comment, or retry_pending_comment, and no prerequisites (e.g., a connected LinkedIn account is needed to queue a post). Usage is only inferable from the tool name.

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

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

Annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) already flag this as a mutating outward action, and the description usefully adds that the reply is queued for real sending plus the optimistic-concurrency safeguard ('never sent unseen'). It omits what happens on a version mismatch or the error surface, 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?

Two sentences: the action first, then the one parameter that needs explanation. No filler, and the safety rationale is attached directly to the parameter it governs.

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-param mutation tool with annotations covering the safety profile and no output schema, this is close to complete. The remaining gap is the unmentioned editedMessage parameter and unspecified behavior when expectedVersion no longer matches.

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

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

Schema description coverage is 0%, so the description must carry the load, and it explains expectedVersion very well by tying it to the draft's `version` from get_pending_replies. However pendingReplyId is left bare and, more importantly, the optional editedMessage (maxLength 8000) is never mentioned, so the ability to approve with edits is invisible.

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 ('Approve an AI-generated LinkedIn reply') and the resulting effect ('queue it to be sent'). This implicitly separates it from deny_pending_reply, update_pending_reply, regenerate_pending_reply and approve_pending_comment, but none of those siblings are named, so differentiation is left to the reader.

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

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

Usage is implied by the approval action and the guidance to pass expectedVersion, but the description never states when to choose this over deny_pending_reply, update_pending_reply, or regenerate_pending_reply. No exclusion conditions or prerequisites (e.g., account connection state) are 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?

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds value beyond them: it discloses the return shape (a 0-100 score plus gaps framed as what/why/how/action with the exact fixing tool call) and the intended workflow (read-only; apply fixes with the named tools after confirming with the user). That workflow and output detail is real added context.

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

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

Front-loaded with the tool's essence, then dimensions, then triggers, then read-only workflow. Three well-formed sentences that each carry information. The 'EXPERT SETUP REVIEW' lead-in is slightly promotional, but it does not waste much 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?

No output schema exists, and the description compensates by describing the return (0-100 score, gap list with what/why/how/action), the read-only constraint, and the follow-up path. For a single optional-parameter audit tool, nothing an agent needs to call it correctly is missing.

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

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

Only one parameter (setupId) with 100% schema coverage, and the schema already documents the key behavior ('Omit to audit the active setup'). The description adds nothing about the parameter, so the schema carries the full load, which matches the baseline-3 rule for high coverage.

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

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

States a specific verb ('grades'/'expert setup review') and resource (the AI setup), and enumerates the concrete dimensions graded: business-context completeness, ICP precision, goal wiring, message/sequence assets, and the LinkedIn sender. It is clearly distinct from campaign-oriented audit siblings, but it never names or contrasts with the closest siblings (full_audit, diagnose_campaign, get_account_health), leaving that differentiation to 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?

Gives explicit triggers: 'when the user asks to review/improve their setup, when results are weak, or before going live.' That is clear context for invocation. However, it offers no when-not guidance or named alternative (e.g., full_audit vs. this), so the agent must still guess which audit tool to reach for.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond the schema: the 500-contact ceiling and the hard requirement that confirm be true — the schema only shows confirm's default of false, not that it must be set. It still omits whether deletion is permanent or cascades to campaigns/lists, 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, no waste, with the destructive scope and the confirmation precondition front-loaded. 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 2-parameter destructive bulk tool with no output schema, the essentials (scope limit, confirm requirement) are present, and annotations carry the safety hint. However, it does not say whether deletions are irreversible or what side effects occur (campaign membership, list membership), which matters for a bulk destructive call.

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

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

Schema description coverage is 0% for both parameters. The description recovers the semantics of confirm (must be explicitly true, not just the default false) but adds nothing about contactIds beyond the maxItems already in the schema, and nothing about ID format or validity. Partial compensation for a real 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?

States a specific verb and resource ('Delete ... contacts') plus a batch scope ('up to 500') and a qualifier about the active setup, so an agent can distinguish this bulk operation from the singular delete_contact sibling. It does not explicitly name the single-delete alternative, so it falls 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?

The description gives one real prerequisite ('Requires confirm: true') and implies bulk context, but never states when to choose this over delete_contact or bulk_move_contacts, nor any exclusion conditions. Usage is implied rather than guided.

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

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

Annotations already declare this is a write operation (readOnlyHint=false) that is not destructive and not open-world, so the safety profile is covered externally. The description adds useful scope context ('up to 500', 'active setup'), but omits what happens to the source-list membership, whether the move is atomic, and conflict handling for contacts already in the destination list.

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

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

A single tight sentence with the constraint and destination front-loaded and no filler. It is efficient, though its brevity is also what leaves behavioural and usage questions unanswered.

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 output schema, the description covers the essentials but not the consequences: nothing says contacts are removed from the source list or what the result contains. Adequate, but an agent would still be guessing about side effects at the 500-contact boundary.

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%: listId is documented in the schema, while contactIds carries only maxItems/minItems constraints. The description partially compensates by restating the 500-contact cap and the destination-list semantics, matching the baseline of 3 for a schema that does most of the work.

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

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

States a specific verb ('move') and resource ('contacts') plus scope ('up to 500', 'to another list'), so the operation is unambiguous. It does not differentiate itself from near-neighbours like bulk_delete_contacts, update_contact, or add_leads_bulk_to_campaign, so it stays below 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?

No when-to-use or when-not-to-use guidance is given. An agent gets no help deciding between this, update_contact (single-contact list change), or the bulk add/enrichment siblings, and no prerequisites are stated.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so safety profile is covered. The description adds a genuinely non-structured behavioral requirement — that confirm must be true — which is a mandatory confirmation gate the agent would otherwise miss (the schema only shows confirm with default false and no doc).

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

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

Two short sentences, action first, hard requirement second. No filler; every clause carries information the 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?

For a two-parameter mutation with no output schema, the description plus destructive annotations cover the essentials: what it does, what state it targets, and that confirmation is mandatory. The only missing piece is the provenance/format of taskId.

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

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

Schema coverage is 0% for both parameters, so the description must compensate. It does clarify that confirm must be set to true (a semantic constraint beyond the bare boolean), but it says nothing about taskId — where it comes from or its format. Partial compensation only.

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

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

States a specific verb (Cancel) and resource (background task) and narrows scope to tasks in 'pending or retrying' state, which distinguishes it from retry_task and get_tasks. It stops short of naming the sibling it is not, so it misses the top band.

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 state qualifier ('pending or retrying') implies when the tool applies, but there is no explicit guidance on when to cancel versus retry_task (a close sibling) and no when-not condition or prerequisite ownership note. Usage is inferable but not stated.

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

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

Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent with the described writes in mode 1. The description goes well beyond them, disclosing batching (up to 20), the account-safety rationale of one LinkedIn profile view per check, that answers are saved on the recipient, the free/no-credit nature, and the daily retry 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-loaded with the core purpose before the mode details, and nearly every sentence carries operational value. It is dense and semicolon-heavy, and the final suggestion about remove_message_targets is slightly tangential, but there is little wasted text.

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

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

There is no output schema, yet the description explains the relevant return signals (remainingUnchecked, stop) and where results are persisted (recipient openProfile). Given the tool's complexity, the definition supplies everything an agent needs to invoke and continue it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: campaignId target selection is PENDING FIRST and saves results, profileUrls behaves differently with vs without campaignId, and senderConnectionIds affects source preference. It stops short of syntax details, but adds real behavioral context over the schema.

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

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

States a specific verb+resource (check which InMail recipients are LinkedIn open profiles) and defines the domain-specific term (people who accept InMail for free). It clearly differentiates its two modes and its function from siblings like get_message_targets and remove_message_targets, so an agent can recognize its role 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?

Explicitly routes the agent between two modes: pass campaignId to check-and-save campaign recipients, or pass profileUrls without campaignId for a pre-check before building a campaign. It also gives continuation rules (call again when remainingUnchecked > 0, stop on stop: true) and names follow-up tools, leaving little to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, but the description adds real context beyond them: the full blast radius ('wipes EVERY collected lead in that intent bucket for the active setup'), the containment ('other buckets are left untouched'), and the reversibility profile ('cleared leads can be re-collected by future runs'). The confirm requirement is disclosed as well. This is exactly the kind of operational context annotations cannot carry.

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

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

Two sentences, front-loaded with the verb and scope, and every clause earns its place: blast radius, containment, reversibility, alternative, and precondition. No filler or restatement of the tool 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?

No output schema exists and none is needed for a destructive clear, and the description covers the destructive scope, the containment guarantee, recoverability, the confirm precondition, and the alternative path. Nothing an agent needs to invoke this 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?

Schema description coverage is 50%: searchType is thoroughly documented in the schema, but confirm has no schema description at all. The description compensates by stating 'Requires confirm: true', giving the agent the semantics the schema omits, and characterizes searchType as a bucket selector. It adds meaning for the undocumented parameter but duplicates the bucket semantics already in the enum description.

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

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

States a specific verb (clear) and a precisely scoped resource (one Intent Signal Agent result bucket keyed by searchType, on /app/signals), and explicitly names the sibling it is not (delete_signal_leads). An agent can distinguish it from get_signal_agent_results and delete_signal_leads 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?

Routes the agent to the right alternative with the condition that selects it ('use delete_signal_leads to block specific leads from re-adding'), and clarifies the boundary condition that other buckets are left untouched. The confirm: true precondition is also stated, so the agent knows what is required before invoking.

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

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

Annotations already declare readOnlyHint=false and openWorldHint=true, but the description adds substantial non-obvious behavior: it validates the cookie against LinkedIn before saving, enforces the plan sender limit, warns the cookie will expire, and describes the returned connectMessage + suggestions to relay. This is exactly the kind of mutation and lifecycle context the annotations do not carry.

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

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

The core purpose and the preferred-alternative routing are front-loaded in the first two sentences, which is right. It is long and dash-heavy in the middle, with some repetition about 2FA and auto-refresh, but nearly every sentence carries actionable instructions rather than filler.

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

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

Despite having no output schema, the description explains what is returned (connectMessage + suggestions) and what they mean, and it covers validation, plan limits, and the cookie's expiry lifecycle. An agent has enough to call the tool and to relay results 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 already 100%, so the baseline is 3. The description goes beyond the schema by explaining the operational trade-off of userAgent — why to ask for the real fingerprint (longest-lived cookie) and what to do when the user cannot supply it. It does not add field-level detail for country, proxyId, or label beyond what the schema states.

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 LinkedIn sender by pasting its li_at session cookie.' It further distinguishes itself from the sibling connect_linkedin_with_credentials by explaining that the cookie variant is cookie-only and expires, so an agent can route correctly without reading both 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?

Explicitly names the alternative and the condition selecting it: 'Prefer connect_linkedin_with_credentials when the user can share their login' because a saved email+password enables silent cookie auto-refresh. It also gives an ordered fallback for the user-agent capture step, so the agent knows when-and-when-not at each decision point.

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

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

Annotations only cover the write/open-world profile, but the description discloses that the server performs the login, stores the cookie and encrypted credentials, silently refreshes later, and even describes error behavior for push-to-phone 2FA. It also documents the return payload (connectMessage/suggestions/status/alwaysOnReady) used to detect a 24/7-ready account.

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 core action is front-loaded, but the 2FA explanation is heavily repetitive—the 'store totpSecret for 24/7' idea is restated three times, and the phone-push workaround is circled more than once. Sentences earn their place individually but the whole is longer than necessary.

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

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

For a 7-parameter connect tool with no output schema, it covers the login flow, credential storage, 2FA handling modes, the failure case, and the returned fields an agent must relay. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying the totpCode-vs-totpSecret trade-off and that totpSecret is the durable, stored path. It goes beyond the schema descriptions, though it repeats much of what totpSecret's own schema text already says.

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

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

States a specific verb+resource: 'Add a LinkedIn sender by logging in with the account's email and password.' It also distinguishes itself from the sibling connect_linkedin_with_cookie and positions itself as the recommended path. An agent can select it 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?

Explicitly names when to use it (recommended connect path, no user-agent needed), the alternatives (connect_linkedin_with_cookie for phone-push 2FA), and the follow-up step (call get_linkedin_2fa_status). It also splits totpCode vs totpSecret usage by scenario.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety and openness are covered. The description adds important behavioral context beyond annotations: the count is free and doesn't cost credits, and it explains the revenue-band sampling limitation (up to 100 companies, revenueScope.complete false means a sample) plus the zero-result caveat. This is valuable operational 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?

Well-structured and front-loaded with the core verb and benefit, followed by usage strategy and filter list. The second half is dense and slightly long, but every sentence provides actionable information. Minor verbosity in the filter enumeration.

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 14 parameters and no output schema, the description covers the essential context: what it returns (a count), when to use it, how to combine filters, the sampling caveat, and the zero-result interpretation. An agent has enough to call it correctly and interpret the 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 100%, so each parameter is already documented in the schema. The description enumerates the filter categories (keywords, titles, locations, etc.) and adds some naming/flow context (use companyIds from find_companies), which is minor since the schema already carries the detailed semantics. 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 precise verb+resource+scope: 'Count how many LinkedIn people match a filter set'. It explicitly distinguishes itself from search_people by noting it should be used BEFORE it, and describes the exact nature of the count (free, instant, exact).

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 when-to-use guidance ('Use this BEFORE search_people to size a market'), prescribes a workflow (fan out several angles, union the ones that land), and explains why ('counting never costs credits, so go broad'). It also warns about a common pitfall (a zero from one filter is not an empty market, try another angle).

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the mutation profile is covered. The description adds genuinely non-annotation context: quota limits per plan and the default that the setup is created in 'completed' state so it is immediately usable. It omits auth/permission requirements and error behavior when the quota is exhausted.

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 its gating condition, and no witnessed filler. Slightly verbose on the plan enumeration but each sentence carries 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 mutation tool with 11 parameters, nested objects, zero required fields, and no output schema, the description is adequate but thin: it never says what happens on quota exhaustion, whether omitted nested objects are left empty or defaulted, or what the call returns (setup id?). The quota and default-status details are the useful additions; the rest relies on the schema.

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

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

With 11 parameters at 64% schema coverage, the schema does most of the explanatory work. The description's only parameter-relevant statement ('Creates a completed setup by default') merely restates the schema's status default and adds no new meaning for the nested signalAgents, businessContext, campaignSettings, or idealCustomerProfile objects.

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

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

Specific verb + resource ('Create a new LinkedNav AI setup'), which cleanly separates it from update_ai_setup, get_ai_setup, and generate_ai_setup_icp. It does not name those siblings explicitly, but the resource and verb make the distinction readable without opening schemas.

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

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

Gives a concrete precondition ('when the account has an available setup slot') with plan-based quotas (Pro 3, Standard/free/trial 1), which is real when-to-use guidance. It stops short of naming alternatives (e.g. update_ai_setup for an existing setup, generate_ai_setup_icp for ICP drafting) or stating what to do when no slot exists.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely behavioral context beyond them: sendMode is IMMUTABLE after creation, Pro-only gating for AI/follow-ups/InMail, and that enabling follow-ups without Pro errors. It does not describe permissions, rate-limit behavior, or response shape beyond the ID, 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?

The purpose and return value are front-loaded, then the mode taxonomy, and every sentence carries real content. It is a dense single block that repeats some sendMode/Pro-only detail already present in the schema, so there is minor redundancy, but nothing is filler.

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

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

For a 17-parameter tool with nested objects and no output schema, the description covers the two main creation flows, their gating rules, and the return value ('campaign ID'). It does not enumerate parameter defaults or the full follow-up structure, but the schema descriptions carry those, so coverage is adequate.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds cross-parameter logic the schema states only locally: campaignType determines which parameters matter, AI mode makes messageTemplate/inMailSubject optional, and promptId is ignored for outreach. That relational guidance raises it above 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?

The description opens with a specific verb+resource ('Create a new campaign in LinkedNav') and states the return value ('Returns the campaign ID'). It then distinguishes the two campaign types and routes the agent to the correct add-leads sibling for each (add_lead_to_campaign vs add_message_targets), so it is separable from create_comment_campaign, duplicate_campaign and other 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?

It clearly explains when each campaignType applies ('outreach' vs 'message'), the two message send modes, and that AI mode/follow-ups/InMail are Pro-only, giving strong selection context. It stops short of naming explicit alternatives to avoid (e.g. duplicate_campaign, create_comment_campaign) or stating when not to use this tool.

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

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

Annotations only say readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds valuable non-obvious behavior: campaign is created in DRAFT, sourceMode is immutable after creation, and Pro-only features. These are exactly the transaction-state facts annotations can't convey.

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

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

Front-loads the tool purpose and core mode distinction, then layers in constraints and next steps. Dense but nearly every clause carries a real constraint (immutability, Pro-only, draft state).

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

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

For a 14-parameter creation tool with no output schema, the description covers the critical workflow (create draft, add targets, activate) and the two-mode model. It could note the approvalMode/scheduleSend interplay but the schema handles specifics well.

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 93%, so parameters are already well documented. The description reinforces the sourceMode/monitor mode distinction and the draft-then-add-targets workflow, but adds little parameter detail beyond what the schema already provides.

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 (create comment campaign) and immediately distinguishes the two modes (posts vs monitor) that define this tool. It contrasts with sibling create_campaign by specifying COMMENT campaign and names activate_campaign as the follow-up step.

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

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

Clearly explains the two sourceMode choices and what each requires, plus the Pro-only constraints. It names the next step (activate_campaign), but doesn't explicitly say when to prefer this over create_campaign or duplicate_campaign.

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

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

Annotations already declare a non-destructive mutation (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lowered. The description still adds genuinely useful, non-obvious behavior: silent skipping on duplicates and the dedup key (LinkedIn URL), plus what a contact becomes once in a campaign.

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 action and target before the clarifying parenthetical. Dense but each sentence (identity, sibling equivalence, dedup) carries distinct information; the terminology digression is the only mild clutter.

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 25-param, no-output-schema tool, the description covers the important hidden semantics (dedup, record aliasing). It omits what a caller gets back on success versus skip, which matters slightly more because there is no output schema.

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

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

Schema description coverage is 100% and the 25 parameters are richly documented in the schema itself, so baseline 3 applies. The description's only param-relevant signal is the profileUrl dedup key, which is behavioral rather than adding field-level meaning.

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 ("Add one LinkedIn profile as a new contact") and grounds it in the product UI ("Contacts" page, /app/contacts). It explicitly names the sibling create_lead and declares equivalence, so the agent can distinguish it from other create_* tools 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?

Identifies the direct alternative (create_lead) and asserts they are identical, which helps selection. It also explains record identity (contact/lead/prospect) and silent-skip dedup, but gives no explicit when-to-use vs bulk siblings like create_leads_bulk or add_lead_to_campaign.

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

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

Annotations only show readOnlyHint=false and destructiveHint=false. The description adds important context beyond annotations: dedup by LinkedIn URL, silent skip on duplicates, and the semantic mapping of lead/contact/prospect. Lacks detail on permissions or side effects like campaign enrollment.

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 core action and resource. No filler or redundancy.

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

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

Given 25 parameters covered fully by schema descriptions and no output schema, the description provides the essential conceptual context (lead=contact, dedup, silent skip) that an agent needs to use the tool correctly. Missing return behavior, but no output schema exists to carry 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 description coverage is 100%, so the schema already provides rich parameter documentation. The description does not add meaning beyond what the schema covers. 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?

Specific verb+resource ('Add one LinkedIn profile as a new contact in LinkedNav') and clarifies the domain concept that lead=contact=prospect. Also explicitly names the sibling create_contact and states equivalence, which helps the agent route correctly.

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?

Mentions it is 'Identical to create_contact' and describes the dedup behavior ('Skips silently if the profile already exists'). However, it doesn't say when to prefer this over create_contact, create_leads_bulk, or add_lead_to_campaign.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely useful behavior beyond that: the 50-item cap, the four possible per-lead statuses, silent de-duplication, and the 'Contact limit reached' skip reason. It omits auth/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?

Two tightly written sentences with the key constraint (50, single call) front-loaded and the return/edge-case behavior following. Every clause earns its place.

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

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

With no output schema, the description usefully documents the per-lead return statuses, which is the main thing an agent needs to interpret results. It could say more about required fields or auth, but for a bulk create with a fully-documented schema 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?

Schema description coverage is 100%, so the nested lead fields and listId are already documented in the schema. The description adds nothing about parameter syntax or format beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add up to 50 LinkedIn profiles as contacts/leads'), plus the batch scope ('in a single call'). The parenthetical '(the "Contacts" page)' hints at its distinction from campaign-scoped siblings like add_leads_bulk_to_campaign, but no sibling is named explicitly, so the differentiation is implicit rather than stated.

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

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

The description conveys the batching context and notes behaviors like duplicate skipping, but never says when to choose this over create_lead (single) or add_leads_bulk_to_campaign. Usage is only implied by the 'single call' framing.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-destructive local write. The description adds only the "active setup" scoping detail, which is genuinely useful context, but says nothing about name-collision behavior, whether the list starts empty, or what identifier comes back.

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

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

A single front-loaded sentence with no filler or repetition. It is tight, though arguably under-specified for a tool with a nested parameter object.

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

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

For a create tool with a nested object parameter, no output schema, and no annotations describing the result, the description should say at least what is produced or how the nested template is used. It leaves the messageTemplate semantics and the created list's identity 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?

At 75% schema coverage the schema already documents name, color, and description, and the description adds nothing on top of them. The most complex input, the nested messageTemplate object with its static/personalized enum and customMessage/personalizedPrompt fields, has no explanatory text anywhere, and the description does not compensate.

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

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

The description names a specific verb and resource ("Create a new LinkedNav contact list") and scopes it to "the active setup", which separates it from sibling creators like create_campaign, create_contact, and create_lead. It stops short of naming the related list tools (update_list, delete_list, link_list_to_campaign), so sibling differentiation is only partial.

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 statement of when to use this tool versus alternatives, no prerequisites, and no mention of related operations such as afterward linking the list to a campaign or updating/deleting it. An agent must infer usage purely from the name.

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

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

Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) already tell the agent this is a non-destructive local write. The description adds two genuinely useful behavioral facts beyond that — no slot limit and the sourceAiSetupId fallback to the active setup — but says nothing about validation, the legacy content vs context precedence, 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?

Three short sentences, zero padding, with the core purpose front-loaded before the two clarifying facts. Nothing here 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 an 18-parameter, nested-object creation tool with no output schema, the description is thin: it never signals that only 'name' is required, never warns that the followUp/attachment sub-objects are where most of the configuration lives, and gives no hint about what a successful create returns. The rich schema covers much of the gap, but the description does not pull its weight for a tool of this 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 description coverage is high (78%), so the schema already carries most parameter meaning, which sets the baseline at 3. The description's sourceAiSetupId note merely restates the schema's own 'Omit to use active setup' text and adds no new syntax or constraint detail, so it does not earn a bump.

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 a new LinkedNav prompt template'), so the agent immediately knows this is the creation counterpart to get_prompt/update_prompt/delete_prompt. It does not explicitly distinguish itself from the adjacent create_ai_setup sibling, which is the main remaining ambiguity.

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

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

The sentence 'If sourceAiSetupId is omitted, the active setup is used' gives useful default-behavior context, and 'no prompt slot limit' removes a possible hesitation. However, there is no explicit when-to-use guidance, no statement of prerequisites, and no routing advice versus alternatives like create_ai_setup or generate_message_templates.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing permanence and collateral damage ('including the user's notes on it'), telling the agent exactly what else is destroyed. It stops short of stating irreversibility or whether the action can be undone.

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 destructive action, then scope, then the collateral effect. No filler; 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 single-parameter destructive tool with no output schema, the description covers the action, the identifier source, and the side effect on notes. Minor gaps remain around irreversibility/recovery and behavior when the key doesn't exist, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% and the schema already documents the key format (normalized LinkedIn URL or lowercased name), so the baseline is 3. The description adds provenance ('as returned by crm_list_cards'), which helps the agent locate a valid key rather than guessing 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?

States a specific verb+resource ('Permanently delete one CRM board card') with explicit scope ('one ... by its key'), and names the sibling (crm_list_cards) that produces the key. An agent can distinguish this from crm_upsert_cards or bulk_delete_contacts immediately.

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

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

The description tells the agent where the key comes from ('as returned by crm_list_cards'), which implies the correct workflow, but gives no explicit when-to-use/when-not guidance and no alternatives for other deletion paths. 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?

Annotations already declare readOnlyHint/openWorldHint=false/destructiveHint=false, so safety is covered. The description adds genuine operational nuance the annotations do not: that the response is compact with conversations stripped, and the pitfall that the linkedinUrl key is lowercased and must never be used to construct a link.

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

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

Three dense sentences, front-loaded with the core action and scope, then filters, then return-shape guidance. No filler, and the parenthetical warnings are placed directly next to the fields they qualify.

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 discloses return fields (linkedinUrl, chats[].chatId) and the key-lowercasing gotcha. It omits list size, pagination or ordering behavior, which an agent listing cards might need to know.

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

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

Schema description coverage is 100% and the enum for stage is fully spelled out in the schema, so parameters are already documented. The description only restates 'filter by stage or by needsFollowUp' without adding format or semantics, which is the baseline-3 case.

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 (list CRM board cards) and immediately scopes it as 'compact: no conversation', which separates it from conversation-fetching siblings like get_inmail_conversation and get_conversation. An agent can pick it correctly 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 the two optional filter conditions (stage, needsFollowUp) and routes the agent onward: read a thread with get_inmail_conversation, and 'no person lookup needed'. It lacks explicit when-not-to-use guidance relative to non-list CRM siblings (crm_upsert_cards, crm_delete_card), so it stops short of a 5.

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

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

Annotations declare destructiveHint=true, and the description earns that by spelling out exactly what is destroyed: supplied fields overwrite stored values, and messages/callNotes REPLACE the stored arrays entirely. It also discloses the protective exceptions (the user's own notes are never touched; a hand-set stage is preserved unless forceStage is true), which the annotations cannot express.

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

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

Four tight sentences, front-loaded with the identity/matching rule, then overwrite semantics, then the two exceptions. No filler and nothing restated from the title without added 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 destructive bulk upsert with no output schema and one top-level array parameter, the description covers identity, limits, overwrite behavior, and the stage-lock exception — the information an agent most needs before writing. It omits any mention of failure handling or partial-success behavior across a 50-card batch, which is the remaining gap.

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

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

Schema coverage is 100%, so field-level documentation is already carried by the schema; the description adds the cross-parameter semantics that matter most — key normalization fallback, array replacement vs field overwrite, and the stage/forceStage interaction. This is meaningfully more than the schema alone.

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

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

States a specific verb pair and resource ('create or update CRM board cards'), gives the cardinality rule (one per person, up to 50 per call), and the identity rule (matched by key). An agent can immediately distinguish it from siblings like crm_list_cards and crm_delete_card.

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 matching rule implies when this tool is appropriate (when you have card identities and want to upsert), but there is no explicit when-to-use vs crm_delete_card / crm_list_cards guidance and no stated prerequisites. 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds real value beyond that by disclosing the blocking precondition and the confirm requirement. It stops short of saying whether the deletion is reversible or what happens to the setup's artifacts.

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 earning its place: what it deletes, the precondition, and the required flag. The scoping and gating information 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?

For a destructive two-parameter mutation with annotations covering the safety hint and no output schema, the description supplies the key operational facts (precondition, confirm flag). Minor gaps remain on reversibility, failure behavior, and setupId sourcing, but nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It does clarify that confirm must be true (the schema only shows default false), but says nothing about setupId — where to obtain it or what it identifies — leaving half the parameters 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 (Delete) and resource (AI setup), and narrows scope to 'a draft or completed AI setup'. The resource is clearly distinct from the other delete_* siblings (campaign, contact, list, prompt) and from get_/update_/select_ai_setup, so an agent can route 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 an explicit precondition — deletion is 'Only allowed when no scoped campaigns, lists, or contacts remain' — which tells the agent when this call will fail. It does not, however, name the alternative path (e.g., removing dependent campaigns/lists first, or using update_ai_setup), leaving the remediation to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing the cascade effect (removing campaign membership from contacts) and the confirm:true requirement, which are not visible elsewhere.

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, front-loading the action and side effect, with the invocation requirement last. No filler, nothing redundant.

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

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

For a simple two-parameter destructive tool with annotations covering the safety profile and no output schema, the description covers the main behavior and invocation requirement adequately. It could add whether deletion is permanent, but that gap is minor.

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 carries the load. It explains the confirm parameter's meaning (must be set true to proceed) despite the schema marking it optional with default false — a valuable clarification — but says nothing about campaignId beyond its name.

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

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

States a specific verb and resource ('Delete a campaign') plus the notable side effect of removing campaign membership from contacts. This clearly distinguishes it from create_campaign, update_campaign, and pause_campaign, though it does not name a specific sibling to differentiate scope from remove_leads_from_campaign.

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 precondition ('Requires confirm: true') that the agent must satisfy to invoke it successfully, which is useful. However, it offers no when-to-use versus alternatives (pause_campaign, update_campaign) and no explicit statement that the action is irreversible.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered. The description adds a concrete precondition the annotations do not: the call requires confirm: true, a behavioral gate the schema only hints at via default: false. It still omits irreversibility and what gets removed alongside the contact.

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, both front-loaded and load-bearing: scope first, then the required flag. 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 destructive mutation with no output schema and no schema parameter docs, the description covers the confirm gate but leaves gaps: what deletion actually removes, whether it is reversible, and how to obtain a valid contactId. An agent can call it, but without full confidence about side effects.

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

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

Schema description coverage is 0%, so the description must carry the burden. It explains confirm fully ('requires confirm: true') but says nothing about contactId — no ID format, source, or example. It compensates for one of two undocumented parameters.

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

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

States a specific verb and resource ('Delete one contact') and the qualifier 'one' implicitly separates it from the sibling bulk_delete_contacts. It does not name the alternative explicitly, but an agent can tell single-delete from bulk-delete from the wording alone.

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

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

The word 'one' implies this is the single-record path versus bulk_delete_contacts, and the confirm requirement is stated, but there is no explicit when-to-use/when-not guidance or prerequisites (e.g., permissions, cascading effects on campaigns/lists).

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: it discloses the side effect that contacts are moved to the setup default list (not deleted), and that confirm must be true. It stops short of stating irreversibility or permission requirements, but the contact-migration disclosure is exactly the kind of context annotations cannot carry.

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

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

Three short sentences, each earning its place: what is deleted, what happens to contacts, and the required flag. The destructive side effect is front-loaded where the agent will see it first.

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

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

For a two-parameter destructive tool with no output schema, the description covers the essential context: scope constraint, side effect on contacts, and the confirmation precondition. Missing only minor details such as irreversibility or error behavior when the target is a default list.

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

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

Schema description coverage is 0%, so the description carries the burden. It clarifies the semantics of the confirm boolean ('Requires confirm: true'), which is genuinely useful, but says nothing about listId beyond its name, leaving half the parameters undocumented in both schema and description.

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

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

States a specific verb (Delete) and resource (a non-default list from the active setup), with a scope qualifier that pins down exactly what can be targeted. An agent can immediately tell this apart from create_list/update_list and understands the default list is off-limits.

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 'non-default' qualifier implicitly excludes default lists and 'Requires confirm: true' states a call precondition, but there is no explicit when-to-use guidance or named alternative (e.g., bulk_delete_contacts, update_list). Usage is implied rather than stated.

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

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

Annotations already flag destructiveHint, but the description adds substantial beyond-schema detail: ACTIVE campaigns are auto-paused with a specific reason, queued sends are cancelled, and the template-only campaign exception is called out. This is exactly the context an agent needs before a destructive cascade.

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 the destructive consequences, then the exception, then prerequisites. The parenthetical aside is dense with useful information and earns its place; no padding.

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

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

No output schema exists, so the description carries the return/effect burden and does so fully by describing the cascade side effects. Everything an agent needs to invoke this destructive tool correctly is present.

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

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

Schema coverage is 100%, so both promptId and confirm are documented in the schema itself, including confirm's 'must be true' semantics. The description restates 'Requires confirm: true' without adding meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (Delete) and resource (LinkedNav prompt template) with the identifier scope ('by ID'). Clearly distinguishable from sibling delete tools like delete_campaign, delete_contact, delete_list, and delete_ai_setup.

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 directs the agent to call get_prompt first to inspect campaignCount before deleting, and states the confirm prerequisite. It lacks an explicit 'when not to use' framing, but the cascade warning effectively tells the agent when this is dangerous.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them: deleted intent leads are permanently blocked from being re-added by daily runs, and the call requires confirm: true. It leaves some gaps (what happens to non-intent deleted leads, behavior when a URL is unmatched), 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 sentences, none wasted, with the core action and agent scope front-loaded before the identifier sourcing and the confirm requirement. Tight, though the third sentence carries several distinct facts at once.

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

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

For a destructive tool with no output schema, the description covers the input source, agent scoping, the re-add blocking side effect, and the confirm gate — essentially everything needed to invoke it correctly. Minor omissions (per-agent irreversibility, partial-failure behavior) are the only 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 67% and the confirm parameter has no schema description at all; the description compensates by stating 'Requires confirm: true' and by clarifying that linkedinUrls accepts vmids or company IDs for the intent agent. This meaningfully extends the schema rather than restating it.

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

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

States a specific verb and resource ('Delete collected signal-agent result leads') and scopes it to exactly one agent, enumerating the three agent types. An agent can distinguish it from siblings like clear_signal_agent_results or get_signal_leads without inspecting 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?

Tells the agent where the identifiers come from ('Pass the lead linkedinUrl values returned by get_signal_leads') and notes the intent-specific alternatives (vmids or company IDs), which is clear invocation context. It does not, however, contrast itself with the sibling clear_signal_agent_results or state when deletion should be preferred over clearing all results, so no explicit alternatives/exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds the useful fact that both pending and failed comments can be denied and that the outcome is suppression of posting, but it omits whether the denial is reversible, what happens to the underlying comment, 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?

A single front-loaded sentence with no filler; the effect is stated immediately after the action.

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 with annotations covering destructiveness and no output schema, the description conveys the action, the eligible states, and the result. The remaining gap is the source/format of the ID, which is minor.

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 parameter, and the description adds nothing about pendingCommentId — no format, no note that it comes from get_pending_comments or get_pending_comments_count. 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?

States a specific verb (deny) plus resource (pending/failed AI comment) and the resulting effect ('so it will not be posted'), which cleanly distinguishes it from approve_pending_comment and retry_pending_comment. It does not explicitly name those siblings, so it falls 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?

The phrase 'pending or failed AI comment' implies the applicable state, so usage is inferable. However, no alternatives are named and no when-not condition (e.g., use retry_pending_comment to regenerate instead) is 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?

Annotations already disclose destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds real value beyond that: it explains the optimistic-concurrency guard via expectedVersion, warning that a draft rewritten since being shown will not be denied unseen.

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, front-loaded with the action and then the safety-catch rationale. No filler text.

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

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

For a destructive, no-output-schema mutation, the description covers the effect on the reply and the version-safety behavior. It omits what happens on a version mismatch or whether the denial is reversible, but is otherwise sufficient to invoke correctly.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It explains expectedVersion's source ('the draft's `version` from get_pending_replies') and its purpose as a staleness guard, though pendingReplyId is left to inference from its name.

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 (deny), a specific resource (pending or failed AI reply), and the concrete outcome ('so it will not be sent'). This clearly separates it from siblings like approve_pending_reply, retry_pending_reply, and update_pending_reply.

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 (to prevent an AI reply from being sent) and adds explicit guidance on the expectedVersion argument's role in avoiding denial of a stale draft. It does not, however, name an alternative tool or state exclusions.

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

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

Annotations already declare readOnlyHint/destructiveHint, and the description goes well beyond them with status-aware branching: drafts yield activation blockers matching the checks activation enforces, paused campaigns yield pause reason + reason-specific fix + resume viability, active campaigns yield silent-stop detection plus next send time in Eastern time. It also discloses the blocker output format (what/why/how/action with the fix tool), which is substantial behavioral disclosure not available in annotations or 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?

Front-loads the trigger phrase ('use whenever...'), then behavior, then the output contract. Dense and information-rich, with every sentence contributing, though the long compound trigger sentence and 'CAMPAIGN DOCTOR' branding add slight bulk without new information.

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

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

There is no output schema, so the description must carry return semantics, and it does: it explains what is returned per campaign status and the what/why/how/action structure of each blocker. An agent has everything needed to call it and interpret the 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 coverage is 100% and the single campaignId parameter is fully documented in the schema (including the omit-to-auto-pick fallback logic). The description adds nothing about the parameter, so the baseline of 3 applies where the schema does all the work.

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

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

States a specific verb+resource (diagnose a campaign) and frames it as a 'CAMPAIGN DOCTOR', which clearly separates it from data-fetching siblings like get_campaign/get_campaigns and from state-changing siblings like activate_campaign/pause_campaign. An agent can tell what this does 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 unusually rich trigger conditions: 'use whenever the user asks why a campaign won't start, can't activate, is paused, stopped sending, isn't working, or what's wrong with its settings.' It does not, however, name explicit alternatives (e.g., get_campaign for raw config) or state when NOT to use it, so it falls just short of the when/when-not/alternatives bar.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral content beyond that: prospects are copied conditionally, and message campaigns carry settings only, requiring add_message_targets for recipients. It does not say whether the duplicate starts paused/active or what it returns.

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, zero filler, with the core action and the conditional copy behavior front-loaded before the add_message_targets pointer.

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 should say what a successful duplicate yields (new campaign ID, initial state), which it does not. For a mutation tool with several sibling campaign tools, that return-value gap is the main missing piece.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains copyProspects well (default false, prospects excluded unless true), but leaves name and campaignId entirely uninterpreted, so only one of three parameters gets semantic 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?

States a specific verb+resource (duplicate a campaign configuration) with the scoping qualifier 'in the active setup', which separates it from create_campaign and update_campaign in the sibling list. It does not explicitly name those siblings, so it stops short of full 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?

Gives a clear selection rule: prospects come along only when copyProspects is true, and names add_message_targets as the tool to use when adding recipients to a message campaign instead. It does not address when to duplicate versus build a campaign from scratch with create_campaign, but the context given is solid.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true; the description goes beyond them by naming the data source (the user's own Clay workspace, i.e. not an external scrape), the LinkedIn-based auto-resolution fallback, and the fact that the user's credits are billed. It still does not say whether existing company fields on the contact are overwritten, which is the main behavioral question for a destructive write.

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 and scope (ONE contact, firmographics), followed by the fallback behavior and the cost note. Every sentence carries distinct information and none repeats 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 tool with no output schema, the description covers inputs, data source, fallback path, cost, and the field set produced. The remaining gap is process semantics: there is a get_company_enrichment_status sibling suggesting async processing, and the description never says whether the call is synchronous or must be polled.

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?

Only one parameter (contactId) with 100% schema description coverage ('Contact ID to enrich'), so the schema already carries the semantics. The description adds nothing about the parameter itself (no format, no example, no source of the ID). Baseline 3 is appropriate when 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?

Specific verb (enrich) plus resource (contact company) with an explicit ''ONE'' scope marker that implicitly contrasts with the bulk sibling enrich_contacts_company_bulk. It enumerates the firmographic fields returned (revenue, employee size, type, industry, HQ, funding), so an agent knows exactly what it produces. It does not name the sibling outright, so it falls just short of 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?

The description explains the auto-resolution path for contacts lacking a company URL and warns that Clay credits are consumed, which is useful context. However, it gives no explicit when-to-use or when-not-to-use guidance versus enrich_contacts_company_bulk for multiple contacts, nor any prerequisites about workspace state. 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?

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the mutation and external-scraping nature is structured. The description adds meaningful context beyond that: it is a queued job, uses LinkedIn profile scraping, saves results automatically, and costs 1 credit only when an email is found. It does not explain overwrite behavior or how to retrieve the job result.

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

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

Four short sentences, front-loaded with the core action and followed by mechanism, cost, and alternative. Every sentence adds distinct information 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 an asynchronous, no-output-schema enrichment queue, the description covers the action, data source, auto-save behavior, and cost model. It stops short of saying how to track the job or where the result appears, which would be helpful, but the sibling get_enrichment_status likely fills that gap.

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

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

Schema description coverage is 100%, so contactId and forceReenrich are already documented in the schema. The description adds no parameter-specific meaning, such as what forceReenrich overwrites or when re-enrichment is useful. With high schema coverage, the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: queue an email enrichment job for a contact. It distinguishes the tool from enrich_contact_phone by explicitly routing phone enrichment elsewhere, so an agent can separate it from the closest sibling without opening schemas.

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

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

It gives a clear alternative for a different enrichment type: 'For phone, use enrich_contact_phone.' That is useful routing guidance. It does not mention bulk email enrichment alternatives (enrich_contacts_email_bulk) or when not to re-enrich, though forceReenrich in the schema partially covers the latter.

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?

Adds meaningful context beyond the annotations: the job is queued asynchronously, the phone is saved automatically (consistent with destructiveHint=true implying overwrite), and it costs 1 credit only when a phone is found. It does not explain what happens to an existing phone number or whether the queued job can be cancelled.

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

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

Three tight sentences with the core action front-loaded, followed by mechanism and cost. No filler and nothing repeated from the schema or annotations.

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

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

For an async single-contact enrichment tool with no output schema, the description covers the action, mechanism, and cost. The notable gap is that it doesn't say how the caller learns the job finished or where the phone lands — an agent would want a pointer to the status 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 100%, so both contactId and forceReenrich are already documented in the schema. The description adds no parameter-level detail (e.g. what qualifies as 'already done' for forceReenrich), so the baseline 3 applies.

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

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

States a specific verb and resource ('Queue a phone enrichment job for a contact') and describes the mechanism (LinkedIn profile lookup, auto-save). The singular 'a contact' implicitly distinguishes it from the sibling bulk variant enrich_contacts_phone_bulk, but it never names that alternative 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?

Usage is only implied by the name and the word 'Queue' — an agent can infer this is for one contact and async, but the description offers no explicit when-to-use guidance, no mention of enrich_contacts_phone_bulk for batches, and no pointer to get_phone_enrichment_status for tracking the job.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and destructiveHint=true, so the safety profile is covered. The description adds meaningful non-annotation context: dedup-by-company so multiple contacts cost one lookup, auto-resolution of missing company URLs from LinkedIn, and that the user's Clay credits are consumed. It does not describe what the mutation touches or failure 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?

Four short sentences, front-loaded with the core action and then cost/dedup mechanics. Every sentence carries information, though the credit note could be folded in more tightly.

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, so the description carries the burden of return behavior, which it does not cover (e.g., what is returned per contact or partial-failure handling). However, it does cover cost, dedup, and auto-resolution, which are the key operational facts for a bulk enrichment 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?

Only one parameter with 100% schema coverage, so the schema already documents contactIds. The description reinforces the dedup/cap semantics ('deduped; capped per request') but adds no new format or constraint detail beyond what the schema states. 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 (Enrich), resource (multiple contacts), and target data (company firmographics), and the 'bulk' scope clearly distinguishes it from the singular sibling enrich_contact_company. An agent can tell what it does 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?

The description implies bulk use via 'up to the per-request cap' and cost behavior, but never explicitly routes the agent between this and enrich_contact_company, enrich_contacts_email_bulk, or enrich_contacts_phone_bulk. Usage context is implied rather than stated with exclusions or 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?

Annotations already flag this as non-read-only, destructive and open-world, so the bar is lower; the description still adds real value by disclosing the async queue model, the per-contact outcome vocabulary (queued | already enriched | already queued), and the cost of 1 credit per email actually found. It stops short of saying what 'queued' implies for follow-up (how/when to poll) or whether an existing email address can be overwritten.

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 and scope, then outcome shape, then cost. No filler; each sentence carries distinct information.

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

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

With no output schema, the description correctly surfaces the return shape (per-contact status) and the billing implication — the two things an agent needs to plan the call. The one gap is that it doesn't point to a status-checking sibling for queued items, which matters for an async 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 100% — both contactIds (1–20) and forceReenrich are fully documented inline. The description's 'up to 20' and status vocabulary largely restate the schema's maxItems and the re-enrich flag, adding little parameter-level meaning beyond the baseline.

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

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

States a specific verb+resource+scope: 'Queue email enrichment for up to 20 contacts at once.' The batch framing and the 20-contact ceiling cleanly separate it from the singular enrich_contact_email and from the phone/company bulk 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?

Usage is only implied — the 'bulk' verb and 20-item cap suggest this is the multi-contact alternative to enrich_contact_email, but neither that sibling nor any when-not condition (e.g. already-enriched handling) is named. The forceReenrich parameter hints at a prerequisite, but the description never states 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?

Goes beyond the annotations with two genuinely useful facts: this is an asynchronous queue (results are per-contact queued/already enriched/already queued) and credits are only charged when a phone number is actually found. However, destructiveHint=true is never explained — the description does not say that forceReenrich overwrites existing phone data, which is the most likely reason the tool is flagged destructive.

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 operation and scope, then the return contract, then the billing rule. Nothing is redundant and every sentence carries information.

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

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

With no output schema, the description usefully enumerates the per-contact result values. What is missing for a destructive, async, credit-consuming bulk operation is a note about overwriting on re-enrich and where the queued work is completed or polled (get_phone_enrichment_status).

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 contactIds and forceReenrich are already documented, and the description adds no per-parameter semantics (e.g., what happens to existing numbers on re-enrich). Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Queue phone enrichment') plus the batch scope ('up to 20 contacts at once'), which distinguishes it from the single-contact sibling enrich_contact_phone and from enrich_contacts_email_bulk / enrich_contacts_company_bulk. An agent can identify the operation and its limits without opening the schema.

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

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

Usage is only implied: batch phone enrichment follows naturally from the name and the 20-contact cap. There is no explicit guidance on when to prefer this over enrich_contact_phone, no prerequisite information (e.g., whether contacts need a LinkedIn profile first), and no pointer to get_phone_enrichment_status for tracking the queued work.

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

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

Annotations (readOnlyHint=false, destructiveHint=true) flag mutation, but the description carries far more: cache-first semantics, credit cost model (1 per email, 1 per phone, misses/cache free), the mandatory preview-then-confirm flow, and synchronous per-call caps. It explains what the 'destructive' cost actually is.

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

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

Purpose and the search_people link are front-loaded, and each sentence adds distinct operational value (cost, preview, timing, follow-up). It is long at roughly seven clauses, but nothing reads as 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?

Given it is a paid, mutating enrichment tool with no output schema, the description covers everything an agent needs: cost triggers, preview requirement, caching, synchronous duration caps, and the next step. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning: it explains 'optionally mobile phones' for fields, and the cache-first/free-hit language clarifies when forceReenrich and confirm matter beyond their schema text.

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

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

States a specific verb+resource+outcome: 'Turn raw LinkedIn profile URLs into verified work emails (and optionally mobile phones)'. Distinguishes itself from siblings like enrich_contact_email and search_people by framing itself as 'the closer for search_people'.

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 sequencing: pass search_people's linkedinUrl values in, ALWAYS preview with confirm:false, get user approval, then confirm:true, then use create_leads_bulk. Names the prerequisite tool and the follow-up tool, and warns about large lists.

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

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

Annotations only carry readOnly=false and destructive=true; the description goes much further, disclosing the exact cost model (0.07 credits/profile, charged only for profiles found), background execution, the free skip of already-enriched profiles, and the required user-consent two-call pattern. It also tells the agent what happens when credits run short. Nothing here contradicts the destructive/openWorld hints.

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

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

It is a long description, but the purpose and the cost/consent constraint are front-loaded, and each paragraph adds actionable information rather than filler. A few parenthetical asides could be trimmed, keeping it just short of a 5.

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

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

With no output schema, the description closes the loop by directing the agent to get_enriched_profiles (or re-reading get_signal_leads) for results, and it covers cost, consent, idempotency, and credit exhaustion. For a paid, background, write-like enrichment call, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the structured fields already document all three parameters and the baseline is 3. The description nonetheless adds real meaning: it explains that confirm:false is a no-charge estimate and confirm:true is the queued commitment, and that forceReenrich controls whether already-enriched profiles are re-billed — semantics beyond the schema text.

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

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

The description names a specific verb+resource ('Enrich LinkedIn profiles') and enumerates the exact attributes added (location, current company, headline/seniority, experience, skills), so its output is unmistakable. It is also distinguishable from sibling enrichment tools (enrich_contact_email, enrich_linkedin_urls) because it states the profile-level scope and the downstream purpose (filtering/segmenting/ICP scoring).

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

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

It explicitly says when to use it and where the inputs come from ('pass the linkedinUrl values from get_signal_leads ... social listening engagers, or a list the user gives you'), and names the companion read tool (get_enriched_profiles) for retrieving results. The confirm:false-then-true workflow and the credits top-up escape hatch are spelled out as operating procedure.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds real behavioral context: it reads the synced inbox, returns days-quiet / last-sender / hasInboundReply per thread, sorts oldest-quiet first, and warns that onlyWithReply requires the full thread to be synced.

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 core purpose and the definition of 'cold,' then layers return shape, sort order, and the onlyWithReply tip. Every sentence adds value, though it is longer than strictly necessary.

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

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

With no output schema, the description appropriately explains the returned fields (days quiet, who sent last, hasInboundReply) and sort order, and it states the data source (synced inbox). Adequate for a 4-param read tool, though it omits pagination/limit behavior beyond the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema for onlyWithReply by framing it as 'real relationships worth reviving,' though it adds nothing new for days, limit, or connectionId.

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 (Find) and resource (conversations that have gone quiet) with a precise operational definition of 'cold' (no message from either side in N days). It does not differentiate from the nearby sibling find_unanswered_replies, which is a similar retrieval tool, 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?

Gives a clear use context — re-engage before threads go fully cold — and explains the onlyWithReply:true branch for targeting real relationships. It does not, however, say when to prefer find_unanswered_replies or get_unibox over this tool, so no explicit alternative/ exclusion guidance.

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

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

Annotations cover safety (readOnly, non-destructive, openWorld), and the description adds substantial behavior the annotations cannot: it is free/no-credits, needs no account, and runs on a shared database. It also discloses signal-combination limits (hiring/growingTeamMinPct/revenue/size must ALL be given together) and the LinkedIn restriction that recentFunding + recentLeadershipChange runs two searches and adds a signals:[...] field.

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

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

The purpose and the primary routing are front-loaded, and most sentences carry unique constraints. It is dense and long for a single paragraph, packing several distinct concerns (limits, combination rules, next steps, unavailability), but little of it is filler.

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

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

For an 11-param, no-output-schema search tool, it covers return fields (name, companyId, industry, size), the follow-on workflow, cost model, and behavioral quirks. An agent has everything needed to invoke it correctly and act on results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains how signals combine (hiring:true + recentFunding:true = AND) and that some parameters are only valid together, which the per-field schema text does not convey.

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

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

Opens with a specific verb+resource: 'Find companies by BUYING SIGNALS and firmographics' and enumerates the signals (hiring, growth, revenue, leadership, funding) plus optional scoping. It clearly distinguishes itself from search_people, find_decision_makers, and list_funding_signals by naming them and their roles.

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

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

Explicit when-to-use with routing: it states the tool is FREE, frames it as the step before search_people/find_decision_makers, and warns those pull rows and cost credits. It also excludes the unavailable use case ('filtering by which SOFTWARE a company uses is not available'), which is exactly the kind of negative guidance that prevents misselection.

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

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

Annotations give safety profile (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description usefully adds that the call is asynchronous, returns a runId immediately, and that results must be polled from get_discovery_status. This async/return-shape disclosure is genuine value beyond the annotations, though it doesn't cover rate limits or error 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?

Two sentences, front-loaded with the core purpose and then the async follow-up path. Dense but every clause earns its place; no filler or redundancy.

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

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

With no output schema, the description correctly explains the return (runId) and the polling route to verified results, so an agent knows how to complete the flow. Missing only edge details like failure handling or result shape after polling.

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?

Only one parameter and schema coverage is 100%, so the schema already documents businessDescription fully. The description restates the concept ('from a description of your business') without adding syntax or format guidance, matching the baseline 3 when the schema carries the load.

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

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

Specific verb ('AI-discover') plus precise resource ('competitor companies on LinkedIn') and the input that drives it ('a description of your business'). The parenthetical visitors-flow reference anchors it and distinguishes it from siblings like find_companies, find_decision_makers, and find_influencers.

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 lays out the full workflow: run this, poll get_discovery_status with type 'competitors', then track_competitor to add picks. It names concrete next tools and the condition selecting them. It lacks an explicit when-not-to-use (e.g. vs find_companies), so it falls just short of a 5.

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

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

Goes well beyond the read-only/open-world annotations: it discloses that the join happens server-side, that accuracy depends on inbox sync, that a failure path returns 'warning + needsInboxSync', that legacy senders use a cached connection list, and that refresh:true triggers a live pull only on live-read-capable senders. This is rich operational context an agent 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?

Core purpose is front-loaded and the paragraph stays dense rather than padded, with each sentence adding a distinct fact (scope, downstream use, sync prerequisite, date filter, sender handling). It is long enough that a slightly tighter phrasing would help, 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?

With no output schema, the description still characterizes the return value as a 'lead list' and names the degraded response shape ('warning + needsInboxSync'). Prerequisites, per-parameter behavior, and cross-sender behavior are all covered, leaving no decision-relevant gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: since restricts to 'connections made since a date', refresh is tied to 'live-read-capable senders', and limit is framed by the note that 'the full never-messaged count is always reported'. It stops short of detailing connectionId semantics, keeping it at 4.

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

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

States a precise verb (find) and resource (1st-degree connections with no message history) plus a memorable scoping phrase, 'warm-but-untapped part of your network'. This cleanly distinguishes it from siblings like find_engagers_not_connected and find_cold_conversations 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 routes the output to the next step ('ready to hand to create_leads_bulk ... then start an outreach or message campaign') and names a prerequisite alternative ('recommends running sync_unibox first') with the exact condition that triggers it (inbox not synced). Both when-to-use and the dependency chain are stated.

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

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

Goes well beyond the annotations by disclosing the per-person credit cost (0.02), the two-step confirm:false/confirm:true charge flow, and what is returned. Annotations (destructiveHint=true, openWorldHint=true) only flag mutation and open-world behavior, so the cost/spend disclosure adds real value; it stops short of stating rate limits or resolution-failure 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 core purpose and filters, with parentheticals carrying downstream routing and cost. It is dense and slightly long, but every clause (cost, confirm, title targeting, filter combos) earns its place.

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

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

No output schema exists, so the description correctly specifies the return payload (name, title, LinkedIn URL) and the downstream consumers. Combined with the cost and confirm semantics, an agent has everything needed to call this correctly without surprises.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantic guidance the schema lacks: what omitting titles yields, and the concrete seniorities:["CXO","VP"] + functions:["Sales"] combination. It reinforces intent rather than just repeating field names.

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

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

Specific verb+resource with explicit scope: senior decision-makers at a company, enumerated as C-level/VP/Head-of/Director/Founder, and it names the return fields (name, title, LinkedIn URL). It is clearly distinguishable from siblings like find_companies, find_influencers, and search_people.

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 when to pass titles vs omit them, how to narrow with seniorities/functions/locations, and routes results downstream to enrich_* and create_leads_bulk. It also names search_people as the analogous preview→confirm tool, giving the agent an alternative pattern reference.

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

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

Goes well beyond the readOnly/destructive annotations by disclosing the internal scoring pipeline (1–10 against the active setup's targets, same scorer as Social Listening), the competitor-dropping rule, the leads/notAFit partitioning, the score ≥ 5 threshold, best-first ordering, and the roleUnclear reason plus a recovery path via get_profile. That is exactly the behavioral context an agent needs to interpret results.

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

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

Purpose is front-loaded in the first sentence and every clause (scoring, filtering, downstream guidance) carries real information rather than restating the name. The single dense paragraph with stacked em-dashes and parentheticals is slightly harder to scan than a segmented form, but there is little dead weight.

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