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

Annotations already flag destructive and open-world behavior; the description adds the meaningful consequence that switching accounts changes outreach identity. It does not elaborate on side effects of unlink or refresh_tier, but the annotation coverage lowers the burden.

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

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

Tight and front-loaded: the main purpose is stated first, the accounts-vs-account distinction takes one sentence, and the args are compactly listed. 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?

Covers core usage, the key sibling distinction, and relies on an existing output schema. However, action semantics are under-specified: what 'switch' versus 'switch_to' means, what 'refresh_tier' does, and which actions require account_id are left to inference.

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

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

The input schema provides no descriptions or enum values, but the description lists the allowed action values and notes account_id is used for switch_to. This meaningfully compensates for the schema, though the difference between 'switch' and 'switch_to' and the meaning of 'refresh_tier' remain unclear.

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

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

Description uses specific verbs ('switch', 'unlink', 'connect') and names the resource (active LinkedIn account). It also explicitly distinguishes itself from the 'accounts' sibling by noting listing is the accounts tool, so an agent can tell which tool handles mutation vs listing.

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 that the active account determines who outreach is sent as and points to the accounts tool for listing, giving clear context for when to use this tool. It does not spell out exclusions or conditions, but the main alternative is named.

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

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

The readOnlyHint annotation already covers the 'Changes nothing' aspect, so the description adds no new behavioral disclosure beyond that. It does not mention rate limits, response size, or other side effects, but for a simple list operation the annotation suffices.

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

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

The description is two short sentences plus a minimal Args block. The purpose is front-loaded, and every sentence earns its place, with no redundant words.

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

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

The tool is very simple (one optional parameter, no required fields) and has an output schema, so the description doesn't need to explain return values. The combination of the purpose statement, the Args hint, and the annotations fully equips an agent to call it correctly.

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

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

The schema provides only a title and default for the action parameter, with zero description. The description compensates by specifying action="list" and clarifying that other account actions belong to the account tool, giving the agent enough context to invoke it correctly. It doesn't explicitly state the parameter is optional, but the schema default covers that.

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

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

The description states a clear verb+resource: 'List the LinkedIn accounts connected to this HeyLead.' It immediately clarifies the tool's scope and read-only nature with 'Changes nothing.' This distinguishes it from the singular 'account' sibling by pointing out that account management actions belong elsewhere.

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

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

It explicitly names the alternative tool 'account' for switching, unlinking, and connecting email, telling the agent when not to use this tool. The instruction in the Args block reinforces that only the 'list' action is intended here, leaving no ambiguity about which operations belong to this tool.

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

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

Annotations already mark the tool as read-only and open-world, and the description adds useful behavior beyond that: hosted accounts receive a dashboard link and snapshot card, the link should be relayed, and some clients show the image only to the model. It also documents default behavior for empty parameters without contradicting the annotations.

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

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

The description is front-loaded with a one-line summary and then an organized Args block. The hosted-account image nuance is a valuable caveat that earns its place. It is slightly longer than strictly needed but contains no filler.

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

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

With no output schema, the description still explains what each mode returns, export formats, parameter defaults, and the hosted-account rendering caveat. It omits error handling and permission notes, but for a read-only analytics tool the provided context is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden. It documents all four parameters: action values, campaign_id defaulting to active, campaign_ids for compare mode, and format choices for export. This fully compensates for the bare schema.

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

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

The description clearly identifies the tool as campaign analytics with reports, comparisons, and exports, which distinguishes it from sibling tools like campaign or show_status. It lacks a direct action verb, but the resource and available modes are specific enough to avoid tautology.

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 Args section gives mode-specific usage context: report, compare, and export, along with defaults for empty campaign_id and campaign_ids. However, it never explicitly states when not to use this tool or names alternatives among the large sibling set, leaving some routing 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 flag destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral detail: 'reply' and 'approve_draft' SEND a LinkedIn message and cannot be undone. It does not explicitly state whether discard_draft is also irreversible, which is the only small 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?

