Funkel AI

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

Annotations already flag destructive=true, readOnly=false, and idempotent=false. The description adds meaningful context beyond that: it names the fields stamped (status, reviewed_at, campaign_id), describes the two-phase preview/confirm mechanism, and notes downstream pipeline ingestion. It does not explicitly address reversibility, which would round this out.

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, but the description is lengthened by overlapping two-phase narration and the 'over MCP: call once' instruction, which sit in tension and force the reader to reconcile them. Some sentences duplicate schema 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 no output schema, the description usefully covers the return (confirmation token + preview, then result). For a mutation tool it is largely complete, though it could state more about irreversibility given idempotent=false and destructive=true.

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

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

Schema coverage is 100%, so the schema already documents all six parameters including the conditional campaign_id requirement the description restates. The description adds context on what approval produces but little syntax/format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb pair (approve/reject) and resource (discovered leads) with clear scope ('one or more'). It is readily distinguishable from siblings like find_leads and import_search_leads_to_list, which cover discovery/import rather than decisioning.

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

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

Explains the conditional requirement (campaign_id needed for approve, not for reject) and the confirmation-token flow, which tells the agent how to invoke it. It lacks explicit when-to-use-vs-alternative routing and the two-phase vs 'call once over MCP' framing is somewhat muddled.

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 flag destructive/openWorld/non-idempotent; the description adds what those mean in practice: it previews searches, enabled state, and LinkedIn resolution, then requires explicit approval. It also discloses integration dependencies (X account required, HN uses public provider) and the MCP call flow (call once, omit confirmation_token, runs immediately).

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

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

Front-loaded with purpose, then workflow and guardrails; every sentence carries operational information. It is dense and long, but no sentence is filler, so it stays efficient despite its size.

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

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

With no output schema and eight parameters, the description fully covers the mutation workflow: preview, approval, what it does not do, dependencies, and the MCP invocation pattern. An agent has everything needed to call it correctly and in the right sequence.

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 baseline is 3, but the description adds meaning the schema does not: the approval lifecycle for confirmation_token, the '1-10 precise searches' constraint on queries, and the fact that the LinkedIn resolution choice is surfaced for approval rather than applied blindly.

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 ('Configure X or Hacker News searches for one owned agent and set source listening') and names the sibling it is not ('use set_agent_source_listening instead'). An agent can distinguish it from the ~50 siblings 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 prerequisite ('First call get_agent_sources'), conditional branches for the no-source and existing-source cases, an exclusion ('does not activate a draft or paused agent'), and an alternative tool for the no-change case. Nothing 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?

Beyond the annotations (destructiveHint=true, idempotentHint=false, openWorldHint=true), the description discloses exact approval requirements, version concurrency control, retry replay limits ('completed effects cannot replay'), pause's inability to stop an executing provider call, and MCP-specific token behavior. This is rich operational context well beyond 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?

The description is front-loaded with the core operations, then layers constraints and MCP-specific behavior in four tight sentences. Every sentence carries distinct operational 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 a complex destructive mutation tool with no output schema, the description covers approval, versioning, retry constraints, pause limitations, and MCP execution semantics. Together with the annotations, it gives the agent everything needed 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 100%, so baseline is 3, but the description adds useful semantics: 'Supply its current version' ties expected_version to concurrency, retry requires a failed idempotent local-read step (linking step_id to a specific condition), and confirmation_token should be omitted on the first MCP call. These go beyond the schema's field 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 names the exact resource ('durable Operator task') and four specific control operations (pause, resume, cancel, retry), clearly distinguishing it from sibling read/list tools like get_operator_task and list_operator_tasks. An agent can identify its purpose 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?

It states critical usage conditions: exact approval, supplying the current version, the retry precondition of a failed idempotent local-read step, and the pause limitation. It does not explicitly name alternatives (e.g., use get_operator_task to inspect first), but the context and exclusions are clear.

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

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

Annotations already flag destructive/non-idempotent, and the description adds substantial behavior beyond them: the two-phase preview-then-confirm flow, that the result is a draft agent, ICP merge/override semantics, how empty arrays and empty signal sets behave, and the default signal seeding rule. No contradiction with the annotations.

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

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

The core contract (create draft agent, two-phase, MCP single-call) is front-loaded and most sentences carry operational rules. It is dense and a few clauses duplicate schema text (excluded_companies URL handling, signal field list), which keeps it 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?

