LinkedCamp

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so safety is covered structurally; the description adds real value by naming fields that are deliberately non-writable (billing, password, email) and by bounding the blast radius to the caller's own profile. It stops short of describing partial-update semantics (zero required params means unspecified fields are left untouched) or what the tool returns, which keeps it below 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?

Front-loaded with the action and the writable fields, followed by scope limits and alternatives — the right order for an agent scanning for eligibility. Slightly redundant at the tail: billing is declared non-writable in sentence two and then again as outside the server entirely, which costs a few words without adding information.

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

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

For a mutation tool with four optional parameters, a nested settings object and no output schema, the description covers scope, exclusions and non-writable fields adequately, and annotations carry the safety profile. The remaining gap is return behavior on success/partial failure, which matters given there is no output schema to fall back on.

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 nested settings toggles are already fully documented field-by-field and the baseline would be 3. The description still adds meaning beyond the schema by grouping the parameters into profile fields vs. inbox/reporting/notification toggles and by stating which account attributes are intentionally excluded from the writable surface.

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 (update) and a precisely scoped resource (your own profile and notification preferences), then enumerates the writable field groups: name, language, inbox-manager/reporting/notification toggles. It also names the sibling tools it is not (linkedin_account_update, email_account_update, campaign_update), so an agent can disambiguate 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?

Explicit about when to use it (own user profile only) and when not to: LinkedIn account settings, mailbox settings, campaign settings, billing, team management and tenant configuration are all declared out of scope, with the correct alternative tool named for each. The exclusion of password and email as non-writable is also stated up front.

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 safety profile, and the description adds genuinely non-obvious behavior: the upstream field cannot return PENDING or FAILED rows at all, and failures are only visible via lead_get. It also warns that the status parameter filters the lead's pipeline status rather than the activity's, preventing a very plausible 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?

Three tight sentences: what it returns, what it cannot return, and the disambiguation warning. The scope constraint is front-loaded and no sentence is filler.

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

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

With no output schema, the description supplies the shape ('one row per lead per step') and the completeness limitation (no pending/failed rows), which is the critical information. It stops short of describing pagination/ordering or the default range window, but nothing essential for calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents page, range and its date aliases, keyword, and the status enum. The description's status clarification is valuable but duplicates what the schema field description already states, and it says nothing about range/pagination semantics beyond what is structured.

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 resource (completed activities) and even the row grain ('one row per lead per step'), with an explicit scope constraint that only COMPLETED rows are returned. It does not name sibling listing tools like campaign_activity_summary or activity_skip, so differentiation is partially 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?

Gives an explicit routing rule — use lead_get to inspect a failure and its failedReason — which is exactly the kind of alternative-selection guidance agents need. It lacks a 'when not to use' condition for aggregate/analytics siblings, so it is clear but not exhaustive.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description adds real context by narrowing the blast radius ('that status is the only thing it writes') and warning that it does not schedule the next step, preventing a false success claim. The remaining gap is silence on whether a skip can be undone or what happens when the activity is not pending, which matters given destructiveHint=true and idempotentHint=false.

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 verb and status written, then the caveat, the id-type warning, and the alternative. No sentence is redundant and each carries a distinct constraint.

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 one parameter, full schema coverage, and annotations covering the safety profile, the description supplies nearly everything needed: effect, non-effect, follow-up verification, and an alternative tool. Only the failure mode (non-pending or unknown activityId) and reversibility are unaddressed.

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

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

Schema coverage is 100% and the single parameter already documents its source (`activity_list`), so the baseline is 3. The description adds disambiguation beyond the schema by stressing it acts on an activity id rather than a lead id, which is the most likely caller error for this 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 and resource ('Mark one pending action SKIPPED') plus the scope constraint ('one pending action', 'activity id, not a lead id'). It explicitly distinguishes itself from `lead_update` and points to `lead_flow_state` for follow-up, so an agent can separate it from adjacent flow/lead tools 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 the triggering condition ('unblock a lead stuck on a step that will never succeed'), the alternative for a different intent ('to stop a lead entirely use `lead_update` with `paused` or `isExcluded`'), and the post-call action ('re-read with `lead_flow_state`'). When-to-use, when-to-use-something-else, and what-to-do-next are all present.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the operational consequences an agent can't infer: campaigns and conversations silently lose automated replies, prospects mid-conversation go unanswered, and knowledge attachments plus training are destroyed. It also discloses the required 'Agents' plan permission, which is not in the schema or 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?

Roughly five sentences, each doing distinct work: what it does, what breaks, irreversibility, the confirmation protocol, the non-destructive alternatives, the permission gate. The consequence is front-loaded before the guidance.

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

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

For a one-parameter destructive mutation with no output schema, everything an agent needs is present: blast radius, irreversibility, a pre-flight confirmation workflow, alternatives, and the authorization requirement. Nothing material is missing.

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

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

Schema coverage is 100% and the single parameter already carries a description ('AI agent id, from `agent_list`'), so the baseline is 3. The description reinforces the `agent_list` provenance but adds no format or validation detail beyond the schema.

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

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

States a specific verb and resource ('Delete an agent') and immediately distinguishes it from non-destructive siblings by naming the alternative paths (agent_upsert with isActive:false, conversation_update with assistant:false). An agent knows exactly what this does and what it costs versus those siblings.

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

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

Gives explicit preconditions (read `agent_list`, show the user, get an explicit yes) and explicit when-not-to-use guidance that routes to two specific sibling tools for the softer cases. This is the strongest possible form of usage guidance.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, non-idempotent), so the description's job is additive context — and it delivers: the copy is configuration-only and the knowledge will not function until agent_train runs, plus a plan-level "Agents" permission is required and cross-account placement is owner-restricted. It does not say whether the duplicate is created active/paused or how it is named, which are the main remaining behavioral gaps.

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: purpose, then the critical post-copy caveat, then the permission/ownership constraints. Nothing is wasted and the most decision-relevant warning (needs agent_train) comes early.

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 only two parameters, full schema coverage, and no output schema, the description covers what an agent needs to invoke it correctly and not be surprised afterwards. It is missing only the return value (presumably the new agent id) and whether the copy inherits settings like status, both of which matter for a duplication 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% and the userId schema text is far more precise than the description (naming subaccount_list, forbidding guessed ids, requiring a user confirmation). The description's "optionally into a sub-account" and "account owner" only restate that at a higher level, and it says "account owner" where the schema says "agency owner" — a loose summary rather than added meaning. 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?

"Copy an agent, optionally into a sub-account" states a specific verb (copy/duplicate) and resource (agent) with an explicit scope option. An agent can immediately tell this apart from agent_upsert, agent_get, or agent_delete 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 clear context: it names agent_train as the mandatory follow-up step before the knowledge works, and states the owner-only precondition for the cross-account variant. It stops short of naming an explicit alternative tool or a "do not use this when..." exclusion, but the post-copy routing guidance is genuinely actionable.

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 genuinely new context by stating the "Agents" permission requirement and by scoping the result to configuration only (no conversational output). It does not discuss response size or shape, which is the remaining gap.

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

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

Three tight sentences: payload contents first, usage instruction second, sibling routing third, permission note last. Nothing is redundant and the most decision-relevant information is front-loaded.

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

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

For a single-parameter read tool with full annotations and no output schema, the description covers what is returned, when to call it, what it does not return, and the auth requirement. An agent has everything needed to invoke it correctly.

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

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

Only one parameter and schema coverage is 100% — the schema already documents agentId and its provenance from `agent_list`. The description adds no extra semantics about the id format, 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 and resource ("One agent's full configuration") and enumerates exactly what fields are returned: personality, intent, instructions, FAQs, follow-ups, booking action. It then explicitly separates itself from agent_logs, agent_query and agent_stats, so an agent can pick correctly 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 affirmative condition ("Read this out to the user when they are choosing an existing agent") and names three sibling alternatives with the question each answers. When-to-use and when-to-use-something-else are both explicit.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds material beyond them: the plan-level 'Agents' permission requirement and the consequence that an attached agent 'answers real prospects by itself'. It does not cover return size, pagination, or default ordering for a list endpoint, which is the remaining behavioural gap.

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

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

Front-loaded with the resource, then the when-to-use routing, then the conceptual disambiguation. The agent/persona/knowledge-base sentence is useful for disambiguation but is the longest piece and could be trimmed; the rest earns its space.

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

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

With no output schema, the description should imply what comes back; it hints at the list being inspectable via agent_get but never says the result contains agent IDs and types the caller can feed forward. Permissions, safety, and routing are all covered, so only the return-shape detail 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 each of the three parameters is documented in the schema, so the description adds little on this axis. It does gloss the semantics of two enum values (CHAT replies to prospects, CONTENT drafts posts) and never mentions withStats, so it neither clarifies nor misleads beyond the schema baseline.

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

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