The description is compact: a one-line purpose, a warning about irreversibility, a sibling routing note, and a clean args list. It front-loads the most important facts and has no filler.

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

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

With an output schema present, not explaining return values is acceptable. The description covers actions, target, content, and irreversibility, but it leaves the send_message sibling unaddressed and does not clarify whether text is required for reply/approve_draft, so an agent may need to infer those preconditions.

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%, yet the description documents all three parameters: action values ('reply', 'approve_draft', 'discard_draft'), chat_id as the conversation/draft, and text as the message or edited draft. This fully compensates for the sparse schema and adds allowed values via prose.

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

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

Description opens with a concrete verb+object: 'Reply in a LinkedIn conversation, or approve or discard a drafted reply.' It clearly delimits three actions and distinguishes it from the inbox read tool ('Reading the inbox is the inbox tool'), so an agent can tell it apart from siblings like inbox.

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

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

It provides explicit routing away from reading ('Reading the inbox is the inbox tool') and warns that reply/approve_draft send a message and cannot be undone. However, it does not address the sibling send_message tool, so the boundary between sending a fresh message and answering an inbox conversation 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 declare readOnlyHint=false and destructiveHint=true, so the description doesn't need to restate that. It adds useful behavioral context: creates the event on the connected calendar, attaches a Google Meet link, and emails the attendee an invitation. It doesn't mention side effects like overwriting existing events or permission requirements, but the core behavior is disclosed.

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

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

The description is well-structured with a clear opening sentence, a usage trigger, and a compact Args list. Every sentence earns its place. It could be slightly tighter, but it's appropriately sized for a 5-parameter tool.

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

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

Given the tool has an output schema and annotations, the description covers the essential behavioral context: what happens (event created, Meet link attached, invitation emailed) and when to use it. It doesn't mention failure modes or prerequisites (e.g., calendar must be connected), but the connected-calendar detail is implied. This is adequate for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains attendee_email ('Who to invite — the prospect who replied'), start ('When it starts, ISO 8601'), duration_minutes ('How long the meeting runs. Defaults to 30'), summary ('Event title. Defaults to naming the attendee'), and description ('Optional agenda or notes'). This adds meaning beyond the bare schema property 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?

The description states a specific verb ('Book'), a resource ('a meeting on your Google Calendar'), and the action's purpose ('invite a prospect'). It clearly distinguishes itself from siblings like send_email or send_message by specifying calendar event creation with a Google Meet link and attendee invitation.

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

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

The description explicitly says 'Use this when a reply agrees to a call,' giving a clear trigger condition. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for an agent to select this tool over generic messaging tools.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description adds useful behavior beyond that: the default campaign_id behavior ('Uses the active one if empty') and the confirm requirement for destructive actions. No contradiction with annotations.

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

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

The description is compact: two sentences of purpose/guidance followed by a tight argument list. It front-loads the primary verbs and then provides exact parameter semantics without redundancy. Every sentence earns its place.

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

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

For a 3-parameter, 9-action tool with no output schema, the description covers the state-changing purpose, all action keywords, parameter defaults, and the confirm flag. It doesn't explain nuances like when to choose emergency_stop over pause, but these are not essential for a correct first invocation.

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

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

Schema coverage is 0% and there are no enums, so the description carries the full burden. The Args section lists every allowed action value, explains the campaign_id default, and clarifies confirm's role. This adds substantial meaning to the bare schema.

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

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

The description lists a specific set of verbs ('Launch, pause, resume, archive, delete or emergency-stop a campaign') applied to a resource, and explicitly distinguishes itself from the read-only sibling campaign_status. This makes the tool's scope clear and separates it from alternatives.

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

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