For a 9-parameter, nested-object tool with no output schema, the description covers the operational essentials: invocation mode, confirmation flow, ICP inheritance/override, signal seeding and defaults, and the limit that some settings can't be represented. An agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks: icp_filters keys override only those keys while saved fields persist, excluded_companies stores exact employer names and converts LinkedIn URLs to slug names retained in competitor_urls, and signals entries must carry platform/category/key/label/enabled/config. This goes beyond the schema's field-level 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 ('Create a new draft agent under the request's scoped app') and immediately characterizes it as a two-phase preview-then-create operation. The scope (draft agent, scoped app) is specific enough to separate it from sibling mutation tools like update_icp or enable_agent.

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/when-not guidance: omit icp_filters to inherit the saved ICP untouched, pass only the keys the user asked to change, use [] to clear a list, supply signals only when the user selects explicit signals, and 'call this tool once, without confirmation_token' over MCP. It also tells the agent not to claim a setting was saved if the schema can't represent 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?

Annotations already declare the write/destructive/idempotent profile, and the description adds real behavioral context: an approval step is required before creation, the retargeting-vs-destination-list rule, and that over MCP it runs immediately without a confirmation_token. It does not explain what the destructiveHint=true implies (what a draft creation can overwrite), 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?

Purpose and the key constraints are front-loaded, and the procedural sentences (ask about type, delay, mode, template, final step) each carry usable instruction. It is dense but nearly every sentence earns its place; only slight redundancy between the description and schema on message_template variables.

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

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

For a mutation tool with no output schema and full schema coverage, the description covers approval flow, parameter resolution, defaults, and MCP invocation semantics, and states it 'returns the result'. The main omission is any explanation of the destructiveHint implication, which an agent would otherwise have to guess.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning: the agent_id/list_id resolution logic (agent's destination list, else product default assigned to both), the default 4-step workflow when workflow_steps is omitted, the questions to ask for custom steps, and the allowed template variables. This goes meaningfully beyond the field 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?

States a specific verb+resource ('Create a draft campaign') and immediately distinguishes scope with 'Never activate, discover, enroll, or send', which separates it from enable_campaign, create_agent, and similar siblings. An agent can identify this tool's 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?

Gives explicit conditional guidance: with agent_id and no list_id use the agent's destination list; omitted workflow_steps yields the standard 4-step flow; custom steps require asking about type/delay/mode/template/final step. It also states the negative space ('Never activate, discover, enroll, or send') and the MCP invocation rule (call once, omit confirmation_token).

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 non-read-only, non-destructive, non-idempotent, closed-world. The description adds real context beyond that: the list starts empty, how to populate it later, and the MCP calling convention (call once, no confirmation_token, runs immediately). The 'call this tool once' guidance helpfully reinforces the non-idempotent hint.

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 scoping are front-loaded, and the sentences largely earn their place by covering usage, follow-up path, and calling convention. The MCP-specific sentence adds a bit of length but carries actionable information.

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

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

For a two-param create tool with no output schema, the description covers purpose, trigger, state semantics, follow-up, and invocation behavior. It only gestures at the return value ('returns the result'), which is the one 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 description coverage is 100% with only 2 params, so the schema already documents both fields fully. The description adds name examples ('Q4 Targets', 'Hot Founders') but no syntax or constraint detail beyond the schema's 1-100 char range. 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+resource (create a new lead list) and adds the scoping constraint (scoped to the request's app), which distinguishes it from siblings like get_list, list_lists, and rename_list. An agent can identify the operation without opening the schema.

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

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

Gives a clear when-to-use trigger ('when the user wants to organise leads into a named bucket') and names the follow-up path (approve_leads with action='approve'). It does not explicitly state when *not* to use it, nor does it mention the closer sibling import_search_leads_to_list, so it falls short of a 5.

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

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

Annotations mark this destructive, non-idempotent and mutating. The description adds real context the annotations cannot: confirmation is expected before calling, request_key is single-use and fails on a changed intent, and the MCP path skips confirmation_token and runs immediately. It does not say what record state is affected or how failures surface.

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

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

Three sentences, all load-bearing: precondition, idempotency constraint, and the MCP-specific invocation path. Front-loaded with the action and confirmation requirement.

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 the confirmation flow and execution path in a mutation tool with no output schema. The main missing piece is where the note lands (on a lead, scoped how) and what the agent gets back beyond 'returns 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%, so every parameter is already documented including reminder_body's dependency on reminder_at. The description only adds the request_key uniqueness rule in prose; it does not elaborate on lead_id, body limits or due date format beyond the schema.

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

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

States a specific verb and resource: 'Create a scoped note or reminder'. It distinguishes itself from create_reminder by framing the note as attached to a lead, but the boundary with create_reminder is never explicitly drawn.

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 precondition: 'after an explicit confirmation of the exact lead, body, and due date', and tells the agent what to do over MCP (call once without confirmation_token). It stops short of naming alternatives such as create_reminder for standalone reminders.

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

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

Annotations already flag destructive=true and idempotent=false; the description adds genuinely new behavioral context: the request_key is single-use and a changed intent under the same key fails, and that over MCP it executes immediately without a confirmation_token. It stops short of saying what the destructive effect is or what happens on a retry after failure.

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 its precondition, then the idempotency rule, then the MCP calling convention. No filler; only 'scoped' is left undefined.

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 tool with no output schema, it covers the confirmation/idempotency workflow and the MCP invocation path adequately. Minor gap: no statement of the side effects implied by destructiveHint=true or post-failure retry behavior.

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 semantics the schema lacks: request_key's one-application-only constraint and the MCP-specific rule to omit confirmation_token, which materially changes how the caller uses those two 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+resource ('Create a scoped note or reminder') and conditions it on prior confirmation of lead, body, and due date. However, it does not distinguish itself from the sibling create_note, despite claiming to create 'a note or reminder', leaving overlap unresolved.

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 workflow guidance (confirm exact lead/body/due date first; call once without confirmation_token over MCP), which implies when the tool fits. But it never states when to use this versus create_note, list_reminders, or get_scheduled_action, so alternative selection 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 mark this readOnly/idempotent/non-destructive, and the description reinforces the key trait ("Does NOT write") while adding real context the annotations don't cover: the diff-envelope review workflow and the staging-then-apply sequencing with update_icp. No contradiction with the readOnlyHint.

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

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

Front-loaded with the core action and its return value, then routing and prohibition. Every sentence carries distinct information with no redundancy.

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

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

No output schema exists, so the description appropriately explains the return (diff envelope structure), and it covers the staging/apply relationship fully. 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 agent_id, proposed_icp_filters, and proposed_icp_description are all documented in the schema. The description only repeats that update_icp needs "the same agent_id and proposed fields" without adding format or syntax detail, so it earns the baseline 3.

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 ("Stage a proposed ICP edit") and describes exactly what it produces (a diff envelope with current vs proposed and fields_changed). It clearly distinguishes itself from the sibling update_icp, which is the apply/write counterpart.

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 ("when the user describes a change in plain language"), an explicit prohibition ("never call update_icp directly without first staging here"), and a named alternative with its condition (update_icp, confirm-tier, same agent_id). Routing 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 declare non-readOnly, non-destructive, non-idempotent and open-world, but the description adds real substance: the preconditions on reply_state, the fact that approval must precede sending, and that the call executes immediately without a confirmation_token. The one gap is that it never says whether the generated draft is persisted or how repeated calls (non-idempotent per annotations) relate to each other.

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 its scope, then preconditions, then the send handoff, then MCP mechanics – a logical order with no filler paragraphs. Only minor redundancy in 'It runs right away and returns the result', which restates the immediately preceding instruction.

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 correctly covers the return ('a single message body'), the non-sending boundary, the approval loop that triggers send_message, and the hard precondition on lead state. An agent has everything needed to call it correctly and to know what happens next.

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 tone, lead_id and reference are already documented with formats and an enum, which sets the baseline at 3. The description adds modest value by describing the profile fields it reads and framing reference as an 'optional specific hook', but clarifies nothing about tone or lead_id sourcing beyond the schema.

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

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

States a specific verb and resource with explicit scope: 'Generate a personalised draft for one lead' and 'returns a single message body'. It also carves itself apart from the send path by stating 'Does NOT send', which distinguishes it from send_message and prepare_conversation_reply among the siblings.

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

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

Gives explicit sequencing (call get_lead first, then draft, then user approval, then send_message), an explicit exclusion ('refuse to draft for opted-out / replied / rejected leads'), and MCP-specific invocation guidance (call once, without confirmation_token). When-to-use, when-not-to-use, and the alternative tool are all 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?

Annotations already declare destructive/non-idempotent/open-world, and the description adds real value on top: the two-phase confirmation-token flow, what the first call returns (token + preview), and the MCP-specific single-call behavior. It does not state permission requirements or reversal options, so it stops short of a 5.

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

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

Three short sentences with the action and preconditions front-loaded, then the phase protocol, then the MCP exception. Efficient, though the phase-1/phase-2 explanation is somewhat densely packed.

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

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

For a state-changing tool with no output schema, the description covers preconditions, the confirmation protocol, and the MCP override, which is enough to call it correctly. It omits what the 'result' payload contains and any rollback/permission notes.

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 3 is the baseline; the description adds the meaning behind confirmation_token by explaining the phase-1 vs phase-2 protocol and that it should be omitted over MCP, which is more than the schema field text conveys.

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 (enable/activate) and resource (agent), plus the preconditions ('paused or draft') and the outcome ('begins discovering leads on its schedule'). It is clearly distinguishable from siblings like pause_agent and enable_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?

Explains when the tool applies (a paused or draft agent) and gives explicit, branch-specific instructions for the MCP path versus the two-phase path. It does not name a sibling alternative, but the trigger condition 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 declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it discloses the side effect (engine begins scheduling per workflow), the two-phase confirmation contract, pre-condition validation (workflow steps, connected accounts), and that failures surface as structured errors. This is exactly the mutation context the annotations cannot 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-loaded with the purpose and side effect, then flows into the two-phase mechanics and the MCP-specific note. It is slightly repetitive around the confirm/preview step, but the length is defensible given the two-phase complexity.

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

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

With no output schema and four parameters, the description covers phase-1 return (confirmation token + preview), the commit path, validation failures, and MCP behavior. The only thin spot is the vague 'returns the result' for the MCP one-shot path; otherwise it is complete enough 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 100%, so the baseline is 3. The description adds real usage semantics for confirmation_token — omit it on phase-1, supply it on phase-2 to commit — which the schema alone does not explain, plus notes app_name and campaign_name feed the confirm preview.

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 plus resource ('enable (resume) a paused or draft campaign') and immediately clarifies the state transition and that the engine starts scheduling actions. An agent can distinguish this from pause_campaign and create_campaign_draft 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?

Clearly identifies the applicable campaign state (paused or draft) and walks through the confirm-then-commit flow, including the MCP override (call once without confirmation_token). It never names an explicit alternative or a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint/idempotent/destructive, so the safety profile is covered; the description goes beyond them by disclosing the return boundary ('bounded named summaries and IDs, never full rows') and the semantic meaning of the default source (agent-found, awaiting approval) plus the escalation policy on thin results. That is real behavioral context, not a restatement of 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?

Dense but front-loaded: purpose and scope first, then the alternative tool, then the source default, then filter behavior, then the escalation rule. No filler sentences and no repetition of schema constraints such as the 1..50 limit.

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 carries the burden of describing returns — which it does ('bounded named summaries and IDs, never full rows'). Combined with the default-source semantics and the explicit alternative tool, an agent has everything needed to call this 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 baseline is 3, but the description adds genuine meaning: what 'source' values signify (discovered = agent-found awaiting approval vs approved = already in campaigns) and that 'search' runs an ILIKE across name/company/headline. 'status' only gets a restatement, keeping this just short of a 5.

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

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

States a specific verb+resource ('Search leads') along with its scope ('the app the request is scoped to'), which distinguishes it from search_external_leads and other list/pull tools in the sibling set. It also names get_lead as the detail-loading counterpart, so an agent can route correctly 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?

Explicit routing: 'Use get_lead to load full detail for a specific id.' Explicit default and override for source ('discovered' by default; pass source='approved' for leads already in campaigns). It even prescribes behavior when results are thin ('surface the count and ASK the user before broadening the filters — do not silently relax constraints'), which is guidance an agent could not 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuine behavioral context beyond that: entitlement conditions (paid/lifetime for Operator, beta for campaign actions), that feature flags are account-wide, and crucially that the result is 'not an action authorization or credit quote' — a boundary/caveat that prevents misuse.

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 purpose, then entitlement rules and a boundary caveat. Every sentence conveys actionable information with no filler.

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

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

With no output schema, the description carries return-value burden but adequately signals what the snapshot represents and what it is not, which is the key semantic an agent needs. It stops short of describing the return shape, but for a zero-parameter read tool this is a minor 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?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond what the empty schema already implies.

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

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

States a specific verb (read) and resource (current account access for Operator and campaign actions in the selected product), which is more than a tautology. It differs from the many get_* siblings (get_product_context, list_preferences) by targeting entitlement/access state, though it doesn't name a sibling to route the agent explicitly.

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

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

The description implies the usage context by explaining entitlement requirements for Operator and campaign actions, but never states when to call this versus alternatives like get_product_context or a campaign fetch. No explicit when/when-not guidance 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, but the description still adds real context: it returns unconfigured sources too, and a draft/paused agent does not collect until activated. It also scopes out LinkedIn signal groups, which is a useful boundary. It stops short of describing shape or size of the returned payload.

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, then routing and behavioral caveats follow in logical order. Six sentences is on the dense side, but nearly every one carries a distinct condition or constraint that an agent needs.

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

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

There is no output schema, so the description reasonably explains what comes back (sources including unconfigured ones) and the activation caveat. Combined with the routing guidance, an agent has enough to call and follow up correctly; only the exact return structure is left unstated.

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

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

Schema coverage is 100%, so both agent_id and app_id are already fully documented in the schema. The description only implies the 'one owned agent' scoping and adds no format or constraint detail beyond the schema. 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 ('Read X and Hacker News listening settings for one owned agent') with a clear scope note ('including sources not configured yet'). It is immediately distinguishable from configure_agent_source and set_agent_source_listening, which it names.

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

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

Gives explicit routing: use list_agents to find the agent, configure_agent_source when configured is false, and set_agent_source_listening when configured is true and searches exist. The when-to-use branches are fully spelled out with the condition that selects each alternative.

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

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

Annotations already cover the read-only, idempotent, non-destructive safety profile, so the description's job is to add semantics. It does so well, disclosing that completed actions/invitations key off executed_at while connections/replies use lead event timestamps, and that the numbers are separate counts rather than a single conversion cohort.

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 what is returned, followed by the timestamp semantics and the window limits. Every sentence carries information; nothing is padded, though the timestamp sentence is dense.

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

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

With no output schema, the description usefully characterizes the return as separate event counts and explains the timestamp basis, which is what an agent needs to interpret results. It stops short of describing the shape/pagination of the payload, but the semantic guidance is strong.

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 parameters are already documented (scope defaults to 'app', days_back default 7 / max 90, campaign_id required when scope='campaign'). The description only echoes the default/max window and the dual scope, adding little beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Return) and resource (product- or campaign-scoped activity counts) with a clear scoping dimension. It is distinguishable from most siblings, though it never names or contrasts with the nearby insight tools (get_insight, list_insights).

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 through the scope parameter ('product- or campaign-scoped'). There is no statement of when to reach for this tool versus get_insight/list_insights, and no exclusions or prerequisites are given, leaving selection 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 readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real context beyond that: it enumerates what is returned (updated_at for approved settings changes, workflow, sender assignments, schedule, review mode, action state, readiness blockers) and clarifies two non-obvious behaviors – empty templates are not claimed as generated, and no sending or activation occurs.

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, then return content, then behavioral caveats. Every sentence carries information; the middle enumeration is long but purposeful given no output schema exists.

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 takes on responsibility for describing the return payload and the absence of side effects. Combined with full annotation coverage and a fully documented single parameter, an agent has nearly everything needed; only explicit routing versus list_campaigns is missing.

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

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

