Funkel AI

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered structurally. The description adds real value beyond that: it describes the two-phase commit gate and the exact fields stamped (status, reviewed_at, campaign_id) and notes downstream pipeline ingestion. It omits token expiry/retry semantics and reversibility, 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?

Purpose and the two-phase contract are front-loaded in the first two sentences, and the trailing sentence about downstream ingestion is genuinely informative. The middle sentences are clause-dense and could be tightened, but nothing is pure 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 6 parameters, a destructive mutation, and no output schema, the description carries the burden well: it explains the phased return (token + preview), the required-parameter asymmetry, and the side effects. An agent has enough to invoke both phases correctly without guessing.

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 semantic meaning the schema does not: campaign_id is 'the campaign the leads will be associated with' and is required only for approve, and confirmation_token is the phase-2 commit switch — clarifying how parameters interact rather than just restating them.

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) plus the resource (discovered leads), which cleanly separates it from find_leads and the campaign-management siblings. An agent knows exactly what operation this is 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?

Explains the two-phase call sequence (phase 1 returns token + preview, phase 2 commits with confirmation_token) and the conditional requirement that campaign_id applies only to action='approve'. It does not explicitly say 'use this after find_leads' or name any alternative tool for reversing an approval, so it stops short of full when/when-not guidance.

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

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

Annotations already flag a destructive, non-idempotent, open-world mutation. The description adds critical behavior beyond annotations: it previews exact searches, enabled state, and LinkedIn resolution choice, requires explicit approval, does not activate draft or paused agents, and notes X account connection and Hacker News provider requirements.

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

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

Front-loads the core purpose, then walks through prerequisites, conditional behavior, approval flow, exclusions, and source-specific requirements in tightly ordered sentences. No sentence is filler; each either routes the agent or prevents a misstep.

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

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

Given a complex, mutating, multi-step configuration tool with full schema coverage and an existing outputless preview/approval pattern, the description covers prerequisites, alternatives, approval gating, and source-specific constraints. Nothing material is missing for correct invocation.

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

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

Schema description coverage is 100%, so parameter documentation is already handled by the schema. The description reinforces '1-10 precise searches' and 'LinkedIn resolution choice', but these largely repeat the schema descriptions rather than adding new syntax or usage 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 and resource: configure X or Hacker News searches for one owned agent and set source listening. It clearly distinguishes itself from get_agent_sources and set_agent_source_listening by naming both siblings and the conditions for using 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 explicit sequencing ('First call get_agent_sources'), branch-specific behavior for no existing source versus an existing source, and a direct alternative for searches that need no change: set_agent_source_listening. It also states when not to use it and what approval is required.

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 flag destructive/non-idempotent, and the description adds substantive behavior beyond them: an approval prerequisite, optimistic-concurrency version requirement, a restriction on which steps retry may target, the no-replay rule for completed effects, and the caveat that pause cannot stop an in-flight provider call. No annotation contradiction.

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

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

Four tight sentences, front-loaded with the operation set and followed by the constraints that actually govern invocation. Dense but every clause carries an operational constraint; 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 and five parameters, so the description carries weight; it covers approval, versioning, retry eligibility and pause semantics. It omits what a stale version returns and the mechanics of the confirmation_token handshake beyond 'omit on first call'.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by explaining that expected_version must be the task's current version and that step_id applies only to retry (failed idempotent local-read step), plus the first-call token flow.

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

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

States specific verbs (pause, resume, cancel, retry) against a specific resource (a durable Operator task), and 'durable' plus 'operator' clearly separates it from pause_agent/pause_campaign and from the read-only get_operator_task/list_operator_tasks 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 governing precondition ('after exact approval') and operation-specific conditions for retry, plus the pause limitation. It does not explicitly route the agent to a sibling (e.g., read task state via get_operator_task first), so it falls short of 5.

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

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