The description gives clear context: 'Every action here changes what happens next' and points to campaign_status for watching or reading history. It does not explicitly mention create/edit siblings, but the state-changing framing is enough to guide the agent toward when to use this tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds 'Changes nothing' and explains that monitoring a draft requires launching via campaign(action='launch'), adding context beyond the annotations. No contradiction.

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

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

The description is compact and front-loaded with the core purpose ('Watch a campaign run...'), then efficiently lists args with inline explanations. No wasted words; every sentence adds value.

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

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

For a read-only tool with no output schema, the description explains each action's output concept (live progress, step-by-step plan, history). It also links monitoring to the launch action, which is helpful. Minor gap: no mention of error conditions or return format, but not critical for a monitoring tool.

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

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

Schema coverage is 0%, so the description carries full responsibility. It explains each action value ('monitor', 'plan', 'status_history') with detailed meanings, and clarifies that campaign_id defaults to the active campaign. This fully compensates for the bare schema.

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

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

The description clearly states the tool watches a campaign run, shows its plan, or reads status history, with a specific verb and resource. It distinguishes from read-only operations but doesn't explicitly differentiate from siblings like show_status or scheduler_status, though the action options add specificity.

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

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

Provides no guidance on when to use this tool versus alternatives. It explains each action (monitor, plan, status_history) but doesn't mention sibling tools or exclusions. An agent would have to infer context from the actions alone.

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

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

The description goes well beyond the annotations by disclosing concrete side effects: marking invitations accepted, moving outreach to replied, storing messages, and setting opted-out in a way that stops all future outreach. It also explicitly states it sends nothing, which supports the readOnlyHint=false and destructiveHint=true annotations without contradicting them.

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

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

The description is compact but information-dense: a one-sentence summary, a functional overview, and then the important side-effect and dependency details. Nothing is redundant, and the most critical behavioral constraints are front-loaded.

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

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

For a parameterless tool with an output schema, the description fully covers what the tool does, what it changes, what it does not do, and why it matters for follow-ups. The dependency warning about accepted invitations is especially valuable context an agent needs before invoking it.

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

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

The tool has zero parameters, so the schema carries no parameter semantics burden and the baseline is 4. The description notes no arguments and instead focuses on behavior, which is entirely appropriate for a parameterless tool.

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

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

The description opens with a specific verb and resource: 'Read new LinkedIn replies and record what they mean.' It then details what it fetches, classifies, and lists, and distinguishes itself from siblings by noting it sends nothing and is the only path that notices accepted invitations.

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

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

The description gives clear context: this tool reads, records, classifies, and prioritizes replies, and is the only path that detects accepted invitations, making it essential for follow-ups. It does not explicitly name alternative tools or when-not-to-use conditions, so it stops short of full routing guidance.

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

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

Beyond readOnlyHint=true, the description discloses meaningful behavioral details: results are capped at 25 due to cost, nothing is filtered locally, and the distinction between 'no matches' and a failed search is explained. It also specifies that natural-language LinkedIn queries are passed through unchanged and usually return empty, which is critical for expected 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?

The description is front-loaded with the core purpose, then uses a clean 'Args:' block that maps directly to the schema. The longest section (query) earns its length by explaining the nuanced LinkedIn behavior. No sentences are filler.

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

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

The tool is complete for an agent: it explains when to use it, what it does not do, parameter semantics, error-reporting nuance, rate limits, and output formats. An output schema is present, so return values need not be described. The sibling routing is explicit.

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

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

With 0% schema description coverage, the description compensates fully: all 10 parameters are documented. The query parameter receives extra depth, including literal LinkedIn keyword matching, example formats, a warning about natural-language queries, and cap behavior—all meaning beyond the schema's type and default fields.

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

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

The description opens with a specific verb and resource: 'Search, browse and read your contacts, and export them.' It also explicitly declares 'Changes nothing' and names the sibling with mutating operations ('Tagging, noting, re-staging and linking are update_contact'), making the tool's scope unmistakable.

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

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