Schema description coverage is 100% and campaign_id is fully documented with UUID format and example, so the schema carries this dimension. The description adds only 'in the selected product' as ambient scope context and nothing about the identifier itself; 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+resource ('Read one campaign') with clear singular scope that implicitly separates it from list_campaigns. It does not explicitly name the sibling it contrasts with, 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?

Usage is implied by 'Read one campaign in the selected product' – fetch a single campaign by id rather than enumerating. There is no explicit when-to-use guidance, no exclusions, and no mention of list_campaigns or the update/enable/pause siblings as 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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds value by scoping the return as 'bounded' and enumerating its contents, and by restating that no messages are drafted or sent. It stops short of describing pagination or how 'bounded' is enforced relative to the limit parameter.

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

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

Two sentences, both dense and front-loaded: the return contents first, then the usage guidance and the read-only caveat. The enumeration is long but every element earns its place by telling the agent what it will receive.

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 explaining return contents and does so thoroughly. The only gap is that neither lead_id nor conversation_id is required, yet the description doesn't state that at least one identifier must be supplied.

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

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

Schema description coverage is 100% with explicit UUID formats and the limit default/max documented in-schema, so the baseline is 3. The description only echoes 'bounded' context without adding syntax or selection semantics (e.g., lead_id vs conversation_id precedence).

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 ('Return bounded conversation context for one lead or conversation') and enumerates the payload: lead profile, product/campaign context, messages, notes, reminders, follow-up suggestions. This delineates it clearly from profile-only siblings like get_lead and from get_product_context.

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 triggers ('before meeting prep, reply planning, or questions about what happened with a lead') plus an implicit when-not by noting it 'does not draft or send messages', routing authors to prepare/send_conversation_reply instead. Nothing 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the closing 'Read only' is largely redundant. However the description adds real behavioral context beyond annotations: the result is capped at four items, includes source IDs and links, and the scope rules differ by source type (account-wide for senders/insights versus product-scoped for leads, actions, campaigns, unread messages). That scoping distinction is genuinely useful and not available anywhere else.

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

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

Two sentences, front-loaded with the action and result shape, then the scoping rules. Dense but efficient. The trailing 'Read only' is the one sentence fragment that does not earn its place, since the annotations already assert it.

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

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

With no output schema, the description carries the burden of explaining returns, and it does so only partially: 'operational starting points' is jargon that is never defined, and the ranking criteria behind 'rank' are unexplained. An agent knows roughly what the call yields and its cap, but not why items are ordered as they are or how to present them.

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

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