Annotations only provide the flag set (destructive, non-idempotent, non-open-world); the description adds substantial behavior they do not encode, notably the mandatory two-phase preview/confirm protocol, ICP merge/override semantics, defaults seeding when signals are omitted, and the LinkedIn-URL-to-slug conversion with a user-verification step. It does not explain why the tool is flagged destructive, but the additive behavioral disclosure is unusually rich.

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 correctly: purpose and the two-phase rule come first, then ICP merge semantics, then signal semantics. Every sentence carries information, but it runs to roughly eight dense sentences in a single block with no visual grouping, making key rules (like the empty-array clearing convention) easy to skim past.

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 nine-parameter tool with nested signal objects and no output schema, the description covers the genuinely hard parts: the merge/inheritance model, the confirmation flow, and signal construction including the keyword_tracking example. It stops short of explaining what the phase-1 preview returns or how confirmation_token/max_signals are meant to be used in practice.

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 a 3 is the baseline; the description nonetheless adds real meaning, such as icp_filters overriding only supplied keys while keeping job_titles/mandatory_keywords/excluded_companies/company_sizes, excluded_companies accepting employer names or LinkedIn URLs and storing slug names, and the required field set for each signal. max_signals, type, app_name, icp_description and linkedin_account_ids get no description-level elaboration.

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

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

States a specific verb, resource and scope: 'Create a new draft agent under the request's scoped app.' The 'draft' qualifier and the two-phase flow distinguish it from siblings like draft_icp_edit, enable_agent, and update_icp without the agent needing to open another schema.

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

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

Explicit operational rules cover the whole decision space: call twice (preview then confirm), omit icp_filters on a vague request to inherit the saved ICP, pass only the keys the user asked to change, pass an empty array to clear a list, omit signals to seed from ICP, use [] for no signals. It also instructs the agent to ask for missing details rather than fabricate.

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

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

With destructiveHint=true and readOnlyHint=false already declared, the description adds real behavioral context: a two-phase approval flow (implied by confirmation_token), the default 4-step workflow when steps are omitted, and default-list creation side effects. It doesn't spell out irreversibility or auth requirements, so not a full 5.

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

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

The core verb is front-loaded and each sentence carries operational content, but the description is long and re-states at least one schema detail (the {FirstName}/{LastName}/{Company} variables). Mostly earned, slightly 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 7-parameter, no-output-schema mutation tool, it covers the approval workflow, list-resolution defaults, workflow defaults, and the negative constraints. It leaves the confirm-preview mechanics and confirmation_token acquisition flow implicit, which is the only material gap.

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

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

Schema coverage is 100% so baseline is 3, but the description adds resolution logic the schema lacks: with agent_id and no list_id use the agent's destination list, otherwise the product default list is assigned/created, and an explicit different list retargets a draft agent only after approval. The personalization-variable constraint is repeated from the schema, so not a 5.

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

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

States a specific verb and resource ('Create a draft campaign in the selected product') and immediately scopes it as a draft with an approval gate. An agent can distinguish this from enable_campaign, update_campaign_workflow, or update_campaign_settings because the description says it creates rather than mutates or activates.

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 and when-not-to-use: 'First show the exact campaign... for approval' and 'Never activate, discover, enroll, or send.' It also routes alternative cases (agent_id with/without list_id, custom vs default workflow_steps), leaving little to inference.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, idempotentHint=false, and the description adds real context: the list starts empty and is populated later via approve_leads with action='approve' plus the new list_id. That downstream workflow detail is genuine value beyond the structured fields, though it omits whether the call returns the new list_id or what happens on duplicate names.

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

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

Three sentences, each with a distinct job: purpose, usage trigger, and follow-up behavior. No filler or restatement of the 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 two-parameter creation tool with no output schema, the description covers purpose, trigger, and post-creation workflow. The only gap is not stating that the new list_id is returned, which the agent would need to chain into the approve_leads step it recommends.

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

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