The description explicitly routes mutations to a sibling: 'Tagging, noting, re-staging and linking are update_contact.' The read-only context is reinforced with 'Changes nothing.' While it doesn't say 'use this when you need to read contacts,' the inclusion of the alternative and the clear non-mutating scope leaves no ambiguity.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, but the description goes further by clarifying that nothing is sent until launch, that rate limits, sending window and opt-outs still apply, that project_brief is required before launch/resume/auto-send, and that approval behavior is a workspace setting surfaced via inspect/scheduler. It does not explicitly reconcile the destructiveHint against the fact that only a draft is created, which is the one gap.

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

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

Front-loaded with the purpose and the draft-until-launch rule, and arg docs are alphabetical and readable. However the use-case list is stated twice nearly verbatim (sales prospecting/recruiting/research in the opening paragraphs, then again as 'customers... candidates... investors...'), which is avoidable bloat in an already long description.

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

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

With an output schema present, the description needn't explain return values, and everything else an agent needs for a 14-param, open-world, mutating tool — prerequisites, parameter interactions, defaults, and the goal taxonomy — is present.

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

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

Schema description coverage is 0% across 14 parameters, so the description carries the full burden — and it does, documenting every parameter with defaults, conflicts (exclude_connections cannot combine with connections_only), and value enums for goal/campaign_type/voice_mode. Examples are supplied for target_description, company_url and people.

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 LinkedIn outreach campaign') plus the input modality ('from a natural language description') and immediately scopes it as a draft until campaign(action='launch'). An agent can distinguish this from campaign, edit_campaign, and generate_icp 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 routes the agent: use the `people` argument when the user can already name targets (skips LinkedIn search), use `connections_only` for 'DM my network', use `exclude_connections='off'` when the user says 'include my existing connections', and use `force` only on a mismatch verdict. Alternatives and when-not conditions are named rather than implied.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description adds genuinely new behavioral context beyond them: changes apply only to messages written from now on, editing any offer_* field unconfirms the Offer card, project_brief is required before launch/resume/auto-send, and exclude_connections/connections_only are mutually exclusive toggles. No contradiction with the annotation 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?

Structure is well front-loaded (purpose, then patch semantics and alternatives, then Args), and for a 52-parameter tool with a bare schema the length is largely earned. There is some repetition ("Empty keeps the current value" / "0 to keep current" recurs many times) and the campaign_type paragraph could be tightened.

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

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

An output schema exists so return values need no explanation, and the annotations carry the safety profile. The description still covers what an agent needs to call this correctly: partial-update semantics, defaults for empty values, prerequisite fields, and the exclusivity between exclude_connections and connections_only.

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% across 52 parameters, so the description carries the full burden and does so: it documents ~50 of 52 fields with meaning, accepted values ("on"/"off"/"observe", intent enums, ranges like 7-60), units, and cross-field interactions. Only voice_noise and voice_humanize are left undocumented.

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

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

Opens with a specific verb+resource ("Change one running or drafted campaign's settings") and immediately distinguishes itself from create_campaign and campaign(action=...), which are named explicitly. An agent can select this tool over its siblings 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?

States the patch semantics ("Pass only what you want to change; every field left empty keeps its current value") and names the alternatives with the condition that selects them: create_campaign for a new campaign, campaign(action=...) to launch/pause/stop. It also scopes the tool ("edits settings only: it sends nothing and adds no prospects").

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

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

Annotations already indicate readOnlyHint=false, openWorldHint=true, and destructiveHint=true. The description adds valuable behavioral context beyond that: the result is persisted ('The result is saved and can be reused with create_campaign(icp_id=...)'), and it details how decision_makers_only behaves differently across goals. No contradiction with annotations.

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

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

The description is well-structured: an opening statement, a paragraph on scope and reuse, then a clear Args list. It front-loads the core purpose. However, the sentence 'Supports target audience analysis, customer segmentation, buyer persona creation, ideal customer profiling, and B2B market research.' is somewhat redundant with the opening line and adds length without new information. Still, every other sentence earns its place.

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

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