The description identifies the resource and its scope ('AI agents configured for this account') and enumerates the sub-types (CHAT, CONTENT, others), so the agent knows exactly what set it is dealing with. It also separates the concept from neighbouring resources (personas, knowledge bases). The verb is only carried by the name/title rather than the description text, keeping it 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?

Explicit entry point is given ('Start here when the user asks about automated replies') along with the follow-up flow ('show them agent_get so they can judge the fit before anything is attached'). It also names the mutating sibling campaign_update and states an exclusion/caution ('never attach one unasked'), which is exactly the when-not guidance most definitions lack.

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 the safety profile is covered. The description adds a real behavioral constraint the annotations lack: it requires the "Agents" permission on the plan. It stops short of describing pagination or log volume, which is the only remaining gap.

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

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

Front-loaded with the core purpose, then routing alternatives, then the permission note. The middle sentence ('What it actually said in real conversations') slightly restates the opening clause rather than adding new information, but the description stays short and readable.

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

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

For a read-only log tool with no output schema, the description adequately conveys what is returned (the ask/answer trace) and the routing alternatives. The permission requirement is a useful addition. Pagination behavior for potentially large logs is the one notable omission.

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 two parameters, so the schema already documents both agentId and page. The description adds no parameter detail beyond what the schema provides, which is the expected baseline 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 resource and scope: the trace of what an agent was asked and what it answered. It explicitly names the sibling tools it is not (agent_query for hypotheticals, conversation_get for the prospect-facing thread), so an agent can disambiguate 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 trigger — read this when an agent's replies look wrong — and names two alternatives with the condition that selects each ('to try a hypothetical instead... use agent_query'; 'to read the prospect-facing thread use conversation_get'). Nothing about tool selection is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds meaningfully beyond them: the no-delivery guarantee ('nothing reaches the prospect') and the plan-level 'Agents' permission requirement — both are behavioral facts not encoded in annotations. It doesn't describe what the returned answer looks like or latency/token behavior, 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?

Front-loaded with the core action, then return behavior, disambiguation, and permissions in that order — every sentence carries distinct information. Slightly dense with three sibling references in one paragraph, which costs a point on structure but not 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 states that the answer is returned and that nothing is sent — exactly what an agent needs to interpret the result. Params are fully schema-described, permissions are named, and alternatives are routed.

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 all three required params are documented in the schema (`query`, `agentId` with a pointer to `agent_list`, `conversationId` as context). The description adds no param-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource — run a question through an agent against a real conversation — and immediately frames the purpose (preview how it would answer). It explicitly distinguishes itself from `agent_logs` (past output) and `message_send` (actual replying), so the agent can place it among siblings without opening schemas.

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

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

Gives the when (vetting an agent before it goes active), the when-not (not a way to reply; replying by hand is `message_send`, and only on an explicit yes), and the alternative for historical output (`agent_logs`). Routing is explicit rather than implied.

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

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

Annotations already cover read-only, idempotent, non-destructive semantics, so the description correctly spends its words elsewhere — adding the plan-level 'Agents' permission requirement, which is a real call-time prerequisite an agent cannot infer from annotations. It stops short of noting time windowing or freshness of the totals.

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

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

Three short sentences, front-loaded with what is returned, then the scope constraint, then the alternative and the prerequisite. No redundant restatement of the title 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 does the essential work of enumerating the returned metrics and clarifying aggregation scope, and adds the permission requirement. It does not state the reporting period for the totals, which is the one thing an agent might still need to assume.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a no-param tool applies. The description instead clarifies the implicit scoping decision (all agents, no filter) that an agent might otherwise expect to control.

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?

Names the exact metrics returned (conversations handled, replies sent, appointments booked) and the aggregation scope (all agents). A reader knows precisely what this tool produces and how it differs from agent_logs without opening any schema.

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

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

Explicitly routes the agent: use this for aggregate totals, and read `agent_logs` for a single agent's quality. It also pre-empts a likely misuse by stating 'there is no per-agent breakdown here.'

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's real contribution is the scope statement: it only re-indexes existing knowledge and does not alter instructions or teach unattached material. It also discloses the "Agents" permission requirement, which annotations cannot express. It stops short of saying whether the rebuild is synchronous, how long it takes, or what the call returns — a meaningful gap for a non-idempotent mutation.

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

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

Three sentences, each load-bearing: what it does, when it must run, and what it does not do. The trigger constraint is front-loaded right after the definition, 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?

For a one-parameter mutation with no output schema, the definition covers scope, prerequisites, permission gating, and sibling boundaries. The only shortfall is operational: no mention of latency, async behavior, or whether the call can fail on missing KB entries, which an agent retrying or chaining calls would want.

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 agentId parameter is already documented in-schema as coming from agent_list. The description adds no further semantics about the identifier, so the baseline 3 applies.

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

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

States a specific verb and resource: "Rebuild the agent's knowledge embeddings from its attached knowledge-base entries." It also explicitly bounds the operation against two named siblings (agent_upsert for instructions, kb_attach for adding material), so an agent can distinguish it 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 trigger ("Required after every kb_upsert or kb_attach") plus the consequence of skipping it (stale answers). It also names the alternatives for the adjacent needs, making the when/when-not split 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?

With destructiveHint/idempotentHint/openWorldHint already declared, the description adds real value: it scopes the side effect ('creates or edits the agent and nothing else'), names the required 'Agents' plan permission, warns that an active CHAT agent talks to real prospects, and notes no delete tool exists. It does not explain what an update does to omitted fields among the 25 parameters, which matters given destructiveHint=true.

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 create-vs-update discriminator are front-loaded, then behaviour, then exclusions, then prerequisites. Every sentence carries a decision an agent would otherwise get wrong (active-state risk, knowledge-change ordering, permission requirement) — no filler for a 25-parameter tool.

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

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

Covers creation versus update, permission gate, side-effect boundary, and prerequisite/ordering tools, which is substantial for a 25-param nested destructive upsert. The remaining gap is that with no output schema, it never says what is returned (e.g. the new agent id) after a create, which an agent would need for follow-up calls.

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

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

Schema coverage is 100%, so 3 is the baseline; the description goes slightly beyond by framing the three behavioural fields as distinct axes (personality = identity, intent = goal, instructions = writing rules) and by advising `isActive: false` during drafting. It does not add merge/replace semantics for the many optional fields, so it is not a full 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/update an AI agent) and defines the discriminator inline: pass `agentId` to update. It also draws the boundary against siblings by name (campaign_update, kb_upsert/kb_attach, agent_train, agent_query), so an agent can place it in the workflow 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?

Explicit when-to guidance (set `isActive: false` while iterating; test with `agent_query` before real conversations) plus explicit what-this-does-not-do with the correct alternative for each gap: attaching to a campaign, sourcing knowledge, and building embeddings via `agent_train` after any knowledge change. Nothing about tool selection is left to inference.

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

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

It discloses critical behavioral traits such as performance limitations ('SLOW,' 'may not complete at all') and the aggregation scope, which are essential operational details not found in standard metadata.

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

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

The description is highly dense and perfectly structured to front-load critical constraints and guidance before detailing the specific functionality and scope.

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

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

Given the high-risk/performance nature of this tool, the description is exceptionally complete by providing warnings about failure likelihood and guiding the agent towards more suitable alternatives.

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?

While the schema is 100% covered, the description adds semantic guidance by stating the need to 'narrow' the scope using the `range` parameter, linking the tool's performance directly to parameter usage.

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

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

The description clearly defines the resource (account campaigns) and the specific aggregated metrics it returns, distinguishing its role as a full account roll-up.

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

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

It provides explicit comparative usage guidelines: warns that it is SLOW, suggests alternatives for specific use cases (`analytics_reporting`, `analytics_campaign`), and states the precise condition for its use ('true account-wide roll-up is needed').

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 annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavioral facts: results are totals-only, and this is the cheap call relative to the alternatives. It stops short of describing pagination or latency/cost specifics beyond 'cheap', and the 'totals only' claim sits slightly at odds with the `includeGraph` option, 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?

Three sentences, front-loaded with the metric inventory, then the scope trick, then the routing. Every clause carries information an agent needs; no filler or restated title.

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

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

With no output schema, the description usefully enumerates the returned headline metrics, which is the key missing structured data. Remaining gaps are minor: it does not describe how `range` defaults resolve or what the graph series looks like when `includeGraph` is set, but the schema covers the former and the latter is secondary.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining the meaningful omission semantics of `campaignId` (roll-up across the whole account), which the schema does not state. It adds nothing new for `range`, `userId`, or `includeGraph`, which the schema already documents thoroughly.

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

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