Schema description coverage is 100%, so both parameters (name with 1-100 char bound, optional description) are already documented. The description mentions naming a bucket but adds no format, uniqueness, or validation detail 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 and resource ('Create a new lead list') plus scope ('scoped to the request's app'), which cleanly separates it from siblings like list_lists, get_list, 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?

'Use this when the user wants to organise leads into a named bucket' gives a clear triggering condition with concrete examples ('Q4 Targets', 'Hot Founders'). It does not name a when-not condition or contrast against sibling creation paths, so it stops short of the top tier.

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 (readOnlyHint=false, destructiveHint=true, openWorldHint=false, idempotentHint=false). The description adds real context beyond them: the request_key is single-use and a changed intent under the same key fails, and the write requires a confirmed intent. The one-time-key semantics sit in mild tension with idempotentHint=false (no key means repeat calls do create duplicates), but this is a request-level dedup guard, not a flat contradiction.

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

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

Two sentences, both front-loaded: the action and its precondition come first, the key constraint second. Nothing is padded or repeated from the schema.

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

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

For a 6-parameter destructive write with a two-step confirmation flow, the description covers the confirmation gate, the key constraint, and the target scope. It omits the mechanics of the confirmation round-trip (though confirmation_token is documented in the schema) and any guidance relative to create_reminder; with no output schema, return behavior is reasonably 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 coverage is 100% so the baseline is 3, but the description adds meaning above the schema: the key semantics ("One request_key can be applied only once; a changed intent with the same key fails") go beyond the schema's neutral "Stable unique request identity." It also ties the operation to the exact lead, body, and due date, grounding three of the six parameters in intent.

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

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

States a concrete verb and resource ("Create a scoped note or reminder") and adds the scoping constraint, so an agent knows this writes a note attached to a lead. However, it never distinguishes itself from the sibling create_reminder, and by claiming to create both notes and reminders it actively blurs the boundary with that 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 a clear invocation precondition: the call must follow "an explicit confirmation of the exact lead, body, and due date," which tells the agent when it is safe to proceed. It stops short of naming alternatives (create_reminder, list_reminders) or exclusions, so routing between the note/reminder siblings is left to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false. The description adds genuinely new behavior: a request_key is single-use and a replayed key with changed intent fails, which is important operational context not derivable from the annotations. It does not clarify the confirmation_token round-trip beyond what the schema notes.

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 earning their place, with the creation action and its confirmation precondition front-loaded and the idempotency constraint second.

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 omits what happens on a first call carrying no confirmation_token (whether it errors, or returns a token for the second call) and what the created reminder looks like. For a destructive, confirmation-gated create, that loop is the main thing left unexplained.

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 goes beyond the schema by explaining the request_key's one-shot semantics and that the same key with changed intent errors, which is the key parameter behavior an agent needs to avoid failed calls.

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

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

The description uses a specific verb and resource ('Create a scoped note or reminder') and scopes it to a lead via the confirmation clause. It does not, however, distinguish itself from the sibling create_note, which an agent must choose between when the intent is a note rather than a time-based reminder.

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 a precondition ('after an explicit confirmation of the exact lead, body, and due date') which implies the correct workflow, but never says when to prefer this over create_note or how to handle the pre-confirmation step. Usage is implied rather than directed.

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

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

Annotations already 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 only give the safety profile (readOnlyHint=false, destructiveHint=false, non-idempotent). The description adds real behavioral context beyond them: what input data is read (industry, role, headline, hook), that no message is sent, and the guard conditions on reply_state. It does not cover rate limits or output variability for an openWorld, non-idempotent generation, 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?

Four tightly packed sentences, front-loaded with purpose then sequencing then preconditions; every clause carries a distinct operational constraint (no send, approval gate, get_lead check, refusal set) 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 usefully states the return is a single message body, and it covers precondition checks and refusal cases. It is nearly complete, though it omits what the draft does with `tone` and whether the generated body persists anywhere for later retrieval.

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

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

Schema description coverage is 100% and the enum on `tone` is self-documenting, so the baseline is 3. The description's mention of an "optional reference hook" largely restates the schema's `reference` description and adds no format or syntactic detail, and it never explains how `tone` interacts with the generated draft.

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 ("Generate a personalised draft for one lead") and the return ("a single message body"). It immediately disambiguates from sending siblings with "Does NOT send", so an agent can tell it apart from send_message/send_conversation_reply 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?

Explicit sequencing ("After the user reviews and approves, call send_message"), an explicit prerequisite ("ALWAYS call get_lead first"), and explicit when-not conditions (refuse for opted-out / replied / rejected leads). Nothing about when to use vs. avoid is left to inference.

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

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

Annotations already declare destructive=true, non-idempotent, and openWorld, so the safety profile is covered. The description adds a genuinely non-structured trait: the two-phase commit where phase 1 is a non-committing preview returning a token and phase 2 commits, which materially changes how the agent should call it. It does not, however, explain what the 'destructive' effect actually destroys or retry behavior, keeping it at 4.

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

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

Two sentences, zero waste: the core action and scope are front-loaded, and the phase mechanics follow immediately. Every clause earns its place.

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

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

With no output schema, the description usefully discloses what phase 1 returns (confirmation token + preview) and what phase 2 does, and annotations carry the safety profile. It leaves the post-enable effects and failure handling implicit, so it is strong but not exhaustive.

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 relational meaning the per-field schema does not: it clarifies that confirmation_token is omitted on phase 1 and required on phase 2 to commit, tying the parameters into the two-phase flow rather than describing each in isolation.

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), the resource (agent), the eligible states (paused or draft), and the resulting effect (begins discovering leads on its schedule). This is clearly distinguishable from pause_agent (inverse) and enable_campaign (different resource) without opening any schema.

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

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