The tool takes zero parameters, which is the baseline-4 case under the rubric; there is nothing for the description to clarify. The scope language ('within the selected product') hints that context is supplied externally, but no parameter exists to describe.

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

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

The description gives a specific action (rank up to four items) and enumerates what those items are: connected senders, insights, leads, actions, campaigns, and unread messages, returned with source IDs and links. It is clear enough to distinguish this from a generic list tool. It stops short of naming or contrasting any sibling (e.g. get_inbox_queue, get_analytics), so it does not earn a 5.

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

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

There is no when-to-use statement, no exclusions, and no routing to alternatives, which matters in a family of ~50 tools containing get_inbox_queue, get_analytics, get_product_context and others that could plausibly be the 'start of my day' call. The word 'daily' implies a session-start use case, but that is inference rather than 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 cover the safety profile (read-only, idempotent, non-destructive), and the description adds real behavioral context beyond that: 'One predicate determines both the total and page' and 'AI drafts are not counted as sent replies' are non-obvious counting semantics. Pagination behavior via limit/offset is also noted.

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

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

Four short sentences, each carrying a distinct point (scope, predicate behavior, counting rule, pagination), with the queue scope front-loaded. Efficient with no filler, though slightly clipped in tone.

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?

A read-only list tool with no output schema, so the description ought to say more about the returned shape or the total field it mentions. It covers pagination and counting semantics adequately but leaves the return payload undocumented for a tool where the schema is silent.

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 mode, limit, and offset, and the baseline is 3. The description mostly restates the limit/offset mechanics already in the schema rather than adding format or edge-case 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 ('List') and resource ('reply-needed conversations or due follow-ups'), and the two modes map cleanly to the 'mode' enum. It is clear what the tool returns, though it never differentiates itself from siblings like get_conversation_context or get_daily_priorities.

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 phrasing 'in the selected product' implies a product-scoped context but gives no explicit when-to-use signal or named alternative. An agent must infer that this is the queue view for triaging replies versus other conversation 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is largely covered. The description still earns credit for the non-obvious guarantee that 'proposed changes never run here', which is a behavioral claim the annotations do not express, plus the note that evidence is returned alongside the insight.

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

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

Two sentences, zero filler, front-loaded with the core action. The scoping constraint and the read-only guarantee are each stated once and earn their 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 trivial single-parameter read tool with full annotation coverage, the description is sufficient and even hints at the return payload ('its evidence') despite no output schema. The only gap is the absence of any pointer on how the agent should source the insight_id.

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% for the single required insight_id parameter, including UUID format guidance, so the schema already carries the semantics. The description adds nothing about the parameter and merely implies its role through 'one insight', making the baseline 3 correct.

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

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

States a specific verb and resource ('Read one insight and its evidence'), which cleanly separates it from the sibling 'list_insights'. The scoping qualifier ('for the selected product, or an explicitly account-scoped insight') adds precision. It falls short of 5 only because it never names the alternative tool it is not.

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 establishes the calling context (product-scoped by default, account-scoped when explicit) but gives no explicit guidance on when to prefer this over 'list_insights' or how an agent should obtain a valid insight_id. 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 declare readOnlyHint, idempotentHint and destructiveHint=false, so safety of the call itself is covered. The description adds genuinely new context: the tool returns derived flags and acts as a gate that must precede any messaging. It stops short of describing error behavior (e.g. unknown lead_id) or the full response shape, 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?

Three sentences, front-loaded with what is returned, then the safety-critical invariant, then parameter routing. The long em-dash sentence earns its length by encoding a hard precondition, and there is 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?

No output schema exists, and the description compensates by naming the key derived fields returned. With only two parameters, full schema coverage, and rich annotations, an agent has everything needed to call this correctly and safely.

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 earns an extra point by giving operational meaning to source beyond the schema's terse 'Lead source. Default discovered.': approved maps to active campaigns and discovered to leads awaiting approval.

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 ('Return full detail for a single lead by id') and names the derived fields it surfaces (reply_state, opt_out). This clearly separates it from find_leads and search_external_leads, which locate leads rather than return one lead's full state.

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 mandates when to use it: 'Always call this before drafting or sending a message', plus when-not conditions tied to reply_state/opt_out values. It also routes the source parameter to the right scenario (approved = active campaigns, discovered = pending agent-found leads).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real non-annotation context: only unarchived lists are read, the result includes an exact member count, and contacts are deliberately excluded. It does not mention failure behavior for missing/archived ids, keeping it below 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, zero filler, with the core action front-loaded and the exclusion/routing note trailing. Every clause earns its place.

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

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

With no output schema, the description carries the return-value burden and does so: it states the member count is returned and contacts are not. Combined with annotations covering the safety profile and a fully documented single parameter, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the sole list_id parameter is already documented with UUID format and an example. The description contributes no additional parameter meaning (no constraints on archived ids, no format notes), so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Read one unarchived list in the selected product') plus scope details (unarchived, selected product, exact member count). It also explicitly distinguishes itself from list_list_contacts, so an agent can separate it from a large sibling set 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 provides an explicit when-not and names the alternative: 'Does not return contacts; use list_list_contacts.' That is clear routing guidance. It lacks a positive statement of when to prefer this over list_lists or get_product_context, so it stops short of full when/when-not/alternatives 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 carry the read-only, idempotent, non-destructive profile, so the safety bar is met elsewhere. The description still adds real value by disclosing negative scope ('Does not return executable arguments or raw provider errors') and naming what is returned, which meaningfully distinguishes it from control_operator_task.

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

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

Two tight sentences, the positive statement of contents is front-loaded ahead of the exclusion clause, and no sentence is redundant with 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?

With no output schema, the description usefully enumerates the fields returned and what is withheld, which compensates well. It omits minor operational details such as behavior when the task_id is unknown or stale, and it does not define what a 'durable Operator task' is for an unfamiliar agent.

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 description coverage is 100%, so the schema already documents the UUID format and example. The description adds nothing further about task_id (e.g. where to obtain it), 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 ('Read') and resource ('one durable Operator task') with the scope 'one', which separates it from list_operator_tasks, and enumerates the returned contents (step states, action states, version, progress). An agent can distinguish it from the read sibling and from control_operator_task 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?

Usage is only implied: the required task_id and the singular 'one ... task' suggest this is the lookup-by-id counterpart to list_operator_tasks, but no sentence says when to reach for this tool versus listing or controlling a task. No prerequisites or alternatives are 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?

Annotations already declare readOnly, idempotent, non-open-world and non-destructive, so the safety profile is covered structurally. The description adds a genuine guarantee beyond them: 'No provider credentials or raw unbounded configuration are returned,' which tells the agent the read is bounded and safe to surface. It stops short of describing auth prerequisites or failure modes.

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

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

Two tight sentences with zero waste. The returned-fields list is front-loaded and the negative guarantee follows immediately; nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the fields the agent will get. Combined with annotation-covered safety and a zero-arg schema, this is nearly complete; only the scoping of 'selected product' (how it is selected) is left implicit.

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

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

The tool takes zero parameters, so the baseline is 4 per the rubric. The description correctly implies the read is scoped to an ambient 'selected product' rather than an id argument, matching 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?