The description names a specific verb+resource (headline performance for one campaign) and enumerates the exact metric families returned: prospects, invites, messages, InMails, emails sent/opened/clicked/bounced, replies. It also states the scope variant (omit `campaignId` for an account roll-up), so it is distinguishable from every analytics sibling 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 says 'Start here for "how is this campaign doing" — it is the cheap one' and then routes the agent away to three named alternatives with the exact condition selecting each: `analytics_reporting` for a day-by-day series, `sequence_step_stats` for drop-off, `campaign_export_stats` for a spreadsheet. This is when/when-not/alternatives all present.

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 the safety profile is covered. The description adds important behavioral context beyond annotations: it is SLOW on campaigns with many leads, walks every activity row, and may not complete at all. It does not describe return shape or pagination, but the performance warning is valuable.

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

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

The description is short, front-loaded with the core purpose, then immediately gives the performance caveat and the faster alternative. Every clause earns its place.

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

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

For a read-only analytics tool with no output schema and 100% schema coverage, the description provides enough context: what the funnel represents, the performance risk, and the recommended alternative. It does not explain the exact returned stages or metric fields, but that is a minor gap given the structured schema and annotations.

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

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

Schema description coverage is 100%, and both parameters are documented in the schema: campaignId with its source, and range with date format and alias details. The description adds no parameter-level syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

States a specific verb-like operation, resource, and scope: stage-by-stage conversion for one campaign over a window. It explicitly clarifies the underlying question ('where are we losing people'), which distinguishes it from generic analytics and campaign tools.

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

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

Names a concrete alternative, `sequence_step_stats`, and explains exactly when to prefer it: on large campaigns where this tool is slow or may not complete. This is explicit when/when-not guidance tied to a sibling.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: results are per-day series aligned to a shared `dates` array rather than totals, and scope is by LinkedIn account not campaign. It does not discuss pagination or limits, keeping it just short of 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?

Front-loads the core definition and metric list, then routes to alternatives. The long metric enumeration is dense but informative; slightly verbose but every clause carries meaning.

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

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

No output schema exists, but the description explains the return shape (per-day series aligned to a `dates` array) and the scoping dimension, which is the key thing an agent needs. Minor gaps around pagination/limits keep it from 5.

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

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

Schema description coverage is 100%, so all four parameters (range, filter, userId, linkedAccountId) are already documented in the schema. The description adds only the `dates` alignment concept and the account-vs-campaign scoping note, not parameter syntax or format detail. 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 (parallel daily series report) and enumerates the metrics returned, plus explicitly names the two sibling tools it is not (analytics_campaign, analytics_trend). An agent can distinguish it from siblings without opening any schema.

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

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

Gives an explicit use case ("how did we trend over the last 30 days") and names alternatives with the conditions that select them: totals per campaign → analytics_campaign, months rather than days → analytics_trend. Also states the scoping caveat (LinkedIn account, not campaign).

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context beyond that: one action type per call, one point per month, and optional campaign or LinkedIn-account scoping. It still does not describe the exact aggregation semantics or return fields, but it adds meaningful clarity for this read-only analytics tool.

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

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

Two tightly written sentences, front-loaded with the core purpose and followed by the key alternative. There is no wasted wording.

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

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

For a simple read-only analytics tool with rich annotations and full parameter schema coverage, the description is nearly complete. It conveys aggregation level and scoping, though it leaves the exact returned metric fields unstated.

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

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

Schema description coverage is 100%, so parameter meanings are already fully documented in the schema. The description reinforces the one-action-type constraint and optional campaign/account scoping, but adds little syntax or format detail beyond the schema.

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

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

The description states a specific resource and shape: month-over-month totals for one action type, optionally scoped to a campaign or LinkedIn account. It also distinguishes the tool from `analytics_reporting` by contrasting monthly one-action-type trends with daily all-action-type reporting.

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 signals the intended use case: monthly trend analysis for a single action type, with an explicit alternative for daily granularity across all action types. It does not explicitly distinguish itself from other analytics siblings such as `analytics_campaign` or `analytics_account`, so it falls 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds that no mutation path exists in the API and that this behaves like `appointment_list`. The field list also gives a useful preview of the response, which matters since there is no output 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?

Two tight sentences, front-loaded with the payload description and followed by the read-only/mutation-location 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 one-parameter read tool with strong annotations, the description covers purpose, response shape, and the absence of write operations. Minor gaps remain around not-found behavior and whether paging or expansion is needed for related lead/conversation data.

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 single parameter has 100% schema description coverage and the schema already says the id comes from `appointment_list`, so the description cannot add much. It offers no format, length, or error semantics for `appointmentId` beyond what the schema states.

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

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

States a specific verb and resource — full detail for one booked meeting — and enumerates what is returned (time, timezone, status, lead, conversation). This is clearly distinguishable from `appointment_list`, which it names 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?

Explicitly frames the tool as read-only and tells the agent that rescheduling and cancelling happen in the web app, which is an effective 'do not use this for mutations' signal. It does not restate the lookup path to an id (that lives in the schema), so guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint/idempotentHint, but the description adds the non-obvious rationale — appointments are never hand-inserted or edited over this server, so write tools are absent by design. That prevents an agent from hunting for a create/update sibling. Pagination and ordering behavior are not disclosed.

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

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

Three short sentences: resource definition first, read-only constraint second, sibling routing last. No filler, and the most decision-relevant constraint is front-loaded after the resource statement.

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 some burden for return shape — it doesn't say whether results are paginated envelopes, what fields appear, or default ordering. For an all-optional-filter list tool the scope statement is enough to call it correctly, but not enough to interpret results.

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

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

Schema description coverage is 100%, so all four parameters (page, leadId, status, conversationId) are already documented with sourcing hints. The description adds no filtering semantics, default sort, or pagination guidance 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 defines the resource precisely — meetings booked out of conversations or created in the web app — which is more informative than a generic 'list appointments'. It also implicitly scopes itself against write tools by stating none exist. It stops short of stating the verb/return shape (a paginated collection) in the description itself, relying on the title for that.

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 rules out creation/editing ('there is no tool to create, change or cancel one') and routes the agent to `conversation_get` when the underlying thread is wanted. It does not, however, contrast with the sibling `appointment_get`, so an agent choosing between fetching one appointment vs listing many gets no 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?

Adds genuinely non-obvious behavior beyond the annotations: the copy is created inactive and nothing executes until isActive is set via automation_upsert. It leaves out whether repeated calls create multiple copies (annotations say idempotentHint=false) and what the call returns, which matters for chaining.

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 outcome ('new inactive draft'), followed by the safety implication and the use case. Nothing is redundant.

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

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

For a single-parameter mutation this covers the safety story well, and the annotations carry the write profile. However, the description tells the agent to activate the copy via automation_upsert without saying whether this tool returns the new automation id — a real gap for chaining, and there is no output schema to fall back on.

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 single parameter has 100% schema coverage and already points to automation_list as the source of the id. The description adds no format, default, or constraint information 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?

'Copy an automation into a new inactive draft' is a specific verb+resource+result-state, not a restatement of the name. An agent can immediately distinguish this from automation_upsert and automation_get in the sibling list.

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

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

It gives a clear use case ('try a change without touching the automation currently handling live events') and names automation_upsert as the step that activates the copy. It stops short of explicit exclusions (e.g. when to edit in place instead of duplicating) but the selection context 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 already declare the read-only, idempotent, non-destructive profile, so the description appropriately adds context beyond them: it returns the full workflow graph and warns that the graph shape is undocumented and must match for execution. It does not describe auth needs or exact response fields, but it adds meaningful behavioral context.

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

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

Two sentences, front-loaded with the returned resource, followed by the key authoring warning. Every sentence earns its place and there is 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?

For a simple one-parameter get tool with no output schema, the description sufficiently covers what is returned (an automation and its full workflow graph) and why the shape matters. It could say a bit more about the response structure, but the critical context is present.

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

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

Schema description coverage is 100%, and the schema already explains that `automationId` comes from `automation_list`. The description adds no parameter-specific detail beyond implying the single automation by ID, 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?

The description clearly identifies the resource returned—'One automation with its full workflow graph'—and implicitly frames it as a read operation. It distinguishes the tool from `automation_upsert` by explaining why to read before writing, though it does not explicitly contrast with `automation_list`.

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

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

It gives clear usage context: read one automation before authoring another with `automation_upsert`, and explains that the node/edge shape is otherwise undocumented. It does not cover when to use this versus `automation_list`, but the primary alternative is named with a clear condition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful domain context and deprecation warnings, but it does not describe listing behavior, return format, or pagination.

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 resource definition, then immediately clarifies the two common confusions: webhooks and campaign sequences. Every sentence earns its place by preventing a likely wrong tool selection.

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

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

For a zero-parameter, read-only list tool with rich annotations and no output schema, the description is largely complete: it defines scope and steers away from deprecated webhook tools and campaign-flow tools. It could mention the shape of returned automation objects, but that absence is minor given the tool's low complexity.

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

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

The tool has zero input parameters, so there are no parameter semantics to explain. Per the zero-parameter baseline, a 4 is appropriate; the description does not need to compensate for parameter documentation.

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

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