Explicitly scopes applicability to 'a paused or draft agent' and lays out the two-phase call sequence, which tells the agent exactly when and how to invoke it. It stops short of naming alternative tools or stating when-not-to-use, so it lands just below the top band.

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 (destructive/idempotent/openWorld) by disclosing the two-phase commit (token + preview, then confirm), that the engine begins scheduling actions, and that pre-condition failures surface as structured errors. For a destructive mutation this is exactly the operational context an agent needs.

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

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

Purpose is front-loaded in the first sentence and each subsequent sentence earns its place (behavior, two-phase flow, validation). Slightly dense at four sentences, 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 mutation with no output schema, the description covers the critical gaps: confirmation flow, what activation triggers, and error behavior. An agent has everything needed to invoke both phases 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 semantics: it explains the round-trip role of confirmation_token (returned on phase 1, supplied on phase 2) beyond the terse 'omit on phase-1' schema note. It does not clarify campaign_id vs campaign_name coupling, keeping it out of 5 territory.

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 ('Enable (resume) a paused or draft campaign') and narrows the applicable state (paused or draft). The scope distinguishes it well from create_campaign_draft, but it never names the inverse sibling pause_campaign, so differentiation is implicit rather than explicit.

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

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

Gives clear context for when to use it: resuming a paused or draft campaign, in a two-phase confirm flow. It stops short of naming alternatives or stating when-not-to-use, so it lands at clear-context-without-exclusions.

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

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

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 declare destructiveHint=true and idempotentHint=false, but the description adds the crucial two-phase confirmation semantics that the annotations cannot convey — that the first call is non-committing and only the second call with confirmation_token writes. It does not explicitly describe side effects on the target list (e.g. dedupe, overwrite), 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 purpose, then the phase flow, then parameter conditions, then post-commit guidance. Every sentence carries actionable content 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 complex stateful, destructive, two-phase import with no output schema, the description covers the flow, commit semantics, parameter conditions, and follow-up. It stops short of describing the phase-1 preview contents and error/failure behavior, but it is otherwise self-sufficient.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds conditional semantics the schema does not: provider_ids omitted means import all, list_id targets an existing list while list_name creates a new one, and confirmation_token is phase-2 only. This meaningfully enriches the parameters beyond the schema text.

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

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

States a specific verb (import) plus resource (lead rows) and origin (a prior search_external_leads session) into a lead list. This clearly distinguishes it from siblings like search_external_leads (which produces the session), create_list, and find_leads.

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 two-phase flow (phase-1 preview + token, phase-2 commit with confirmation_token) is spelled out, as is when to use list_id vs list_name and what omitting provider_ids does. It even gives forward guidance to reuse the returned list_id for campaign creation. The only gap is an explicit 'don't use this if...' 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 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?

The description adds substantial behavioral context beyond the annotations: it explains the two-phase confirmation workflow, that the first call returns a token and preview, that the user reviews an inline card, and that existing leads remain after pausing. This meaningfully clarifies the mutation flow and impact, which the destructive and non-idempotent hints alone do not convey.

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

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