States a specific verb (read) and resource (selected product's context) and enumerates the concrete fields returned: name, site, description, ICP summary, language, Product Brain availability, dashboard link. That is far more than a restatement of the name. It stops short of naming a sibling it is distinct from, which keeps it at 4.

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

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

There is no explicit when-to-use statement or comparison against siblings like get_lead or get_analytics. Usage is only implied by the phrase 'the selected product's', which signals it operates on an ambient/current product rather than an id-supplied one. Adequate but leaves the agent to infer context.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the description rightly focuses elsewhere. It adds real behavioral context the annotations cannot convey: what is returned (delivery evidence, next_action), that uncertain delivery needs manual provider review unless an outgoing message is confirmed, and that it never retries or sends.

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 is front-loaded in the first sentence, followed by return contents and one behavioral caveat. Every sentence carries weight, though the 'selected product' clause is slightly vague.

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

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

With no output schema, the description correctly compensates by naming the returned fields (delivery evidence, next_action) and the uncertain-delivery caveat. For a one-parameter read tool with full annotation coverage, this is nearly complete; only explicit routing guidance is absent.

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

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

Schema coverage is 100% and the single request_key parameter is fully documented there (including its origin in send_conversation_reply and length bounds). The description adds only the framing 'stable request_key in the selected product', so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read one reply attempt by its stable request_key in the selected product'), which clearly separates it from the send_/prepare_ conversation tools. It does not explicitly name a sibling it might be confused with, but the resource is narrow enough that an agent can identify it.

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

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

There is no explicit statement of when to use this versus alternatives like get_conversation_context or the reply-preparation tools. Usage is only weakly implied by 'Returns actual delivery evidence and next_action', which hints at a status-check role but names no condition or exclusion.

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 read-only, idempotent, non-destructive behavior, so the bar is lower. The description still adds real context the annotations don't carry: results are 'bounded page' with an 'exact total', and terminal (completed) actions are filtered out, which shapes what the agent should expect from 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?

Three short sentences, zero waste, and the core scope ('List pending, approved, or failed scheduled actions') is front-loaded before the return-shape and exclusion notes.

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 the return contract (one bounded page plus exact total) and the completed-actions exclusion. Remaining gaps around ordering and what 'selected product' means in practice are minor for a simple read 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 limit, offset, and campaign_id are already fully documented with defaults, ranges, and UUID format. The description only restates the optional campaign filter at a higher level and adds no pagination or syntax 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?

Specific verb+resource: 'List ... scheduled actions in the selected product', with the qualifying status set (pending, approved, failed) and an optional campaign scope. It implicitly separates itself from the singular get_scheduled_action sibling, but never names it, so the differentiation is inferred 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?

Scope is defined by the included statuses and the exclusion 'Completed actions are not included', which tells the agent when this tool will and won't return a given action. However, no alternative tool is named and no guidance explains when to prefer this listing over get_scheduled_action or the task/queue siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new context beyond the annotations by naming the fields returned and explicitly excluding provider metadata and the message body, which prevents the agent from assuming a full payload.

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

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

Two compact sentences with no filler: the read verb and scope lead, followed by the return/exclusion clause. The phrase 'in the selected product' is unexplained jargon, a minor deduction, 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 does the necessary work by listing the returned field families and the two notable omissions. Combined with annotations covering the safety profile and a fully documented single parameter, the definition is nearly complete; it only omits behavior for an unknown or missing action_id.

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

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

Schema description coverage is 100% and the single action_id parameter already documents UUID format and an example value, so the description adds no parameter-level detail. The baseline of 3 applies when the schema carries the full burden.

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

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

States a specific verb and resource ('Read one action') and enumerates the fields returned, which is well beyond a tautology. It does not, however, explicitly distinguish itself from the sibling 'get_schedule' or 'get_campaign', leaving the agent to infer the singular-vs-collection distinction from the name.

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 reach for this tool versus 'get_schedule' or 'get_campaign', nor any prerequisite or exclusion. The only implicit cue is that a single action is retrieved by id, which the agent must 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 carry the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds useful semantic framing about two health dimensions, but says nothing about return format, freshness, or what 'health' concretely means beyond the connection state.

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

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

Two tight sentences, front-loaded with what is shown, followed by the key caveat. Nothing is wasted or redundant.

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

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

With no output schema, the description reasonably frames the two things the result covers, which is enough for a zero-parameter read tool. It stops short of describing what fields or statuses 'health' and 'readiness' actually surface.

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

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

Zero parameters, so the baseline of 4 applies; there is no parameter surface the description needs to explain.

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 ('show') and resource ('connected sender health') and splits it into two scopes: account-wide connection health versus per-campaign assignment readiness. That scoping makes the tool's identity clear without naming a specific sibling, 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 line 'An account-wide connection does not prove a campaign has a usable sender' implies you call this before trusting a sender for campaign work, but it never states when to use it versus alternatives (e.g. get_access or list_campaigns) nor any 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 non-idempotent; the description adds valuable flow detail (two-phase confirm, inline card preview, phase-1 vs phase-2 token, MCP single-call behavior) that the annotations don't convey. It stops short of saying what happens to previously imported rows or how duplicates are handled, so it's 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?

Front-loaded with purpose, then the two-phase flow, then parameter decisions, ending with the MCP-specific shortcut. Sentences are dense and purposeful, though the final MCP paragraph slightly re-frames the earlier two-phase narrative and reads as a mild afterthought.

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 non-idempotent, destructive mutation with no output schema, the description explains the return shape (confirmation token, preview, committed list_id) and the MCP invocation path, leaving no ambiguity about how to call it correctly. 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: provider_ids omitted means import all, and list_id vs list_name is a mutually exclusive create-vs-use choice. That mutual-exclusivity semantics is not stated in the schema itself.

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 (import), the resource (lead rows), the source (a prior search_external_leads session), and the destination (a lead list). This clearly distinguishes it from siblings like search_external_leads (which finds leads) and create_list (which only creates a list).

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 covers each decision point: omit provider_ids to import everything, use list_id for an existing list vs list_name to create one, and call once without confirmation_token over MCP. It also names search_external_leads as the required prior step and gives downstream guidance about reusing the returned list_id for campaign creation.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds value on top: it discloses that output is a collapsed summary, that internal agent types are remapped to product-facing roles like lead_finder, and that full ICP filters are truncated to a one-liner. That mapping/truncation behavior is exactly the kind of non-obvious trait an agent cannot infer from annotations.

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

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

Front-loaded with the core action and scope, then return shape, then the transition path to get_agent, then usage examples. The enumerated return fields earn their place because no output schema exists to carry them.

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 explicitly spells out the return payload (count, one-liner, list of {id, name, status, type, role, icp_summary}) and the truncation caveat, so nothing an agent needs to interpret results or decide on a follow-up call is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description has no parameter surface to explain, and it correctly avoids inventing any input requirements.

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

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

States a specific verb and resource ('List the specialist agents') plus the scope ('in the product/app the request is scoped to'), and distinguishes itself from the sibling get_agent by defining this as the summary view. An agent can tell exactly what this returns 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 behavior: 'call get_agent (later) to load full detail' names the alternative and the condition that selects it, and it gives concrete example questions ('how many specialist agents do I have?') that anchor when to reach for 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description goes beyond them by disclosing the return shape (count, one-liner, list of {id, name, description, url}) and noting the absence of timestamps and internal flags. It does not discuss permissions or rate limits, so 4 rather than 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: purpose first, return contents second, usage/anti-usage third. Every sentence earns its place and the negative guidance is placed last where it will not obscure the primary purpose.

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

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

With no parameters and no output schema, the description compensates by describing return contents and by clarifying the implicit scope mechanism. Nothing needed 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing to document. The description usefully explains that scoping comes implicitly from the request Scope's app_id, which is context the empty schema cannot convey.

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

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

States a specific verb+resource with scope: 'List the products/apps owned by the request scope's user.' It is clearly distinguishable from siblings like get_product_context, list_agents, and list_campaigns. An agent knows exactly what this retrieves 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 explicit positive triggers ('product inventory or explicit product-switch/disambiguation questions') and an explicit negative exclusion ('do not call this just to discover which product to use for product-aware actions'), backed by the reason (app_id already in Scope). This is textbook 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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real context beyond that: archived campaigns are excluded, settings JSON is deliberately omitted and where to get it instead, and the returned field set. It does not address ordering, pagination, or scoping/permission limits, which keeps it from a 5.

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

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

Scope and exclusion are front-loaded, and each subsequent sentence (return shape, omission rationale plus alternative, status enum) carries distinct information. Slightly dense with nested parentheticals, 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?

With no output schema, the description must describe returns, and it does: count, a brief one-liner, and the item fields {id, name, status, agent_id, list_id}, plus the allowed status values. For a zero-parameter read tool with full annotation coverage, 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?

The tool takes zero parameters, so the baseline for this dimension is 4. The description appropriately uses no space explaining inputs and instead spends it on scope and outputs.

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

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

A specific verb (List) plus resource (campaigns) plus scope (the app the request is scoped to) with an explicit boundary (excludes archived). It names the sibling get_campaign and states exactly what is not covered here, so the agent can distinguish the two without inspecting 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 clearly routes the agent to get_campaign for workflow, sender, and action detail, and the '(excludes archived)' note sets a usage boundary. It does not state a full when-to-use/when-not-to-use rule set or mention other list-style siblings, so it stops 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world behavior, so safety is covered. The description adds useful behavioral context — that each item self-labels its scope and that pagination yields an exact total with bounded pages — but says nothing about ordering, filtering, or what an 'open' insight state implies.

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 resource and scope, no filler. The clause 'account insights are not product-only' is a slightly redundant restatement of the scope-labeling sentence and costs it the top mark.

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 list tool with no output schema, the description covers scope, labeling, and paging semantics, which is adequate. It still omits what an 'insight' actually is, whether results are ordered, and what 'open' means, leaving real gaps for an agent deciding whether to call it.

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

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

Schema description coverage is 100% with only limit and offset, both fully documented with defaults and maxes in the schema. The description adds no parameter-level meaning, 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 ('List') and resource ('insights') plus the scope of returned items (account-scoped and selected-product-scoped open insights), which separates it from the sibling get_insight. However, 'open insights' is domain jargon and it never explicitly contrasts itself with get_insight, so sibling differentiation rests on 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?

There is no when-to-use guidance, no statement of prerequisites or filters, and no mention of the singular get_insight sibling that an agent would otherwise have to guess between. Usage context is only implied by the word 'List'.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely useful context beyond that: it discloses pagination shape ('returns exact total and bounded pages') and a data-exposure constraint ('does not expose email or provider identifiers').

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, tightly front-loaded with the core purpose before the return/data caveats. Every sentence carries distinct information with no redundancy.

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

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

With no output schema, the description compensates by describing the return shape (exact total, bounded pages) and privacy limits, which is what an agent needs to consume results. A minor gap is that it doesn't clarify behavior when list_id refers to an archived or missing 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 coverage is 100%, so limit, offset, and list_id are already fully documented in the schema. The description's mention of 'bounded pages' loosely relates to the paging parameters but adds no syntax, format, or defaults beyond what the schema provides. Baseline 3 applies.

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

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

States a specific verb (list) and resource (contacts) with clear scoping to 'one unarchived list in the selected product', which distinguishes it from list_lists and get_list. It does not explicitly name the sibling it differs from, but the resource specificity makes the intent unambiguous.

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

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

Usage is implied by the resource statement — you call it to enumerate contacts in a given list — but there is no explicit when-to-use guidance or exclusion against alternatives like get_list, find_leads, or search_external_leads. Adequate but leaves selection 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 the safety profile (readOnly, idempotent, non-destructive), so credit goes to what the description adds: it discloses that the total is exact and that the cached lead count is deliberately excluded from it, plus that pages are bounded. These are genuine behavioral caveats not in the annotations, though pagination mechanics remain vague.

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

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

Three short sentences, zero waste, with the purpose front-loaded and the total-count caveat following. 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?

There is no output schema, but the description covers the key return semantics (exact total, bounded pages) and the count caveat. Parameter behavior is handled by the schema. Adequate for a read-only list tool, with only the precise page/return shape left implicit.

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

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

Schema description coverage is 100%, so limit and offset are already fully documented with defaults and maximums. The description only gestures at pagination via "bounded pages" and adds no syntax or format detail beyond the schema. 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 ("List ... lead lists") with a scoping qualifier ("unarchived ... in the selected product"). This clearly distinguishes it from get_list, create_list, rename_list, and list_list_contacts without needing to name them.

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

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

Provides no explicit when-to-use guidance, prerequisites, or alternatives. An agent must infer that this is the enumeration tool versus get_list for a single list, but nothing in the description states that routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds valuable non-structured context: a hard cap of 20 results, and the explicit return contract ('file IDs and metadata only, never bytes or extracted text'). That return-shape disclosure goes beyond the annotations.

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

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

Three tight sentences, each carrying distinct information: what it lists, the return contract, and the usage constraint. The most important scoping (cap of 20, IDs only) is front-loaded with zero 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 parameterless read-only list tool with annotations covering the safety profile, the description supplies the cap, the return shape, and the cross-use constraint — everything an agent needs to invoke and interpret it. No output schema exists, yet the return contract is stated explicitly.

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

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

The tool takes zero parameters and the schema is empty, so there is nothing for the description to clarify. Baseline of 4 applies 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?

States a specific verb (List) and resource (files uploaded to Operator threads) with scope qualifiers ('in the selected product'). This clearly distinguishes it from siblings like list_operator_tasks or list_lists, which target different resources.

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 usage context by noting files are usable for a same-product LinkedIn reply, but it never explicitly says when to call this tool versus alternatives, nor names any sibling to route to. 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 declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered; the description still adds genuinely useful context by disclosing bounded pagination, an exact total, and returned fields (status, version, links). The final "Read-only" sentence is redundant with the annotations but harmless.

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 lean sentences, front-loaded with the action and scope before the return details. The only waste is the trailing "Read-only," which restates an annotation.

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 list tool with no output schema, the description supplies the return shape and pagination behavior that would otherwise be missing. Only the lack of guidance about related tools (get_operator_task, control_operator_task) leaves a small 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%, with limit and offset fully documented in the schema (defaults, max 50, offset cap). The description adds no syntax or semantics beyond the schema, so the baseline 3 applies.

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

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

The description gives a specific verb+resource ("List durable Operator tasks") and scopes it to "the selected product," which distinguishes it from the singular sibling get_operator_task and from control_operator_task. It is clear but does not explicitly name the sibling it replaces.

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: "List" plus the product scope signals a bulk read versus get_operator_task's single fetch, but no when-to-use condition, prerequisites, or alternatives are stated. An agent can infer intent but gets no routing help.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is partly covered. The description goes further with genuinely useful behavioral context: values are bounded, never override user instructions or system rules, and no credentials or tokens are ever returned. These are real traits beyond the annotations, though pagination/ordering behavior for the 20-item cap is unstated.

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, all front-loaded: scope/cap first, safety semantics second, return shape third. Every sentence carries distinct information with no filler.

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

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

With no parameters, no output schema, and annotations covering safety, the description fills the remaining gaps by naming the returned fields (key, value, source) and the safety guarantees. An agent needs nothing more 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 tool takes zero parameters, so there are no parameter semantics to document and the baseline is 4. The description appropriately spends its words on scope and return shape instead.

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

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

States a specific verb (List) and resource (saved Operator preferences) with explicit scope (for the user and product in the request) and a concrete cap (up to 20). An agent can immediately tell this is the read-side counterpart to save_preference 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 implies when to use it (reading saved preferences) but never names the write counterpart save_preference or states exclusions/preconditions for choosing it. Usage is inferable from the verb but not explicitly guided against siblings.

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

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

Annotations already declare readOnlyHint/idempotent/destructive=false, but the description adds meaningful context: results are exact-total with bounded pages, and listing does not complete/settle a reminder. That last point is a real behavioral clarification an agent could otherwise get wrong.

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

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

Two tight sentences; the resource and scope come first, then the default and the non-mutation caveat. 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 read-only list tool with no output schema and fully documented params, the description covers scope, default state, paging semantics, and the key non-effect. Only the exact return shape ('exact total') is left implicit, 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 100%, so limit/offset/status are fully documented in-schema. The description only restates the default status and the paging behavior, adding little beyond what the schema 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 (list) and resource (lead reminders) plus scope (selected product, open or done states). It is clearly distinguishable from create_reminder, though it doesn't explicitly contrast with other list_* siblings.

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

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

Gives the default state ('Default is open') and clarifies it is non-mutating ('does not complete a reminder'), but offers no explicit when-to-use vs alternatives or exclusions such as when to look elsewhere for reminder history.

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

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

Goes well beyond the annotations: it discloses that existing leads are preserved (scoping the destructiveHint), describes the confirmation-token/preview two-phase safety mechanism, and explains what the first call actually returns. The MCP-specific override of the two-phase flow is exactly the kind of behavioral detail annotations cannot 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?

Four sentences, purpose front-loaded, each covering a distinct concern (effect, side effects, two-phase mechanics, MCP behavior). The two-phase sentence is dense but no sentence 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?

With no output schema and no annotations covering the confirm flow, the description carries the burden well: it explains both phases, what is preserved, and the MCP shortcut. It stops short of saying whether pausing is reversible or which sibling re-enables the agent.

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: agent_name and app_name are required for a human-readable preview, and confirmation_token is phase-2-only. That tells the agent why two required params exist rather than merely restating 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 ('Pause an active agent') plus the immediate effect ('stops discovering new leads'), which cleanly separates it from the similarly named pause_campaign sibling. The scope note that existing leads remain prevents misreading the pause as a delete.

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 call sequencing: phase-1 without confirmation_token, then a phase-2 call with the token after user confirmation. It also resolves the runtime ambiguity directly ('Over MCP: call this tool once, without confirmation_token'). It does not name adjacent alternatives such as pause_campaign or enable_agent, so it falls just short of 5.

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

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

Goes well beyond the annotations: annotations only say destructive/non-idempotent, while the description discloses the side effect (stops scheduling), the confirmation-token two-phase protocol, the inline-card review step, and the special single-call MCP behavior. This 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?

Purpose is front-loaded and each sentence carries information, but the description interleaves the general two-phase flow with the MCP-specific path, which requires the reader to reconcile two modes. Still tight, 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, non-idempotent mutation tool with no output schema, the description covers purpose, side effects, parameter intent, and the exact invocation pattern for the MCP environment. 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 coverage is 100%, so baseline is 3, but the description adds value by explaining why campaign_name and app_name matter (human-readable preview) and when to supply confirmation_token (phase-2 only, omit over MCP). That meaning is only partially captured by the schema's terse field 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?

States a specific verb and resource ('Pause an active campaign') and immediately clarifies the operational effect ('the campaign engine stops scheduling actions'), which distinguishes it from siblings like pause_agent and enable_campaign. An agent can identify the tool without opening the schema.

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

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

It gives explicit invocation guidance for this context: 'Over MCP: call this tool once, without confirmation_token. It runs right away and returns the result,' and explains the two-phase flow otherwise. It does not name sibling alternatives or exclusions, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds valuable context by confirming no send occurs, listing what is returned, and scoping file attachment to connected LinkedIn conversations in the selected product. It omits any note on revision conflicts despite returning an 'inbound revision'.

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 front-loaded sentences with the core purpose and the 'Never sends' boundary up front, and no wasted filler. The dense cluster of jargon terms ('inbound revision', 'owned file identity') slightly reduces 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?

With no output schema, the description usefully enumerates the return fields (recipient, sender, channel, revision, signed body, file identity), and annotations plus full schema coverage handle safety and parameters. The weak when-to-use routing against send_conversation_reply is the only real 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 the schema already documents conversation_id, body, and attachment_id with format examples. The description adds no parameter-level meaning beyond noting the booking-link tracking already present in the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Prepare one exact local inbound reply') and immediately differentiates from the write sibling with 'Never sends'. An agent can distinguish this preview tool from send_conversation_reply without opening either schema, though the adjective 'local' is slightly jargony.

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 usage constraint (files work only for supported connected LinkedIn conversations) and the 'Never sends' boundary, but never explicitly says when to prefer this over send_conversation_reply or get_reply_attempt. Usage is implied rather than routed.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds what the annotations cannot: that expected_name exists to 'reject stale changes' (optimistic-concurrency protection), that approval is required, and that the call executes immediately and returns a 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?

Three tight sentences, front-loaded with the action and its constraints. The trailing 'and returns the result' is mild filler, but overall there is little 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 destructive mutation with no output schema, the description covers the approval flow, concurrency guard, and MCP invocation semantics an agent needs. Return-value shape is not required since no output schema exists, leaving only minor 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 100%, so the baseline is 3. The description earns above that by explaining why expected_name is supplied ('to reject stale changes') and clarifying the confirmation_token omission over MCP, information the schema labels alone do not convey.

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

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

States a specific verb and resource with scope: 'Rename one unarchived list in the selected product.' The single-list, unarchived constraint plus the rename action clearly distinguishes it from siblings like create_list, get_list, and list_lists.

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

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

Gives explicit operating context: rename only 'after explicit approval' and, over MCP, 'call this tool once, without confirmation_token.' This tells the agent how the approval gate is bypassed in MCP and that no second confirming call is needed. It stops short of naming any alternative tool, but no rename alternative exists among the siblings.

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

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

Adds substantial context beyond the annotations: 'Existing keys update' discloses upsert semantics, 'No provider credentials or tokens are accepted' documents an input restriction, 'The value is bounded JSON data, not a system instruction' guards against prompt-injection content, and the MCP sentence explains the confirmation-token flow (omit on first call, executes immediately). Annotations flag the destructive profile; the description adds the operational workflow.

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, then built from short, discrete sentences that each carry a distinct fact. The MCP/token sentence partially restates the schema description ('omit on first call'), a minor redundancy, but nothing is padded.

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

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

For a mutation tool with no output schema, the description covers the approval precondition, the MCP invocation protocol, key-update semantics, and credential restrictions, and notes it 'returns the result.' It does not describe failure modes or what the returned result contains, a modest gap.

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

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

Schema description coverage is 100%, so the schema already documents key, value, reason, and confirmation_token, including 'omit on first call'. The description reinforces the token-omission rule and value bounds but adds no new syntax or format detail, 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 (save) and resource (one selected-product Operator preference), with the scope constraint 'one' and 'selected-product'. It does not name the read counterpart list_preferences or any other sibling, so the agent must infer the boundary from the name alone. Clear purpose, but no 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?

'after explicit approval' establishes a precondition, and 'Over MCP: call this tool once, without confirmation_token. It runs right away' specifies the exact invocation path the agent will take. It stops short of naming alternatives (e.g., list_preferences to read existing keys first) or stating when not to use it.

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

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

Annotations already declare openWorldHint=true and non-idempotent, and the description adds real context beyond them: it runs immediately, needs no confirmation_token over MCP, and returns a server-owned session_id plus at most 10 previews. It does not explain why readOnlyHint=false for what reads as a search, nor any rate limits, leaving a 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?

Front-loaded with the core purpose, then the usage condition, the return shape, the import handoff, and the MCP calling convention. Every sentence carries information, though the closing 'It runs right away and returns the result' partly restates the preceding sentence.

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 carries the return-value burden and does so by naming the session_id and the up-to-10 lead previews. Combined with the import handoff and MCP invocation note, an agent has everything needed to call and follow up correctly.

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

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

Schema description coverage is 100%, so query, role, and limit are already documented with examples and bounds. The description's phrase 'words, roles, companies, or market terms' loosely maps to query/role but adds no syntax or format detail 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 (Search), a specific resource (LinkedIn fresh people leads), and the scope (from the request user's connected account). It also distinguishes itself from searching existing saved leads, so an agent can tell it apart from siblings like find_leads and list_list_contacts 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 trigger condition ('when the user describes leads to find by words, roles, companies, or market terms') and the exclusion ('rather than asking to search existing saved leads'). It also routes the follow-up step to import_search_leads_to_list with the returned session_id, giving a complete when-to-use chain.

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 idempotentHint=false; the description goes further by explaining why retries are unsafe (uncertain timeout) and by disclosing file-capability asymmetry (LinkedIn supported, email unavailable). The approval requirement and immediate-execution-over-MCP behavior are additional context not present in the annotations.

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

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