The description defines the resource precisely as account-level event-driven workflows outside any single campaign, and explicitly distinguishes it from campaign sequences handled by `flow_get`/`flow_set`. It does not directly state the listing action, but the tool name and title make that clear, and the scope is well differentiated from siblings.

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

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

It gives explicit exclusions and alternatives: webhook tools are deprecated and should not be looked for, while campaign sequences belong to `flow_get`/`flow_set`. This routes the agent away from wrong siblings, though it does not state prerequisites or when to prefer `automation_get` after listing.

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

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

Beyond the annotations, the description discloses critical behavior: the whole `flow` graph is replaced rather than patched, activation makes the automation run against live events and can message real people, and campaign sequences are untouched. These details materially change how an agent should invoke the tool.

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

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

The description is front-loaded with create-or-update behavior, then moves through graph shape, activation risk, replacement semantics, and scope. Every sentence contributes operational guidance 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 nested, mutation-style tool with no output schema, the description covers the important invocation and safety context. It does not explain what the call returns, which is a minor gap, but the core behavior and graph-replacement semantics are sufficiently complete.

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

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

Schema coverage is 100%, so the schema already defines all five parameters. The description adds valuable meaning for key parameters, especially `_id` for update mode, the replacement semantics of `flow`, and the live-event risk of `isActive`; however, it does not detail the internal node/edge shape beyond pointing to the builder and `automation_get`.

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

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

The description states a specific upsert operation for automations and clearly distinguishes creation (omit `_id`) from update (pass `_id`). It also names related tools (`automation_get`, `flow_set`) so the agent can separate this from neighboring operations.

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

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

It gives explicit workflow guidance: read an existing graph with `automation_get` before hand-authoring, keep `isActive` false while drafting, and get explicit approval before activating. It also names exclusions, including `flow_set` and the absence of a delete tool.

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

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

Annotations only give generic hints (readOnly=false, destructive=false, non-idempotent); the description adds real behavioral facts: the rule is account-wide and lasting, matching is substring-based for KEYWORD/JOB_TITLE with a concrete warning about over-broad terms, and rules cannot be deleted afterwards.

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 what the tool does, then the matching caveat, then the routing alternatives. Every clause carries distinct information; nothing is restated from the title or schema verbatim.

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

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

For a 3-parameter mutation with no output schema, the description covers scope, matching semantics, alternatives, and irreversibility. The only omission is what the call returns (e.g., a created rule id), which is minor given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning beyond the schema by explaining that keyword values are matched as substrings against the profile and must be kept specific, plus the concrete failure mode ('director' would exclude a large slice).

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

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

Opens with a specific verb ('Exclude') and enumerates the exact matchable resources (profile URL, company URL, keyword, job title, email). It is immediately distinguishable from siblings by naming `lead_update`/`isExcluded` and `blacklist_add_bulk` as different routes.

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

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

Explicitly states when not to use it ('not a way to skip one prospect in one campaign, which is `lead_update` with `isExcluded`') and which tool handles batches (`blacklist_add_bulk`). It even closes the loop on rule removal by stating no delete tool exists.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's key contribution is the irreversible consequence: rules 'cannot be removed afterwards by any tool.' That is exactly the kind of context annotations cannot convey. It does not address idempotency (annotations say not idempotent), so whether duplicate keywords are silently doubled is left unclear.

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 bulk-vs-single relationship and the irreversible warning are both front-loaded, and there is no filler or redundancy with 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 an irreversible bulk mutation with no output schema, the description supplies the one piece an agent most needs — that the effect cannot be undone. It leaves open what happens to a 5,000-entry payload that partially fails and what the response reports, which is a real gap for a bulk operation but a minor one given full schema coverage.

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 both parameters are documented inline, including the type enum and keyword matching semantics, so the schema does the heavy lifting. The description's examples ('competitor domain list, or an opt-out export') loosely illustrate what entries look like but add no format or constraint detail beyond the schema (e.g. the 5,000 cap comes from the schema).

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

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

The description states a specific verb and resource ('add many exclusion rules at once') and explicitly relates it to the sibling `blacklist_add` ('same effect as `blacklist_add`, one call'), so an agent can distinguish bulk from single-add without opening either schema.

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

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

It gives clear usage context (a competitor domain list, an opt-out export) and implicitly routes single additions to `blacklist_add`, plus a procedural prerequisite to review the list with the user. It stops short of explicit when-not conditions, such as what to do on partial failure or whether to prefer `lead_blacklist` for individual 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?

Goes well beyond the annotations: discloses merge-not-replace semantics, the irreversibility of the operation (no delete tool), and a recommended pre-check. Annotations (destructiveHint=false, idempotentHint=false) are consistent with an additive, non-undoable write, and the description supplies the practical consequence the flags don't convey.

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

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

Two sentences, zero waste: the core action comes first, then the merge semantics, then the prerequisite. The parenthetical caveat about no removal tool is placed exactly where it matters.

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

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

For a 2-param mutation with no output schema, the description covers what changes, what does not change (destination rules preserved), that the change cannot be undone, and how to preview the outcome. Nothing an agent needs before calling 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 the schema already labels `linkedAccountId` as source and `newLinkedAccountId` as destination. The description's 'from one account onto another' mirrors that mapping without adding new detail such as ID format or validation.

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

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

States a specific verb+resource+scope: cloning every exclusion rule from one LinkedIn account to another. Clearly distinguishes itself from siblings like blacklist_add (single rule), blacklist_list (read), and blacklist_delete by making it a whole-set transfer between two accounts.

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

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

Explicitly routes the agent through a prerequisite: read the destination with `blacklist_list` first. It also gives a negative constraint (no removal tool exists afterwards), which is exactly the when-to-be-careful guidance an agent needs.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the description is not burdened with the basic safety profile. It goes further, disclosing the concrete consequence (previously blocked prospects become targetable again) and why that is dangerous (opt-outs, competitors, do-not-contact requests leaking back into campaigns). That is exactly the value-add this dimension rewards.

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

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

Three sentences, front-loaded with the action, then the risk, then the scoping caveat. The risk statement sits ahead of the workflow instruction, which is the right priority for a destructive tool, and nothing is padded.

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

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

A one-parameter destructive tool with full annotation coverage and no output schema needs exactly this: consequence of the mutation, pre-call verification workflow, and disambiguation from the similarly named blacklist tools. All present; no return-value explanation is required.

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 parameter is already documented as a blacklist rule id sourced from `blacklist_list`. The description repeats that provenance rather than adding new meaning about the id's format or behavior. Baseline 3 is correct when the schema does the work.

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

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

States a specific verb+resource ('Remove an exclusion rule') and immediately distinguishes the scope from the nearest confusion point: it removes a rule, not a blacklisted person, which is handled by `lead_blacklist`. An agent can separate this from `blacklist_list`, `blacklist_add`, and `lead_blacklist` 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 pre-call procedure: read the rule with `blacklist_list`, show the user exactly what it blocks, and obtain an explicit yes. It also names the alternative record path (`lead_blacklist`) and notes no tool removes that record, so both the when and the when-not are covered.

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

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

Annotations already disclose readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds that the output is a CSV delivered as a file rather than inline data, which is genuinely useful context. However, it says nothing about where the file lands, whether repeated calls duplicate artifacts, or how the file is surfaced to the agent, so the added behavioral surface is thin.

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

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

Three short sentences with no filler, and the core action is front-loaded ahead of the sibling routing hint. The fragment "A file for the user" is clipped and could be folded into the first sentence, but nothing is wasteful.

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 one documented parameter, no output schema, and annotations covering the safety profile, the description covers the essential decision (export to file vs. list in chat) and states the output medium. The only gap is what the caller actually receives back (file reference, link, or notification), which it doesn't specify.

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

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

There is a single required parameter with 100% schema description coverage, and that description already points to `linkedin_account_list` for the id. The description adds no further meaning about the parameter (e.g., whether the export is scoped strictly to one linked account), 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?

The description uses a specific verb and resource ("Generate a CSV of every exclusion rule on an account") and explicitly distinguishes itself from the sibling `blacklist_list` for in-conversation reading. An agent can separate this export tool from the list/add/delete blacklist siblings without opening any schema.

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

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

It names the alternative explicitly and gives the condition that selects it ("To read the rules in the conversation use `blacklist_list`"). It doesn't cover exclusions such as prerequisites, account-scope caveats, or when an export is inappropriate (e.g., large accounts), so it stops short of a full when/when-not map.

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 annotations already establish that this is a safe, read-only, idempotent operation. Beyond that, the description adds meaningful behavior: rules are per LinkedIn account, affect every campaign on that account, and filter prospects before they enter campaigns.

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 resource definition and then adds only the scope, diagnostic use, and alternative. There is no wasted text, and the per-account versus per-campaign distinction is stated efficiently.

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

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