The description is front-loaded with the core purpose, then adds the key side effect, the two-phase flow, and the parameter guidance in a compact sequence. Every sentence adds useful information without 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 multi-step mutation tool with no output schema, the description covers the essential call flow, return behavior for phase one, and required parameter usage. It gives enough context for an agent to invoke the tool correctly across both phases.

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 why agent_name and app_name should always be included for a human-readable preview, and by tying confirmation_token to the second phase, which is more than the schema descriptions provide.

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 agent. It also clarifies the effect by saying it stops discovering new leads while existing leads remain, which distinguishes it from enable_agent and pause_campaign implicitly. However, it does not explicitly name or contrast a sibling tool.

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

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

The description gives some procedural guidance for using the tool, such as including agent_name and app_name and using the two-phase confirmation flow. But it does not state when to choose pause_agent over alternative tools like enable_agent or pause_campaign, nor does it mention exclusions or prerequisites.

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 non-idempotent, and the description goes well beyond them by disclosing the two-phase confirmation protocol, the inline-card review step, the confirmation token requirement on phase 2, and the effect ('the campaign engine stops scheduling actions'). This is exactly the kind of behavioral context annotations cannot carry.

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

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

Front-loaded with the action, then the effect, then the two-phase mechanics, then the required-field reminder. Four tight sentences with no filler; every clause informs correct invocation.

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

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

No output schema exists, and the description compensates by stating what phase 1 returns (confirmation token + preview) and how phase 2 commits. Combined with the annotations and the fully documented schema, 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% and the schema already labels app_name/campaign_name as preview inputs, so the baseline is 3. The description adds real meaning: it explains why those fields matter (human-readable preview) and clarifies the phase-1/phase-2 role of confirmation_token (omit on phase 1, supply to commit).

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 ('Pause an active campaign'), immediately distinct from siblings like enable_campaign, pause_agent, and update_campaign_settings. The first sentence alone tells an agent exactly what operation this is.

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

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

Gives clear operational context: it applies to an active campaign, requires a two-phase confirmation flow, and tells the agent to always pass campaign_name + app_name so the preview is readable. It does not name an alternative tool or state when-not to use it, 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 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 destructive=true, idempotent=false, and openWorld=false, so the safety profile is largely covered. The description adds genuinely new behavior: the target must be unarchived, an approval gate applies, and expected_name acts as an optimistic-concurrency guard that rejects stale writes. It does not describe failure modes or the two-step token flow in detail.

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

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

Two tight sentences, no filler. The destructive action and its scope are front-loaded, with the concurrency requirement following immediately.

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

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

For a destructive single-resource mutation with no output schema, the description covers the precondition (unarchived), the approval gate, the stale-write guard, and the full-replacement semantics of description. Combined with annotations carrying the safety profile, an agent has what it needs 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. The description still adds meaning: expected_name is framed as a stale-change guard rather than just a current name, and 'include the full new description' clarifies that description replaces rather than appends. The confirmation_token flow is left to 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 (rename) and resource (list) with a scope qualifier (one unarchived list in the selected product), which is enough for an agent to distinguish it from create_list, get_list, or list_lists. It does not explicitly name a sibling as an alternative, so it falls short of the top tier.

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

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

Gives a clear precondition – the rename must follow explicit approval – and explains the concurrency protocol (supply the current name to reject stale changes). It stops short of naming when-not-to-use cases or alternatives, so it is clear context without explicit exclusions.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds real context beyond them: the two-step approval precondition, the fact that existing keys are overwritten, and the prompt-injection guard that value is data 'not a system instruction'. It does not spell out the confirmation_token handshake, which is only in the schema.

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

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

Four short sentences, each carrying distinct information (action+scope+approval, injection guard, upsert semantics, forbidden inputs), with the core action front-loaded. No filler, though the fragment style is slightly clipped.

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

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