Front-loads the core action and prerequisite, then layers constraints in short sentences; every sentence carries information. Slightly dense with four distinct ideas (approval, inputs, timeout, file support) but 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, non-idempotent write with no output schema, the description covers prerequisites, inputs, failure semantics, and capability limits. It stops short of describing the returned payload structure, though 'returns the result' is a reasonable signal given 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 coverage is 100%, so the baseline is 3; the description earns extra credit by explaining the relationship between 'prepared' and the prepare_conversation_reply output, when attachment_id applies ('when present'), and the purpose of request_key as a stable identity. It does not add field-level validation 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 precise verb and resource ('Send one exact prepared reply to the latest inbound message') and explicitly names the upstream sibling artifact (prepare_conversation_reply result), so the agent can distinguish it from the many other conversation/lead tools. The gating condition (after explicit human approval) further narrows the intent.

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

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

Explicitly states the precondition (explicit human approval), what to supply (complete prepare result, attachment_id when present, stable request_key), and the MCP-specific invocation rule ('call this tool once, without confirmation_token'). It also warns that a timeout is uncertain and non-retryable, which directly shapes correct usage.

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 annotation hints by disclosing the approval mechanics (first call shows exact approval, second commits), what is left unchanged (saved searches, budgets, LinkedIn resolution, other sources), the paused-agent collection behavior, and that over MCP it runs immediately with no confirmation_token. None of this is derivable from the destructiveHint/openWorldHint/idempotentHint flags alone.

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

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