For a simple read-only list with fully described parameters and clear annotations, the description is nearly complete. The main gap is that it does not state what happens when `linkedAccountId` is omitted, even though the schema marks it optional.

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 three parameters are already documented by the schema. The description reinforces the account-level scope but does not add format or behavior details beyond what `linkedAccountId`, `page`, and `pageSize` already 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?

The description defines the resource as exclusion rules for a LinkedIn account and explains their effect: matching prospects are filtered before entering campaigns. It distinguishes this list from the per-campaign exclusion alternative, though the retrieval verb itself is only implied by 'Read it' rather than stated directly.

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

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

It gives an explicit diagnostic use case: read this when a search returns fewer leads than expected. It also names the alternative for a different need, `lead_update` with `isExcluded`, and clarifies the per-account scope that separates this tool from per-campaign 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 closed-world, so safety is covered. The description adds value beyond that by disclosing the return shape ('three numbers for the whole campaign') and a relative cost signal ('cheapest'), which helps an agent decide when to reach for it. Minor gap: no note on how quickly counts refresh relative to recent 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?

Two sentences, zero waste, with the core purpose and scope front-loaded before the sibling routing. 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?

No output schema exists, and the description compensates by naming the three metrics returned (pending, completed, failed) and their granularity (whole campaign). Combined with annotations covering safety and a single fully documented parameter, nothing essential 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?

The single campaignId parameter has 100% schema description coverage, including where to obtain it (campaign_list or campaign_create), so the schema does the work. The description adds nothing about the parameter, which is acceptable at this coverage level but not additive.

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 ('aggregate counts') and resource ('pending, completed and failed actions across the campaign'), and explicitly contrasts its scope with per-step and per-lead siblings. An agent can distinguish it from sequence_step_stats and sequence_leads_at_step without opening any schema.

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

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

Gives an explicit selection rule: this is the cheapest 'is it working' check for the whole campaign, while sequence_step_stats covers the same split per step and sequence_leads_at_step covers leads behind one step. Both alternatives and the condition that selects them 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?

Goes well past the destructive/openWorld/non-idempotent annotations: it discloses async background execution with multi-minute latency, the thrown-error preconditions with literal messages, and the non-obvious side effect that a child campaign is created (which explains why campaign_delete reports removing active children). This is exactly the context structured fields 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 core action, then preconditions, then alternatives, then the child-campaign note. Dense but each sentence carries real information; the campaign_delete cross-reference is slightly tangential but justifies itself as a side-effect disclosure.

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 stating it runs in the background and can take minutes, so the agent knows not to expect immediate leads. It doesn't say what is returned or how to track progress of the background job, which is the one remaining gap for an async mutation.

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 each property (url, type, field, query, campaignId) is documented in the schema, so baseline 3 applies. The description adds only an implicit mapping of 'new source' to the `type` enum and does not clarify which of url/field/query applies to which type branch.

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

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

States a specific verb+resource+scope: 'Top up an already-running campaign with prospects from a new source, without touching its sequence or existing leads.' This is immediately distinguishable from campaign_create, campaign_set_source, and campaign_upload_leads without opening any schema.

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

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

Explicitly names the when-not case ('this is never how a new campaign gets its audience') and routes to the two correct alternatives by name, campaign_set_source and campaign_upload_leads. Two hard preconditions (ACTIVE, first batch filtered) are stated with the exact backend error string.

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

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

Annotations declare non-readOnly, non-destructive, non-open-world, non-idempotent, but the description adds the crucial behavioral facts the annotations cannot convey: the campaign is created in DRAFT state and nothing is sent until campaign_launch. It also clarifies the call has a single narrow effect ('creates the campaign and nothing else'), so the agent won't assume side effects like sequence or account configuration.

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 key fact (draft, nothing sends until launch) and organized around sourceUrl paths. Slightly redundant: 'Nothing sends until campaign_launch' is restated by 'it only sends after campaign_launch' at the end, costing a bit of density.

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 only 2 fully-described params and no output schema, the description supplies the missing workflow context — post-creation steps (flow_set, campaign_update, campaign_launch, campaign_upload_leads) — so an agent knows exactly where this call sits in the campaign-building sequence.

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

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

Schema coverage is already 100%, so the baseline would be 3; the description earns above that by explaining sourceUrl's accepted URL families (LinkedIn/Sales Nav/Recruiter/group/event/post) and the strategic choice of when to supply it versus omitting it. It doesn't add format specifics beyond the schema's own inference note, keeping it at a 4.

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

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

States a specific verb+resource ('Create a DRAFTED campaign') and immediately scopes it: the draft is inert until campaign_launch. The final sentence enumerates what this call does NOT do (sequence, accounts/limits, sending), cleanly separating it from flow_set, campaign_update, and campaign_launch.

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: pass sourceUrl for URL-harvested prospects, omit it and use campaign_upload_leads for CSV, and never start with campaign_duplicate unless the user named a campaign to copy. This is a textbook when-to-use / when-not / alternative specification.

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

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

Goes well beyond the annotations by disclosing the exact side effects: half of not-yet-contacted leads are moved out of the original into a new DRAFTED campaign, the flow is copied, and the original is renamed to '<title> [A]' leaving it with half its audience. It also quotes the failure mode and error string. Although the audience loss on the original sits in some tension with destructiveHint=false, leads are moved rather than deleted and the outcome is fully disclosed, so this is not a 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?

Front-loads the decisive fact (splits, not copies) in the first sentence, then layers side effects, precondition, and the alternative in descending importance. Dense with no filler despite its length.

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

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

One parameter, no output schema, so the description only needs to cover selection logic and consequences. It covers both thoroughly, including the exact error message and the backend's own suggested fallback.

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

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

Schema coverage is 100% and the single `campaignId` parameter is already documented as coming from `campaign_list` or `campaign_create`. The description adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource (split a campaign into an A/B pair) and immediately distinguishes it from the confusingly similar `campaign_duplicate` by insisting 'This SPLITS, it does not copy.' An agent can select correctly without opening the schema.

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

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

Gives explicit routing rules in both directions: use `campaign_duplicate` when the audience should be left alone, use this when the point is to compare two versions on one audience. It also states the precondition (>10 contacts still waiting) and points to `analytics_campaign` for the follow-up comparison.

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 and idempotentHint, but the description goes well beyond them: it explains this is a soft delete, that leads/sequences/activity records persist, that sending halts because workers only pick up ACTIVE campaigns, and that there is no reversal path. That is rich, non-obvious behavioral context that the annotations alone cannot convey.

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

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

The critical warning (no undelete, confirm first) is front-loaded, and most sentences carry distinct information. However, the irreversibility point is restated three times ("no tool to bring it back," "confirm with the user first," "confirm before calling: there is no undelete"), which is more repetition than the warning requires.

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

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

For a one-parameter mutation with no output schema, the definition covers safety, side effects, and post-call visibility thoroughly. The remaining gap is the inaccurate claim about being the sole status writer, which could cause an agent to overlook `campaign_set_status`.

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

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

There is a single parameter with 100% schema description coverage, and the schema already documents it as the id from `campaign_list` or `campaign_create`. The description adds no syntax, format, or edge-case guidance about campaignId, 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?

The description gives a precise verb and resource plus the actual mechanism: the campaign is moved to DELETED rather than erased. It also distinguishes the tool from campaign_update by parameter shape. The only blemish is the flat assertion that this is "the only tool allowed to write a campaign status," which sits awkwardly against the sibling `campaign_set_status` and could mislead an agent comparing 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?

Explicit when-to-use, when-not-to-use (pausing sending belongs in the web app), and a required confirmation step with the user before calling. It also names the consequence of misuse (vanishing from campaign_list, no undelete), which is exactly the routing information an agent needs.

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 that this is a non-read-only, non-destructive, non-idempotent operation. The description adds valuable beyond-annotation context: the result is a new DRAFTED campaign, leads are not copied, the copied sequence preserves original messaging, and sequence_update edits are reverted at launch on an unlaunched duplicate.

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 action and then layers usage, exclusions, and limitations in four purposeful sentences. Every sentence contributes actionable selection or invocation guidance, with no repetition.

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

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

For a one-parameter duplication tool with no output schema, the description covers purpose, when to use it, when not to use it, alternatives, and important behavioral limitations. The one minor gap is that it does not state what the tool returns, such as the new campaign identifier, but the selection and invocation guidance is otherwise complete.

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

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

Schema coverage is 100%, and the schema already documents campaignId as the existing campaign obtained from campaign_list. The description reinforces that it must be one specific existing campaign but adds no new syntax or format semantics 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?

The description states a specific verb and resource: copy an existing campaign's settings and whole sequence into a new DRAFTED campaign, without leads. It also explicitly distinguishes this from campaign_create and sequence_update, so an agent can identify it without opening the schema.

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

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