This is a complex tool with 5 parameters and an output schema. The description covers each parameter's meaning, provides guidance on when to pass goal, explains the saved-and-reusable output, and addresses edge cases (e.g., job search vs. sell). There is an output schema present, so return-value details are not needed. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden. It thoroughly documents all five parameters in the Args section with examples ('CTOs at fintech startups', 'freelance UX designers in London'), explains the default behavior of decision_makers_only, and clarifies the semantics of goal across six distinct use cases. This far exceeds what the bare schema 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?

The description opens with a specific verb and resource: 'Generate a rich Ideal Customer Profile with buyer personas.' It clearly states the deliverable (2-4 personas with pain points, fears, etc.) and enumerates supported use cases (target audience analysis, customer segmentation, etc.). This fully distinguishes it from sibling tools like create_campaign or update_contact.

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

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

The description provides explicit when-to-use guidance, especially for the goal parameter: 'Always pass it; a job search with goal="sell" produces peers, not hiring managers.' It also explains the decision_makers_only flag and how company_context/focus_query improve results. It does not explicitly name alternatives or when-not-to-use scenarios, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces the read-only behavior by mentioning that drafted replies can be read and that write actions belong to answer_inbox. It adds useful behavioral context without contradicting the annotations, and no hidden side effects need to be disclosed for a read operation.

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

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

The description is compact and well-structured: a direct purpose statement, a brief sibling-routing note, and a minimal argument list. Every sentence earns its place and there is no redundant 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?

All parameters are semantically documented, the read/write boundary is explicit, and the presence of an output schema means return values need not be described in prose. The only minor gap is the lack of detail on how chat_id and name interact or take precedence, but this does not prevent correct usage.

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

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

The input schema has 0% description coverage and no enums, so the description carries the full burden of explaining parameters. It defines all four: action with allowed values 'list', 'read', and 'comment_drafts'; chat_id as the conversation identifier; name for finding the conversation by person; and limit for display count. This fully compensates for the empty schema.

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

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

The description opens with a clear verb and resource: 'Read any conversation in your LinkedIn inbox, and the drafted replies.' It also explicitly distinguishes itself from answer_inbox, which handles replying, approving, and discarding drafts, so an agent can easily tell this tool apart from its closest sibling.

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

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

The description explicitly states which actions belong to answer_inbox instead of this tool: 'Replying, approving a draft and discarding one are answer_inbox.' This gives a clear when-not-to-use condition and names the alternative, providing strong routing guidance without leaving the decision 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 openWorldHint=true, so the description's job is to add detail, which it does: skip 'records nothing else,' close records a result, opt_out 'stops all future contact,' and confirm is 'required where the action cannot be undone.' It stops short of naming which specific actions are irreversible or what dismiss does relative to skip.

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 three-action summary, then a prose block of selection rules, then a compact Args list. Every line is informative, though the reason/reason_code/reason_note trio is described somewhat repetitively.

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

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