For a 4-param mutation tool with no output schema and full annotation coverage, the description covers approval precondition, overwrite semantics, and input restrictions. Only the multi-turn confirmation_token workflow and the returned result are 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 the baseline is 3. The description adds two non-obvious constraints on the value parameter (bounded JSON, no credentials/tokens) but leaves `reason` and the confirmation_token flow to 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 (Save) and resource (a selected-product Operator preference), and the phrase 'one ... preference' plus 'Existing keys update' tells the agent the scope and the upsert behavior. It is not confused with list_preferences, though it never names that sibling as the read 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?

'after explicit approval' establishes a precondition and 'No provider credentials or tokens are accepted' narrows the valid input domain, so usage context is implied. However it never states when to save vs. skip, nor points to list_preferences for retrieval, leaving the alternative unspoken.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true and idempotentHint=false, and the description usefully explains why it isn't a pure read: it returns a server-owned session_id and up to 10 previews. It discloses the import handoff workflow, though it could say more about rate limits or freshness of LinkedIn 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 front-loaded sentences with no waste: purpose first, then selection guidance, then the return-value plus next-step pairing. Every sentence earns its place.

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

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

Despite no output schema, the description covers the return shape (session_id plus up to 10 previews) and the downstream import step. Combined with full schema coverage and annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents query, role, and limit. The description only loosely echoes the searchable facets (words, roles, companies, market terms) without adding syntax or format details beyond what the schema provides.

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

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

States a specific verb (Search) plus resource (LinkedIn people leads) and scopes it to the request user's connected account. It explicitly contrasts with searching existing saved leads, so an agent can distinguish it from siblings like find_leads and list_list_contacts.

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 conditions (user describes leads by words, roles, companies, or market terms) and a when-not ('rather than asking to search existing saved leads'). It also names the follow-up tool import_search_leads_to_list and the condition that triggers 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 destructive=true and idempotent=false, but the description goes further in domain-specific terms: a timeout produces an uncertain state that must not be retried automatically, and file support is limited to LinkedIn (email files unavailable). That is exactly the kind of behavior an agent cannot infer from the structured hints.

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

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

Four sentences, front-loaded with the action, then the required inputs, then the two caveats that matter most (non-retryable timeout, file-type limits). 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 destructive, non-idempotent send with a nested object parameter and no output schema, the description covers approval gating, input provenance, timeout risk and file limits. The one omission is the two-step confirmation flow implied by confirmation_token ('omit on first call') and reply_as_confirmed, which the schema hints at but the description never explains.

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 cross-tool meaning by tying `prepared` to the exact output of prepare_conversation_reply and requiring `request_key` to be stable. It adds context the schema alone does not convey, though it says nothing about reply_as_confirmed.

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 ('Send one exact prepared reply to the latest inbound message') with the gating condition ('after explicit human approval') attached. It clearly distinguishes itself from the sibling prepare_conversation_reply by framing itself as the send step that consumes that tool's output.

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

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

Gives an explicit precondition (human approval) and an explicit input requirement (the complete prepare_conversation_reply result plus request_key). It doesn't spell out a when-not rule (e.g. 'never call this to draft or edit'), but the routing to prepare_conversation_reply is unmistakable.

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, idempotentHint=false and openWorldHint=true, but the description adds the crucial non-obvious behavior: a first call only previews the approval and a second user-approved call commits, and saved searches, budgets, LinkedIn resolution and other sources stay unchanged. It also notes a draft/paused agent collects nothing until activated. It stops short of stating failure modes or token expiry, so it is strong rather than 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?

Five tight sentences, front-loaded with the scope limit, then preconditions, then the approval mechanics, then the side-effect boundary. No sentence restates the tool name or wastes tokens.

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 carry the interaction model, and it does: precondition read, alternative tool, two-step approval, and the exact set of things not affected. Nothing an agent needs to invoke this mutation safely is missing.

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

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

Schema description coverage is already 83%, so the baseline is 3. The description adds real meaning on top: it explains the confirmation_token's two-call commit semantics and implies expected_updated_at is sourced from get_agent_sources, both of which are not spelled out in the schema. It says nothing about the app_id multi-product requirement.

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 (pause/resume), a precise resource (an existing X or Hacker News source on an agent), and a hard scope limit ('only'), which immediately separates it from configure_agent_source and get_agent_sources. An agent can pick this tool without opening any schema.

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

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