It gives an explicit ONLY condition — when the user asks to duplicate a campaign they have named — and directly names campaign_create as the alternative for starting fresh. It further clarifies that a duplicate is only useful when the existing copy is meant to be kept, which rules out misuse for sequence editing.

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 and destructiveHint=false; the description adds the material hidden behavior — the file is served from a CDN and emailed to the account owner, i.e. it leaves the conversation. That is exactly the out-of-band side effect an agent needs to know before invoking a non-idempotent export.

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 delivery caveat, then routing. Slightly self-referential with 'which is worth leaving in' style asides ('so it leaves the conversation, which is worth mentioning before calling it'), but no sentence is filler.

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

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

No output schema exists, and the description compensates by stating what is returned (a filename) plus where the file lives (CDN) and that it is emailed. With zero required params and fully documented schema, nothing an agent needs in order 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% and the nested `range` object already documents `from`/`to` aliases, ISO/epoch formats, and the backend default when omitted. The description adds no parameter-level guidance, so the schema carries the load and the baseline 3 applies.

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

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

States a specific verb and resource ('Generate a CSV export of campaign performance') and adds the return shape (a filename). It explicitly distinguishes itself from the two nearest siblings, `lead_export` (prospect data) and `analytics_campaign` (inline numbers), so an agent can route correctly without opening a schema.

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

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

Gives an explicit when-to-use-each rule: use this for performance numbers as a file, `lead_export` for a file of prospects, `analytics_campaign` to read the numbers in-conversation. It also surfaces a precondition (the export leaves the conversation and is emailed to the account owner) that should be considered before calling.

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=false, destructiveHint=false, idempotentHint=false), so the description's added prerequisite about the connected AI provider is genuine value beyond the structured data. It also clarifies the result lands as a draft rather than a launched campaign, which is useful behavioral context. It does not mention that AI drafting is slow/long-running or that repeated non-idempotent calls create duplicate campaigns, which keeps it from a 5.

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

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

Two sentences with zero waste: the core action and its output come first, the prerequisite second, and the sibling routing last. Nothing is repeated from the schema or annotations.

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

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

For a 9-param, 8-required mutation with no output schema, the description is nearly complete — action, prerequisite, and alternative are all present. The remaining gap is the return value: it never says whether the call yields a campaign ID, the generated sequence, or just a success flag, which matters for chaining into campaign_launch or flow_get.

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 every param carries an example-bearing description, so the schema does the heavy lifting and 3 is the baseline. The description adds only the framing that the inputs constitute a "brief"; it says nothing about stepCount bounds (1-10) or how the fields interact with the generated sequence.

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?

Names a specific verb and resource ("ask the platform's own AI to draft a whole campaign — copy and multi-step sequence") and states the outcome ("create it as a draft"). Clearly distinguishes from the manual-authoring sibling flow_set and from campaign_create, so an agent can route without opening a schema.

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

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

Gives an explicit selection rule ("Use this when the user wants the platform to write the sequence for them") plus the inverse case with the named alternative ("to author one yourself, use flow_set"). It also states a hard prerequisite (AI provider connected under Settings - Integrations) that would otherwise cause a silent runtime failure.

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 substantial context beyond them: the readiness-blocker gating logic, the status field's role in choosing an edit path, and the fact that this is a snapshot rather than a detailed sequence or performance view. No output schema exists, and the description compensates by enumerating the returned fields.

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

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

Three dense sentences, each carrying distinct information: contents, gating precondition, and sibling routing. The most important constraint (readiness before launch) is front-loaded and nothing is redundant.

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

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

For a read-only getter with no output schema, the description covers return contents, the readiness/blocker contract, and how the result drives downstream tool choice. An agent has everything needed to call it and act on the response.

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 both parameters (campaignId, includeFlow) are documented in the schema itself. The description adds no syntax, format, or defaulting detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Everything about one campaign') and enumerates exactly what is returned: settings, schedule, limits, attached accounts, lead source, counters, flow outline. It explicitly distinguishes itself from flow_get, analytics_campaign, and lead_list, so an agent can pick it 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 when-to-use ('call before changing anything'), a hard precondition ('_readiness.blockers must be empty before campaign_launch'), and conditional routing based on `status` (flow_set for DRAFTED, sequence_update for ACTIVE/PAUSED). Alternatives are named with the conditions that select them.

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/openWorld/non-idempotent) by spelling out the real-world consequence — outreach is actually sent to real people on a schedule — and a non-obvious behavior: launch rebuilds every step from the saved flow graph, overwriting any `sequence_update` edits made while in draft. That is exactly the kind of gotcha the annotations cannot convey.

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

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

Front-loads the action and consequence, then layers prerequisites, consent, the overwrite warning, and sibling routing. Every sentence carries an operational constraint; nothing is filler despite the length.

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

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

For a non-idempotent, destructive, side-effect-heavy launch tool with no output schema, it covers readiness blockers, required human confirmation, destructive overwrite semantics, and correct sibling picks. An agent has everything needed to call it safely and 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 `campaignId` and `skipPreflight` are already documented in the schema. The description implies a preflight/readiness concept ('clear every blocker') but never ties it explicitly to the `skipPreflight` flag, so it adds only marginal value beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb and resource ('Start a campaign') and immediately describes the concrete effect: real invitations, messages and emails go out from the connected LinkedIn account and mailboxes. It explicitly separates itself from siblings ('the only tool that starts a campaign'; pausing/resuming is `campaign_set_status`).

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 preconditions (run `campaign_get` first, clear every blocker: saved flow, lead source, sending account, finished CSV import) and an explicit consent requirement (show the sequence and audience, get a real yes, not an assumed one). It also names the correct alternative for editing draft copy (`flow_set`) and for lifecycle changes (`campaign_set_status`).

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 real context beyond them: newest-first ordering, 20-per-page pagination, the fact that DELETED campaigns never appear (so deletion looks like disappearance), and the owner-only constraint on userId. That is exactly the extra behavioral detail 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?

Dense but front-loaded: scope and ordering first, then filter semantics, then the deletion caveat, then sibling routing, then the permission note. No sentence is filler.

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

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

No output schema exists, and the description compensates by telling the agent the return shape is a partial list ('a few fields each') and pointing to campaign_get for full detail. Combined with pagination and permission notes, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the practical distinction between DRAFTED and ACTIVE statuses and the permission rule for userId. It stops short of covering page/keyword semantics, which the schema already handles.

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 ('Campaigns in your account') plus ordering and page size, and explicitly distinguishes itself from campaign_get and analytics_campaign. An agent can tell it apart from siblings without opening a schema.

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

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

Names the alternatives and the condition that selects them: 'for one campaign in full use campaign_get, and for performance analytics_campaign.' It also explains what the status filter means in practice (DRAFTED = being built, ACTIVE = sending now).

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 is covered. The description adds value beyond that by disclosing that entries are chronological and attributed to the actor ('written by whoever made them'), which is what makes it an audit trail. It stops short of stating retention window, pagination, or volume caps for a log that could be long.

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

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

Two sentences, front-loaded with the core definition and the event list before the exclusion. Dense but every clause earns its place; the em-dash parenthetical could be tightened slightly, but nothing is redundant.

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

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

For a one-parameter, read-only, non-open-world log tool with no output schema, the description covers what the resource is, what an entry represents, and who authored it. It does not describe the entry shape (timestamp/actor/event fields) or result size, which would help since there is no output schema, but the essential calling information is present.

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

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

With a single parameter and 100% schema description coverage (campaignId, sourced from `campaign_list` or `campaign_create`), the schema carries the full burden. The description adds no further detail about the id format or how missing/invalid ids behave, so baseline 3 is appropriate.

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

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

States a specific resource and scope: a chronological record of everything that happened to a campaign, with an enumerated list of event types (created, started, paused, resumed, lead sources added, settings changed, limits hit). It also draws a hard line against prospect-level history, naming the sibling tools that cover that instead, so an agent can distinguish it 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 use case: 'the audit trail to read when a user asks why a campaign stopped or who changed a limit.' It also names the negative case and routes to alternatives (`activity_list`, `lead_get`, `sequence_step_stats`). Both when-to-use and when-not-to-use are present.

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 as a read-only, idempotent, non-destructive operation. The description adds valuable behavioral context beyond annotations: nothing is sent or saved, and unknown placeholders render empty rather than failing, which is non-obvious and important for interpreting preview 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?

The description is tightly written and front-loads the primary purpose. Every sentence carries useful information: the preview behavior, the safety/failure semantics, and the alternative tools.

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, read-only preview tool with full schema coverage and annotations, the description is complete enough. It explains what the agent will see and why it is safe, and it routes adjacent work to the correct siblings.

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 `campaignId` and `message` are already documented in the input schema. The description adds some useful context about placeholder resolution and using a real lead, but does not provide additional parameter syntax or format details 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?

The description states a specific verb and resource: render a draft message against a real campaign lead to inspect merge-field resolution. It also distinguishes the preview action from saving via `flow_set` and from sending a test email via `campaign_send_test_email`.

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

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