With an output schema present, return values need not be explained, and the action semantics, conditional requirements and defaults are well covered. The remaining gap is 'dismiss,' which is listed but never distinguished from skip or close.

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% across 11 params, so the description must carry the load, and it does: it enumerates action, outcome and reason_code values inline, marks outcome as required for close with no default, and documents defaults for campaign_id ('active one if empty') and deal_currency ('last deal's'). This adds substantial meaning beyond the bare typed properties.

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 opening sentence states three specific actions (skip, close, dismiss) on a named resource, and the closing line explicitly routes the read case to prospect_view. An agent can distinguish this from the sibling prospect_view without opening either schema.

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

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

It states the selection rule directly: 'Someone who is not a fit is skipped, not closed,' explains what close requires versus skip, and names the alternative tool for reading. Conditions for outcome="opt_out" are also given, so there is little left to infer.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Changes nothing' is consistent without adding much new behavioral information. It does add the actionable detail that campaign_id falls back to the active campaign, which is a useful behavioral nuance beyond the schema.

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

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

The main behavior is stated in one sentence, followed by a compact Args list. Every line earns its place; no filler or repetition.

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

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

For a simple read-only tool with an output schema present, the description covers the action choices and the key campaign fallback. Minor ambiguity remains around what happens when outreach_id is empty, but overall an agent has enough to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must carry the parameter meaning, and it does: action gets explicit enum-like values ('conversation' or 'timeline'), and campaign_id gets default-fallback semantics. outreach_id's 'Which outreach' is terse but sufficient to identify the parameter's role.

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 read verb, a single resource ('message thread with one prospect'), and an alternative view ('their timeline'), which clearly distinguishes it from the mutation/send siblings like send_message and update_contact. The 'Changes nothing' clause reinforces that this is a pure read operation.

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 read-only wording and the 'one prospect' scope imply when to choose this tool, but the description does not name alternatives or state when not to use it. It provides context for usage (viewing a conversation or timeline) without explicit exclusions.

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

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

Annotations declare destructiveHint=true, readOnlyHint=false and openWorldHint=true, so the safety profile is covered. The description adds meaningful consequences beyond that: 'Off means nothing sends until it is on again' and that a hosted account never sends from the local machine, both of which affect how an agent reasons about the call.

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

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

Purpose and the key behavioral caveat are front-loaded, then the argument list follows. The per-parameter lines are warranted given 0% schema coverage, though the prose is slightly loose and could be tightened without losing information.

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

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

An output schema exists, so return values need not be explained, and all six parameters are documented. What remains thin is guidance on the multi-action mode itself (what each action does), which is a meaningful gap for a tool whose behavior changes entirely by action.

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

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

Schema description coverage is 0%, so the description carries the full burden and meets it: it enumerates the valid action values and explains all five remaining parameters (enabled, cloud, host, hours, campaign_id), including which actions each applies to and the 'cloud' sentinel for host.

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

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

States a specific verb and resource ('turn the autonomous scheduler on or off, or change how it runs') and explicitly names the sibling it is not: 'Reading its state, logs, activity or diagnostics is scheduler_status.' An agent can distinguish it from scheduler_status 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?

The description gives one clear alternative (scheduler_status for reading) with the condition that selects it, and maps each parameter to the actions it applies to (e.g. 'enabled ... (toggle, report)'). However, it never explains when to choose among toggle, observe, always_on, backfill_cloud, send_from, or report, so the core action-selection decision is left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds context that 'cloud' targets the hosted scheduler versus the local machine, and it clarifies that the daily-report action is handled by another tool. It doesn't disclose response behavior, pagination, or any limits, but this is acceptable for a read-only tool with an output schema 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?

The description is a single front-loaded purpose sentence followed by a tight argument list. Each line in the list adds necessary information with no fluff. The structure makes it easy for an agent to scan the purpose and immediately find the parameter semantics.

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

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

With an output schema present and annotations covering read-only safety, the description's remaining job is to define the parameters and scope—which it does completely. The only possible gap, the exact return shape of each action, is presumably covered by the output schema. An agent has everything needed to invoke this tool correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden—and it succeeds. Every one of the five parameters gets a concrete semantic definition: action lists its allowed values, cloud explains local vs. hosted, hours defines the lookback window, and event_type/campaign_id specify filtering behavior. This is exactly the kind of compensation needed when the schema provides only titles and defaults.

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

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

The description opens with a specific verb and resource: 'Read the scheduler: status, logs, activity, diagnostics...' This clearly identifies the tool's scope and enumerates the sub-information it exposes. It also distinguishes itself from the sibling 'scheduler' tool by explicitly stating that the daily report belongs to that tool, eliminating confusion.

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

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

The description clearly explains the action parameter's valid values and the intended use case for each. It explicitly names the sibling scheduler tool as the correct alternative for daily-report toggling, providing a when-not-to-use note. However, it does not mention how this tool relates to other sibling read/status tools like show_status or campaign_status, so the guidance is not exhaustive.

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

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

Annotations already mark the tool as non-read-only and destructive, so the description adds meaningful context beyond them: InMail fails closed on four specific preconditions, delete only applies to recently sent messages, and empty text auto-generates. It does not mention reversibility or side effects of deletion, hence 4.

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 important one-line purpose is followed by a dense, well-organized Args block with no filler. The detailed InMail preconditions are worth the space and are formatted as a scannable list.

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 five-parameter, multi-action messaging tool with preconditions and defaults, the description covers selection, required fields, failure behavior, and destructive scope. An output schema exists, so the absence of return-value detail is not a 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?

With 0% schema description coverage, the description carries the full burden and succeeds: action gets enumerated values with per-value behavior, campaign_id gets default semantics, outreach_id gets a required-for-inmail flag, and text gets auto-generation plus special delete usage. Every parameter receives meaning beyond its bare name and type.

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 opening line names a precise verb and resource ('Send follow-ups, replies, or InMail to prospects') and the action list makes the scope concrete. It is clear, but it doesn't explicitly differentiate from sibling answer_inbox or say which nearby tool handles other messaging cases, so it earns 4 rather than 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?

Each action value includes when to use it: follow-up after connection accepted, reply to a prospect who messaged you, delete within 60 minutes, and InMail to non-connections. The InMail path lists explicit preconditions and gives the internal DM fallback, while the delete action states its time constraint and the text param identifies auto-generation behavior.

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

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

The description aligns with annotations (readOnlyHint=false, destructiveHint=true) and adds substantial behavioral context beyond them. It explains that the tool analyzes LinkedIn profile and writing style to create a 'voice signature,' and that it performs LinkedIn automation setup and SDR onboarding. It also discloses the authentication requirement via a backend_jwt token and clarifies that no API keys are needed unless providing a custom LLM key. This fully prepares the agent for the tool's side effects and dependencies.

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

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

The description is well-organized and front-loaded. It opens with a one-sentence summary, then a bolded requirement, a short explanatory paragraph, a clear 'First-time setup:' section with steps, and an 'Args:' section with bullet points. Every sentence earns its place; no fluff or redundancy. The structure aids quick comprehension for an agent.

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

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

Given the tool's complexity (external login, token acquisition, multiple configuration options), the description is remarkably complete. It covers prerequisites, exact steps, parameter semantics, and the tool's role in the broader system. The presence of an output schema (indicated by 'has output schema: true') means return-value documentation is not required in the description. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it excels. Each parameter is explained: llm_api_key as optional with purpose, llm_provider with explicit allowed values, backend_url with a default behavior, and backend_jwt as the authentication token with instructions on how to obtain it. This is more than sufficient for an agent to fill the arguments correctly.

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

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

The description states a clear specific purpose: 'Set up HeyLead by connecting your LinkedIn account and analyzing your writing style.' It further distinguishes this from siblings by detailing it handles 'LinkedIn automation setup, SDR onboarding, account connection, and voice analysis' and explicitly marks it as 'REQUIRED for first-time users — must be called before any other tool.' No ambiguity remains.

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

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

It provides explicit when-to-use guidance: 'REQUIRED for first-time users — must be called before any other tool.' It also gives a step-by-step walkthrough: sign in at a specific URL, connect LinkedIn, copy the setup message, and call the tool with the token. It notes 'No API keys needed on the hosted backend,' which preempts a common question. There is no need for alternative tools since this is a mandatory one-time setup.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context by disclosing that hosted accounts receive a dashboard link and snapshot card, and that the link must be relayed because some clients show the image only to the model. This goes beyond the annotations without contradicting them.

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

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

The description is well-structured and front-loaded with the core purpose. It includes a useful relay caveat and parameter documentation without excessive padding. The conversational phrasing ('Ask how's my outreach anytime') is functional but slightly loose, keeping it from 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?

For a simple tool with one optional parameter and no output schema, the description covers the dashboard contents, hosted-account behavior, and parameter semantics. It does not describe the exact shape of stats or error cases, but these are minor for this simple read-only 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 0%, so the description must fully explain the parameter. It does: 'campaign_id: Show stats for a specific campaign. Shows all if empty.' This clarifies the optional single parameter's behavior and default semantics completely.

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

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

The description states a clear verb and resource: 'Show your outreach dashboard' with concrete contents like campaigns, stats, hot leads, and account health. It is more specific than the tool title but does not explicitly distinguish itself from the sibling 'analytics' tool, so it falls 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?

The description gives clear usage context: the chat is the 'front door' to the dashboard and users can ask 'how's my outreach?' anytime. This implies broad, on-demand use but does not state when to prefer another tool or mention exclusions, so it lacks explicit routing guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, which cover safety. The description adds valuable behavioral details: hosted accounts receive a dashboard link and snapshot card, the link should be relayed due to client rendering, and recommendations follow an explicit priority order. This goes beyond the annotations without contradicting them.

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

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

The description is appropriately sized, around 70 words, and front-loads the core purpose. The hosted-accounts caveat is necessary operational detail. There is slight redundancy between 'Analyzes all active campaigns' and 'Analyzes all active if empty,' but it does not hurt clarity.

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

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

For a one-parameter, read-only suggestion tool with no output schema, the description covers purpose, input semantics, prioritization logic, and output hints (dashboard link and snapshot card). It could more concretely describe the structure of the returned recommendation, but it is complete enough for an agent to invoke 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 0%, so the description must compensate. It fully does for the only parameter: 'campaign_id: Focus on a specific campaign. Analyzes all active if empty.' This defines both the parameter's meaning and its empty-value behavior, which is complete and actionable.

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

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

The description opens with a clear verb and resource: 'Suggest the best next action for your outreach.' It further specifies scope by saying it analyzes all active campaigns and prioritizes by impact. It does not explicitly contrast with sibling tools like scheduler or check_replies, so it stops short of full sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It explains behavior and the campaign_id parameter, but never states when to prefer this tool over siblings such as scheduler or check_replies, nor does it give any exclusion criteria. The only instruction, about relaying the dashboard link, is post-invocation rather than selection guidance.

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

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

Annotations already mark the tool as destructive (destructiveHint=true) and non-read-only, and the description adds the safety-relevant dry_run behavior: 'Show what would change without changing it.' It does not contradict the annotations and provides useful context beyond them.

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

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

The description is compact and front-loaded: first the purpose, then the routing instruction, then a terse Args block. No redundant preamble or repetition of the schema's default values.

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

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

For an 8-parameter mutation tool with an output schema and a destructive annotation, the description covers the core decisions: which action, which contact, and dry_run semantics. It falls slightly short on explaining the 'enrich' action and the behavior of 'match', leaving some agent uncertainty for those less common cases.

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 Args list is essential; it explains all 8 parameters and enumerates the allowed action values, which the schema leaves as a bare string. The main weakness is that 'match' is only glossed as 'How to match when linking' and 'enrich' is not explained, but the description still compensates for the schema's lack of parameter descriptions.

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

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

The description opens with a specific verb and object—'Change one contact'—and enumerates the five supported mutations (tag, note, stage, link, enrich). It also explicitly contrasts itself with the read/search workflow by naming the contacts sibling tool, so an agent can distinguish it without opening schemas.

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

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

It gives a clear when-not instruction: reading and searching contacts is the contacts tool, not update_contact. It does not spell out additional exclusion conditions relative to other mutation siblings such as edit_campaign, but the routing context is sufficient for the common case.

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