Gives an explicit precondition chain: read get_agent_sources first, and if 'configured is false or searches are empty' use configure_agent_source instead. It also names the alternative by name and states the two-call approval path, so when-to-use and when-not-to-use are both unambiguous.

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

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

Annotations only declare the safety profile (destructive, non-idempotent). The description adds rich behavior: the first call returns an approval preview, approved execution is atomic, omitted settings are unchanged, null clears a platform, and it never activates/enrolls/sends. This is significantly beyond what annotations provide.

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

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

Front-loaded with the action, then logistics. Every sentence carries distinct, necessary information (scope, prerequisite, preview/approval flow, mutation semantics) 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?

There is no output schema, but the description compensates by explaining the first-call preview return and the atomic save on approval, and by covering mutation semantics and the confirmation_token flow. Minor gaps remain around the exact preview contents, but this is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine semantic value beyond the schema by clarifying the omit-vs-null distinction ('Omitted settings remain unchanged'; 'Explicit null sender clears one platform') and the expected_updated_at provenance.

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 manual review, send window, or sender assignments') and precisely scopes what it does NOT do ('never activates, enrolls, or sends'), which cleanly separates it from enable_campaign, pause_campaign, and update_campaign_workflow.

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

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

Gives clear workflow context: read get_campaign first and copy its updated_at, and explains the two-step preview-then-approve flow. It does not explicitly name an alternative sibling to prefer or avoid (e.g. update_campaign_workflow), leaving some routing to inference.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds the crucial two-phase confirmation flow (first call returns a confirmation card, execution requires confirmation_token), the persistence semantics ('applies the exact stored workflow_messages through the campaign service'), and a clear non-behavior boundary ('never launches or sends'). This goes well beyond what annotations convey.

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

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

Front-loads the core purpose and the preferred selector pattern, then moves into the confirmation mechanics. It's a long description but most sentences carry distinct information; a touch of tightening (e.g., repeating the campaign_name/app_name purpose) would help.

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

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

For a destructive, two-phase mutation on nested workflow_messages with no output schema, the description covers what's modified, what the first call returns, what the second call does, what is never done (no launch/send), and how to select items. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely useful semantic distinctions: message_order vs step_order fallback behavior, allowed personalization variables, the exactly-one-selector constraint, and the preview role of campaign_name/app_name. That said, several of these are also echoed in schema descriptions, keeping it just above baseline.

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

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

States a specific verb and resource: updating message content on existing steps in a draft or paused campaign. It clearly distinguishes itself from siblings like update_campaign_settings (settings, not workflow messages) and create_campaign_draft. The scope constraint ('existing steps', 'draft or paused') further narrows it.

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

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

Gives explicit selection guidance: prefer one-based message_order that skips invite/follow steps, use step_order only when exact raw order is known, provide exactly one selector plus a template per item. This is precisely the kind of when-to-use-A-vs-B guidance that prevents invocation errors.

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

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

Annotations already declare this is destructive, non-idempotent, and not read-only, and the description adds the crucial two-phase commit protocol: phase 1 returns a confirmation token plus preview, phase 2 with confirmation_token performs the mutation. It discloses how the destructive action is gated, which the annotations alone do not convey.

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

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

Front-loads the purpose, then the two-phase mechanics, then the hard prerequisite, then the parameter tip. Every sentence is load-bearing; nothing 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?

For a destructive, two-phase, six-parameter tool with nested objects and no output schema, the description covers the full lifecycle: the staging requirement, the phase-1 preview artifact, and the phase-2 commit. An agent has everything needed to sequence the calls 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 schema already documents all six parameters and the baseline is 3. The description adds real usage guidance beyond the schema by telling the agent to pre-populate agent_name so the confirm preview is human-readable, and by tying confirmation_token to phase 2.

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 scopes the operation to a single agent. It differentiates itself from the sibling draft_icp_edit by framing that tool as the staging step and this one as the committing step.

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

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

Explicitly mandates the prerequisite ('ALWAYS call draft_icp_edit first... never call update_icp directly without staging a diff') and names the exact condition for using this tool (after the user confirms the inline diff). This leaves no ambiguity about when to invoke it versus its sibling.

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