Front-loads the action and scope, then layers prerequisites, approval flow, and transport-specific notes. Dense and mostly waste-free, though a few independent constraints are packed into back-to-back sentences that could be slightly better separated.

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

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

For a state-mutating tool with no output schema, the description covers prerequisites, the approval/confirmation lifecycle, preservation guarantees, downstream activation behavior, and MCP transport differences. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 83%, so the baseline is 3, but the description adds real semantics: confirmation_token is omitted on the immediate-run MCP path, and expected_updated_at ties to the version returned by get_agent_sources. It does not explain enabled/source interplay beyond what the enum already conveys.

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

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

States a precise verb pair (pause/resume) and a tightly scoped resource: an existing X or Hacker News source on an agent. The phrase 'only an existing' plus the explicit routing to configure_agent_source cleanly differentiates it from the nearest sibling.

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

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

Gives explicit prerequisites ('First read get_agent_sources'), a clear when-not condition ('If configured is false or searches are empty, use configure_agent_source instead'), the two-step approval flow, and an MCP-specific invocation rule. An agent knows exactly when to pick this tool and how to sequence 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?

Annotations already declare destructiveHint=true, idempotentHint=false, and openWorldHint=false, but the description adds real value beyond them: a two-phase approval-preview flow, atomic application of changes on approval, optimistic concurrency via expected_updated_at, and the MCP shortcut that runs immediately without a token. It still does not state permission/auth requirements or whether applied changes can be reverted, which keeps it from a 5.

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

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