It gives explicit when-to-use guidance: check the copy before committing it to a step. It also names the alternatives for adjacent tasks, `flow_set` for saving and `campaign_send_test_email` for putting a real email in front of the user.

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 openWorldHint=true, so the description's real contribution is spelling out what that means in practice: one real email leaves the system, the user must see recipient/subject/body and give an explicit yes, and it is only for addresses the user controls. It does not say anything about rate limits or what comes back on success, which keeps it below 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 the tool does, then the safety gate, then the alternative. Every sentence earns its place and nothing is 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 single-fire side-effecting tool with no output schema, the description covers purpose, consent requirements and the safer alternative. The only soft gap is that it does not say what the agent gets back or how failures surface, though annotations and the simple shape make that low-risk.

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 every parameter including the campaignId and emailAccountId cross-references is already documented. The description only mentions recipient, subject and body in the confirmation flow and adds no format or validation details beyond the schema — 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 ('Send one real email ... using a campaign mailbox') and scopes it to a testing purpose, which cleanly separates it from campaign_preview_message and from the prospect-messaging tools. The sibling it is not is named explicitly.

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

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

Gives concrete when-to-use conditions (check rendering and deliverability before launch), an explicit when-not-to-use ('not a way to message a prospect, and there is no tool for that'), and names the alternative for the read-only case: campaign_preview_message.

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=true; the description earns credit by explaining the nature of that destruction ('replacing the source'). It does not cover validation failures at the tool level (only the surface parameter schema notes rejection) or the effect on prospects already attached to the campaign.

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

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

Two sentences, zero filler, with the state constraint and source kinds front-loaded and the sibling routing placed second. Every clause carries decision-relevant information.

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

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

For a 6-parameter mutation tool with fully documented schema, the description covers the essential draft-vs-active distinction and replacement semantics. It stops short of saying what happens to previously staged prospects or whether the call can be re-run safely, which idempotentHint implies but does not confirm.

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's enumeration of source kinds loosely maps to the 'type' enum and hints that CRM sources exist, but adds no syntax, defaults, or cross-parameter rules beyond what the schema already documents.

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 ('Point a DRAFTED campaign at where its prospects come from') and enumerates the accepted source kinds: LinkedIn/Sales Navigator search URL, group, event, post, or CRM segment. It explicitly contrasts itself with campaign_add_prospects, so an agent can separate the two without opening either schema.

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

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

Gives an explicit precondition ('DRAFTED campaign') and names the alternative for the other state ('For an ACTIVE campaign use campaign_add_prospects instead'). It also explains the behavioral difference — replacing the source vs adding to the existing pool — which is the exact decision the agent must make.

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=false and idempotentHint=true, but the description adds the operationally critical fact that the client will not prompt for confirmation — the agent must solicit it itself — plus that pending steps stay queued and resume in place. It also discloses the refusal behavior for non-PAUSED campaigns and the failure mode of the blind `updateCampaign` path.

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 sentence one and every sentence carries operational weight. Slightly dense and clause-heavy in the middle, but no sentence is filler.

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

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

Two required params, full schema coverage, no output schema needed, and annotations covering the safety profile — the description closes the remaining gaps (confirmation ownership, queue behavior, refusal conditions, sibling routing) with nothing material missing.

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

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

Schema coverage is 100% and the enum is documented, so the baseline is 3. The description earns an extra point by explaining *why* ACTIVE is refused for non-PAUSED states (a DRAFTED campaign would be marked live without a lead source, flow, sending account, or sequences), which is rationale the schema does not carry.

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

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

States a specific verb pair and resource (pause/resume a campaign) and immediately delimits itself against siblings: `campaign_launch`, `campaign_delete`, and raw `updateCampaign`. An agent can distinguish this from every adjacent campaign tool without opening a schema.

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

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