Seven short sentences, each carrying a distinct fact, with the core action front-loaded before the prerequisites and boundaries. No filler, no 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?

For a six-parameter nested mutation tool with no output schema, the description covers the preconditions, the partial-update semantics, the approval/return behavior, and the MCP calling convention. An agent has everything needed to call it correctly on the first attempt.

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 semantics the schema does not: omitted settings remain unchanged, an explicit null clears one platform's sender, and the read-get_campaign-then-copy flow for expected_updated_at. These meaning-level details exceed what the property descriptions convey.

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

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

States a specific verb (Change) and resource (a campaign's settings), then enumerates the exact mutable surface: manual review, send window, sender assignments. It is clearly separable from siblings like update_campaign_workflow or enable_campaign, which act on different aspects of a 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?

Gives an explicit prerequisite (read get_campaign first and copy updated_at as expected_updated_at), states the omission rule, and draws the boundary against adjacent tools by declaring it never activates, enrolls, or sends. It even routes MCP callers on how to invoke it without a confirmation_token.

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 readOnlyHint=false, and the description adds substantial context beyond them: the two-phase confirmed action, the confirmation card, approved execution persistence, and the explicit 'never launches or sends' guarantee. It also defines allowed personalization variables.

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

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

The description is dense but front-loaded with the core action and selector guidance. It is somewhat long, and the final 'Over MCP' paragraph slightly duplicates the two-phase explanation, but most sentences earn their 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 destructive, stateful update tool with no output schema, the description covers required preview fields, selector rules, template constraints, confirmation flow, and safety guarantees. 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 baseline is 3. The description adds value by explaining selector semantics (one-based message_order skipping invite/follow steps, step_order as a fallback) and the personalization variable constraint, which goes 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 states a specific verb and resource ('Update message content on existing steps') and scopes it to draft or paused campaigns, distinguishing it from siblings like update_campaign_settings and pause_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?

It explicitly says when to use message_order versus step_order, requires exactly one selector, and clarifies that the tool never launches or sends. The two-phase confirmation flow is fully described, including the MCP-specific single-call 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?

Goes well beyond the annotations by disclosing the two-phase confirmation-token protocol, the inline diff preview, and the confirm step, and by explaining the MCP-transport override. Annotations already flag destructiveHint=true / idempotentHint=false, so the added workflow context is real value, though it never states what is destroyed or how partial edits interact with destructive replacement.

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

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

Front-loaded with purpose and the phase flow, and every sentence is substantive. The trailing MCP-transport sentence is short but introduces ambiguity that briefly forces the reader to re-interpret the earlier imperative, costing a point.

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 the mutation workflow, confirmation semantics, and the draft-first prerequisite for a 6-parameter tool with no output schema, so an agent has enough to call it correctly. It falls short of 5 only because it does not state what happens to unmentioned fields beyond the schema's 'omit to leave unchanged' notes, nor clarify which mode takes precedence in a given session.

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: it explains that agent_name should be pre-populated 'so the preview is human-readable' and clarifies the two-phase role of confirmation_token. That is useful guidance beyond the schema's own 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?

States a specific verb and resource ('Apply an ICP edit (description and/or filters JSON) to one agent') and immediately distinguishes itself from the sibling draft_icp_edit by role. An agent can tell what this tool does and how it differs from the draft/preview tool 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?

Gives explicit when-to-use and when-not: 'ALWAYS call draft_icp_edit first so the user sees a before/after; never call update_icp directly without staging a diff,' and names the phase-2 trigger (confirmation_token). The only flaw is the closing MCP clause ('call this tool once... It runs right away'), which sits in tension with the 'ALWAYS/never' instruction and leaves the agent to reconcile the two modes.

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