Gives explicit when-to-use (pausing needs no ceremony), when-not (won't ARCHIVE, COMPLETE, DELETE, or start a never-run campaign — use `campaign_launch`), and a hard gating rule: ask the user before resuming because the pause reason may be unknown to the agent.

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

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

Beyond the annotations, the description discloses important mutation semantics: only passed fields are changed, and changing linkedAccountId rewrites that account onto every existing lead in the campaign. It also explains account-attachment behavior and cautions that agentId should not be set without user approval.

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 long but appropriately sized for a 24-parameter mutation tool, and it is front-loaded with the core purpose before exclusions and side effects. Each section adds operational value rather than restating 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?

Given the tool's complexity, nested schema, and lack of an output schema, the description covers the critical context: scope, exclusions, alternatives, account attachment, and the linkedAccountId side effect. An agent has enough information to invoke it correctly without needing return-value details.

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 meaningful cross-parameter semantics: linkedAccountId is singular, emailAccountIds is a rotating list, and the user should be asked when there is a choice. It also adds caution around tags and agentId, though it does not explain every one of the 24 parameters.

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

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

The description states a specific verb and resource: changing campaign settings such as title, accounts, schedule, limits, timezone, and safety toggles. It explicitly distinguishes this from status, sequence, and audience operations, so an agent can separate it from siblings like campaign_set_status, flow_set, and campaign_set_source.

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

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

It gives explicit when-to-use and when-not-to-use guidance, naming alternatives for launching, pausing/resuming, deleting, sequence changes, and audience changes. It also states that archiving is web-app only and has no tool, which prevents the agent from searching for a nonexistent substitute.

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 (not read-only, not idempotent, not destructive); the description adds the behavior that actually matters: rows lacking both a profile URL and an email are dropped silently, the import is asynchronous, and the campaign is not launchable until isFiltered flips true. That silent-skip and blocking-state disclosure is exactly the kind of context annotations cannot carry.

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

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

Four sentences, zero filler, front-loaded with purpose then field mapping then edge-case behavior then routing. Each sentence carries distinct information an agent needs.

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

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

For a 4-parameter mutation with no output schema, it covers async behavior, silent-skip rules, the launch-blocking flag, and sibling routing. The remaining gap is what the call returns (imported vs skipped counts, job handle for polling) — with no output schema, a hint there would close the loop.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds genuine value the schema lacks: the header schema declares additionalProperties:false without enumerating permitted target fields, and the description supplies the full list (profileUrl, salesNavUrl, recruiterUrl, email, firstName, lastName, fullName, personalization, phone, website, customVariable). It does not explain removeDuplicates semantics, which keeps it from 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: "Bulk-load prospects into a campaign from parsed CSV rows." It immediately distinguishes itself from campaign_add_prospects and campaign_set_source, so an agent can pick it 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 gives the selecting condition ("Use this when the user has a list in hand") plus two exclusions with named alternatives: audience-described cases go to campaign_set_source (built via search_url_build), and already-running campaigns go to campaign_add_prospects. When-to-use, when-not-to-use, and alternatives are all present.

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 discloses a non-obvious side effect not captured by annotations: reading a thread marks it seen. This aligns with the non-read-only annotation and gives the agent critical operational context before invoking the tool.

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

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

The description is front-loaded with what is returned, immediately follows with the side-effect warning, and then routes to alternatives. Every sentence contributes either purpose, caution, or differentiation.

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 two parameters, full schema coverage, no output schema, and a meaningful side effect, the description provides enough context to invoke it correctly. It covers returned contents, the key warning, and sibling-tool boundaries.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description only lightly echoes the message-history behavior through its mention of full history, without adding parameter-specific syntax or constraints 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?

The description clearly identifies the resource as one conversation thread and specifies that it returns the full message history, the associated lead, and the originating campaign. It also distinguishes this prospect-facing exchange from sibling tools like agent_logs and lead_get, so an agent can tell what it retrieves without opening the schema.

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

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

It gives an explicit when-not-to-use rule: reading marks the thread seen, so it should not be used merely to browse unless the user wants the badge cleared. It also names the correct alternatives for agent reasoning logs and lead step history, leaving little inference for tool selection.

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 genuinely new behavior — default ordering by newest activity, 20-per-page paging, and that no send capability exists anywhere in the surface. It stops short of describing the thread object's fields, which matters since there is no output schema.

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

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

Front-loaded with the resource and ordering, and every routing sentence carries information. There is some redundancy — 'newest activity first' is restated as 'Threads, newest first — the conversation view' — which slightly dilutes an otherwise tight block.

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

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

For an 8-parameter read tool with no output schema, the description covers ordering, page size, two key filters and all plausible sibling substitutions. The main residual gap is the shape of a returned thread (fields, participants, unread state), which the agent must infer.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns a bump by explaining the intent behind two filters — campaignId as 'review one campaign's responses' and keyword as finding 'a specific person' — which reframes the schema's 'Search names and message bodies'. The remaining six filters (tags, type, platform, emailAccountId, linkedAccountId, page) are left entirely 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?

Opens with a concrete resource framing — 'The unified inbox: LinkedIn and email threads with prospects' — plus ordering and page size. It explicitly distinguishes itself from conversation_get, lead_get and analytics_campaign, so an agent can route without opening a schema.

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

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

Gives explicit when-to-use conditions for two filters ('campaignId to review one campaign's responses', 'keyword to find a specific person') and names three alternatives with the exact scenario each serves. It also states a boundary case ('Nothing here sends'), closing off a plausible but wrong intent.

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 mutation safety profile, but the description adds meaningful behavioral context: the operation is account-wide, marks even unread threads nobody has looked at, and should be confirmed before use. It does not cover permissions, reversibility, or response behavior, but it substantially improves transparency 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?

The description is three tightly written sentences with no waste. Impact and caution are front-loaded, and the sibling alternative is mentioned at the end where it is most useful.

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

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

For a one-parameter mutation tool with annotations and no output schema, the description covers purpose, scope, side effect, caution, and the relevant sibling alternative. Nothing an agent needs in order 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?

There is one parameter (`linkedAccountId`) with 100% schema description coverage, including the source tool for obtaining the value. The description does not add syntax or meaning beyond the schema, 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: clearing the unread badge across every thread on one LinkedIn account. It also explicitly distinguishes itself from the single-thread alternative `conversation_update`, so an agent can choose correctly 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?

Provides explicit when-to-use context and a clear alternative: use this for account-wide badge clearing, but use `conversation_update` for one thread. It also advises confirming before use because the effect is blunt and account-wide.

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

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

Annotations already declare non-destructive, idempotent, open-world behavior, so the description only needs to add context — and it does, by bounding the blast radius ("scope is this thread: it does not stop the agent elsewhere... or change the lead itself") and by clarifying the tool cannot send a reply. It stops short of stating whether the change is trivially reversible for the non-archived flags, which would have completed the picture.

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 capability statement is front-loaded, followed by the highest-value scenario, then the boundary conditions. Every sentence carries routing or scoping information; there is no restatement of the title or the schema beyond what adds meaning.

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

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

For a 5-parameter mutation with no output schema, the description plus annotations cover safety, scope, and alternatives well. The only omission is any indication of what the call returns or how partial updates behave (whether omitted fields are left untouched), which matters for an idempotent partial-update tool.

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

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

Schema coverage is 100%, so the schema baseline is a 3; the description earns above baseline by explaining the operational consequence of `assistant: false` ("stops the bot replying so a person can take over"), which is meaning the schema's one-line field note does not convey. The other parameters (seen, isArchived, pauseBotOnManualMessage) are left entirely 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?

The opening sentence names three concrete operations (archive, mark read, hand off between AI and human) on a clearly identified resource, a conversation thread. It is immediately distinguishable from siblings like conversation_mark_all_read or message_send, which the description also implicitly rules out.

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 guidance: "the one call to make when an agent is answering badly and a human needs the thread," tied to the concrete `assistant: false` parameter. It also gives explicit when-not/where-else guidance by naming agent_upsert with isActive: false, campaign_update, and lead_update as the correct tools for the adjacent concerns.

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 annotations already declare the key safety profile: not read-only, non-idempotent, non-destructive, open-world. The description adds meaningful context beyond that, including that credentials are stored as a password and that the operation requires a Pro or Agency plan. It does not say what happens on duplicate connection or whether the connection is validated before success.

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

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

Three sentences, front-loaded with the core action, then the exclusion, then the plan requirement. Every sentence adds decision-relevant information and there is no repetition of schema details.

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 connection/mutation tool with no output schema, the description covers the key decision context: authentication type, the sibling alternative, 2FA implications, and plan gating. It leaves minor operational details unstated, such as duplicate handling and whether a connection test occurs, but the essential call guidance is present.

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

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

Schema description coverage is 100%, with the nested `imap` object fully documented, including example hostnames and typical ports. The description adds no parameter-level detail beyond reinforcing 'username and password', so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: connecting a mailbox over IMAP/SMTP with a username and password. It also explicitly distinguishes this tool from the sibling `email_account_oauth_url`, so an agent can route Google/Microsoft mailboxes without opening either schema.

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

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

It gives explicit when-not-to-use guidance: Google and Microsoft mailboxes should go through `email_account_oauth_url` instead, with the rationale that OAuth avoids storing a password and survives 2FA. It also states a prerequisite: 'Requires a Pro or Agency plan.'

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 is covered. The description's real addition is the 'settings as configured' framing, which tells the agent the values are a configuration snapshot rather than live metrics. It says nothing about behavior when the id is unknown or whether the record is scoped to the caller's subaccount.

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: content first, then routing to the two siblings. No filler, and the most important disambiguation is front-loaded with the field list.

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

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

With full annotations and no output schema, the description should convey return content, and it does name the primary sections. It stops short of an exhaustive field list or an error case, which is minor for a simple read-by-id 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?

Single parameter with 100% schema description coverage that already explains the id comes from email_account_list. The description adds no syntax, format or lookup guidance beyond the schema, so the high-coverage 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?

Names the resource precisely ('one mailbox') and enumerates the returned surface: sending limits, warm-up state, signature, IMAP/SMTP settings. The final clauses explicitly separate it from email_account_stats (actual sending) and email_account_update (mutation), so an agent can route without opening a schema.

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

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

Gives both when-to-use and when-not-to-use with named alternatives: use email_account_stats for what the mailbox actually sent, and email_account_update to change anything. The configuration-vs-performance distinction is the exact decision an agent needs to make here.

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

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

Annotations already declare a safe, idempotent read, so the bar is lower; the description still adds real context — multiple mailboxes allowed, sends rotate across them, and account creation is Pro-only. It doesn't mention whether results are paginated or what status/keyword filtering actually does on the returned set.

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, each doing work: resource definition, dependency, cardinality rule, creation path. Front-loaded with what the tool is; the Pro-only note is a slightly trailing detail but not 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 and full parameter documentation in the schema, the description covers the operational essentials an agent needs: why this list matters, how many to attach, and where to create new entries. It stops short of describing the shape of a returned account (id, provider, status), which would have made it complete.

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

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

Schema description coverage is 100% and the schema already explains status, userId (with the subaccount_list constraint) and keyword. The description adds nothing about parameters, 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?

Opens with a concrete resource definition — 'Mailboxes connected for email steps (Google, Microsoft or IMAP)' — so the agent knows exactly what is enumerated. It distinguishes itself from email_account_get/add_imap by implication rather than explicit contrast, keeping it short of a 5.

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

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

Gives explicit preconditions ('A campaign with an EMAIL step needs at least one attached via campaign_update → emailAccountIds'), an explicit behavioral rule ('ask the user which, do not attach all of them'), and routes to the correct siblings for creating accounts (email_account_oauth_url, email_account_add_imap). It also contrasts against the LinkedIn account case, so the agent knows why cardinality differs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safe-read semantics are covered. The description adds genuinely useful behavior: the callback is handled by the web app not MCP, the mailbox will not appear in email_account_list until the user finishes, and the plan gate. However for a closed-world read-only URL builder, these additions are contextual rather than critical gaps, so a 3 is fair.

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

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

Front-loaded with the core action, then handoff semantics, sibling preference, exclusion, and plan requirement. Every sentence supplies 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?

No output schema exists, but the description explains that returning the URL is the whole job and that the callback occurs elsewhere. For a 2-parameter read-only builder this is complete enough to invoke correctly.

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

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

Schema coverage is 100% for both parameters, including `state` and the `provider` enum. The description adds only implicit mapping (Google/Microsoft) which the enum already states, and says nothing new about `state`. 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 ("Build the Google or Microsoft consent URL for connecting a mailbox") and immediately differentiates from the sibling email_account_add_imap. An agent can identify the tool and its scope without opening the schema.

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

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

Explicitly covers when to use (Google/Microsoft preference over IMAP, no password, survives 2FA), when not to (no LinkedIn equivalent), the handoff flow (give URL to user for browser), and prerequisites (Pro or Agency plan). This is the full when/when-not/alternatives set.

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 adds that the aggregation grain is per-mailbox and enumerates the returned metric categories, which substitutes usefully for the absent output schema. It does not mention pagination, rate limits, or whether metrics are totals versus per-period series.

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, with the metric/scope definition front-loaded before the sibling disambiguation. Every clause carries information the agent needs for selection.

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

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

For a two-parameter read tool with a nested range object and no output schema, the description supplies the metric list that would otherwise be unknown, which is the main gap. Remaining minor omissions are return shape per period and whether `range` omission yields a documented default — the schema does cover the latter.

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%, including the nested `range` object with its `from`/`to`/alias fields and the backend-default behavior when omitted. The description only restates the grains ('one mailbox', 'date range') without adding format or aliasing detail. Baseline 3 applies since the schema carries the load.

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

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

The first sentence names the exact metrics (sends, opens, clicks, bounces) and the exact aggregation grain (one mailbox over a date range), so an agent knows precisely what the tool returns. The second sentence explicitly separates it from the campaign-grain sibling `analytics_campaign`. No ambiguity with `email_account_get` or `analytics_account` remains.

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