Sliq

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

Annotations only say readOnlyHint=false/destructiveHint=false. The description adds substantial behavior beyond that: new code executes on the trigger's next firing, a goal-sync obligation via update_agent must happen in the same turn, one on_enter per node limit, the paused-agent warning, and the credential/context implication that a later run doesn't see this chat.

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

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

Front-loaded with the purpose and the sibling preference, then layered detail. It is long, but for a tool with six trigger variants and cross-tool obligations every sentence is load-bearing; only mild compression is possible.

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 complex, multi-variant mutation tool with no output schema but an inline <returns> block describing success, agent_id, trigger_id, next_run_at, the trigger dict, and the paused warning. Combined with the annotations and detailed usage rules, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully extends it: the on_enter trigger's prompt holds only extra instructions while the message itself goes in message_templates, and prompts should name outside resources by the identifier the tool takes rather than by title. This is real semantic guidance 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 ('Add a trigger to an existing agent') and immediately scopes it against the sibling it is not ('Prefer this over creating a new agent'). An agent can distinguish it from create_agent, update_trigger, and define_sequence 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 explicit when-to-use (schedule follow-ups on an agent with context), when-not (prefer this over creating a new agent), the alternative for editing (use update_trigger if a node already has an on_enter), and a mandatory prerequisite (get_skill_guide('trigger_code') before writing code). Routing is unambiguous.

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

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

Annotations only declare readOnlyHint=true. The description goes far beyond that: it discloses the parallel fan-out mechanism (ThreadPoolExecutor, max 20 concurrent), the cost model (1 Sliq credit per found=True, free for found=False), soft-failure behavior on insufficient credits, the per-user 24h cache, dedup behavior, and that results are saved to canonical company entities. No contradiction with readOnlyHint—enrichment is a lookup/read operation that stores results for the user's workspace but does not modify external state in a way that violates a read-only hint. This is rich behavioral transparency that annotations alone would never provide.

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

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

The description is front-loaded with the core usage rule in the very first sentence, then layers details in a logical order: batching, endpoint, cost, caching, dedup, persistence. Every paragraph earns its place. It is long, but the length is justified by the behavioral and cost details an agent needs to avoid misuse. A 4 rather than 5 because the <returns> block is quite verbose and could be trimmed without losing essential guidance—some of the funding-stage formatting detail could live in the schema or output schema instead.

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—costing, caching, dedup, batched parallel execution, and two distinct output shapes—the description covers everything an agent needs to call it correctly and interpret results. It even explains how missing funding data affects downstream matching (matches_icp includes-on-null). There is no output schema, so the description properly carries the burden of explaining the return structure. The only minor gap is a lack of an explicit 'when not to use' list beyond person enrichment, but it names the key sibling and the coverage 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 description coverage is 100%—the single 'domains' parameter is fully described in the schema, including order preservation and duplicate collapsing. The description reinforces the batch usage ('Pass all candidate domains at once') and adds the canonicalization detail, but it doesn't need to add much beyond what the schema already states. Baseline 3 is appropriate for full schema coverage with minor descriptive reinforcement.

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: 'Enrich multiple company domains in a single call.' It clearly distinguishes this tool from siblings like find_email and enrich_linkedin_profiles by specifying org-only enrichment (company domains, not people). The phrase 'Enrich multiple company domains in a single call' is specific and action-oriented, leaving no ambiguity about what the tool does.

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

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

The description explicitly tells the agent when to use this tool: pass all candidate domains at once, one call with the full list, not one call per domain. It also names an alternative—'For person enrichment (work email, LinkedIn URL), use find_email instead'—and identifies the sibling tool by name. This gives the agent both a positive usage rule and an explicit exclusion, which is exactly what the dimension asks for.

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

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

Beyond the destructiveHint annotation, the description discloses important behaviors: writes are visible in the Apollo UI, apollo_id is ignored and can create blank contacts, accounts are deduped by domain, and the result counts are split into created/existing/saved. This substantially protects the agent from misinterpreting outcomes.

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, then confirmation, required fields, and important caveats. It is somewhat dense but every sentence conveys operational value, and the account result explanation is placed at the end where it provides useful context without burying the main usage rules.

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

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

For a mutating tool with no output schema, this description covers required inputs, common failure modes, deduplication behavior, and result semantics for accounts. The main gap is that contact-level result behavior is not described, but overall the agent has enough context to call the tool correctly and interpret responses.

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

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

The schema already covers all three parameters, but the description adds critical meaning: email is required for contacts, contacts should be passed as {first_name, last_name, email, title, organization_name}, accounts use {name, domain}, and sequence_id adds contacts to a sequence. This goes beyond the bare schema.

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

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

The description uses a specific verb ('Save') and resource ('people as contacts or companies as accounts in the user's Apollo CRM'), clearly distinguishing this write operation from enrichment/search siblings. It also specifies the two supported object types, leaving no ambiguity about what the tool does.

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

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

It explicitly requires user confirmation before calling and instructs the agent to use apollo_enrich first to get full details, which is actionable workflow guidance. It does not fully enumerate when not to use this tool versus similar CRM update tools, but the preconditions and prohibitions are clear.

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

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

Annotations only declare readOnlyHint=true, but the description adds substantial behavioral context: masked names, no LinkedIn URLs, boolean-only has_email/has_phone fields, no persistence to the Output tab, and a warning against using record_search_results. It also discloses credit costs and the org resolution round-trip for company_names, all beyond what annotations provide.

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

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

The description is dense but every sentence earns its place: purpose, cost, return limitations, persistence caveats, and sibling routing. It is front-loaded with the core purpose and immediately gives actionable usage guidance without 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 12-parameter tool with no output schema, the description covers the key operational caveats: partial/masked results, boolean-only contact fields, non-persistence to Output, the find_email escape hatch, and apollo_enrich's org-only scope. Combined with the fully documented input schema, an agent has enough context to invoke the tool correctly and interpret its 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 the input schema already documents every parameter. The description adds context around the 'type' parameter (people vs. organizations, cost differences) and high-level result limitations, but it does not need to explain individual filter parameters. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific action ('Search Apollo's database') with clear object types ('people or companies'), which distinguishes it from generic search tools. It also explicitly contrasts with apollo_enrich ('org-only and does not accept person identifiers') and find_email, helping disambiguate sibling 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?

The description gives explicit cost guidance for people vs. organization searches, instructs when to use liberally vs. deliberately, and names alternatives with their distinct roles: find_email for resolving masked previews into saved persons, and apollo_enrich for org-only enrichment. This is clear when-to-use and when-not-to-use guidance.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses significant behavior: the list is capped at 25, over-cap batches are rejected atomically via ModelRetry, replace_with atomically replaces the full list, and both learnings and replace_with batches are all-or-nothing. It also explains persistence scope (per-agent) and the return value shape. Nothing in the description contradicts 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 long but highly structured with clear sections: a summary, explicit anti-examples, valid examples, usage, and cap behavior. The core action is front-loaded in the first sentence, and every subsequent section earns its place by preventing the exact mistakes an agent would otherwise make. The formatting makes the density navigable rather than bloated.

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, cap semantics, and lack of an output schema, the description is complete: it covers valid entries, invalid entries, routing alternatives, batching atomicity, cap-rejection behavior, consolidation guidance, and return value summary. An agent has everything needed to decide whether to call it and how to structure the arguments successfully.

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?

Although schema coverage is 100%, the description adds essential semantics beyond the raw parameter names: learnings is for appending a batch, replace_with is the full-replacement path after cap consolidation, and the two are mutually exclusive. It also defines what constitutes a valid learning string (rule-of-thumb, no proper nouns/dates/per-entity data), which is crucial for correct invocation and not conveyed by 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: append agent-specific operational RULES to the agent's persistent learning list for the next run, or replace the entire list for consolidation. It sharply differentiates from sibling tools like track_prospects, update_workspace, and save_memory by explicit scoping: per-entity facts, per-run summaries, and general user preferences are excluded. The inclusion of concrete good and bad examples removes ambiguity about what the tool is for.

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

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

The description explicitly states when to append vs. replace, when to use track_prospects/update_workspace/save_memory instead, and how to handle a cap-reached ModelRetry. It also gives precise batching guidance: pass learnings=[...] for one or more entries, and use replace_with after consolidation. No inference is required to decide when this tool is appropriate.

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 indicate non-read-only and non-destructive, so the description carries the burden of explaining behavior. It adds useful context: the email must be queued, attachment IDs come from list_attachments, and the same file can be attached to multiple emails. It does not contradict annotations.

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

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

The description is compact, front-loaded with the core action, and every sentence adds value. The consent guardrail and parameter sourcing notes are included without unnecessary 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 two-parameter tool with complete schema coverage, the description provides enough context to invoke it correctly: when to attach, what target emails qualify, and where the attachment ID comes from. It does not describe error behavior or the result of attaching to a non-queued email, but those gaps are minor.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description slightly enriches recipient_email by clarifying the email must be pending or awaiting approval and attachment_id by tying it to list_attachments, but most parameter meaning is already in 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 action — attaching a file from the user's library to a queued outreach email — and clearly distinguishes this from sibling tools like detach_from_outreach or get_email_attachment. The verb, resource, and target are all explicit.

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

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

The description gives strong usage guidance: only attach when the user explicitly asks, never on the tool's own initiative, and only to queued emails (pending or awaiting approval). It does not explicitly name an alternative tool for the opposite operation, such as detach_from_outreach, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful context: daily caps are per mailbox/from-address rather than per user, and an empty mailboxes list means no account is connected. This goes beyond the annotation and clarifies interpretation of 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 summary is front-loaded with purpose and timing, followed by two concise operational notes. The returns block is structured and compact. Every sentence adds decision-relevant value without redundancy.

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

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

With no output schema, the description fully documents the return structure, including queue fields and optional next_send. It also explains how to interpret empty results and what action to take. Combined with a read-only annotation, this is complete for safe, correct invocation.

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

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

The tool has zero parameters and no input schema burden, so there is nothing for the description to add. The description instead clarifies the output's mailboxes field, which is the relevant semantic content 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?

Description opens with a specific verb and resource: 'Check per-mailbox email outreach usage limits and queue status.' It clearly identifies email-specific mailboxes and queue, distinguishing it from check_linkedin_daily_usage and other usage tools without ambiguity.

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

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

Explicitly states when to call: 'Call this before queuing bulk email outreach.' It also gives actionable guidance for an empty mailboxes list. It does not explicitly name alternative tools or when not to use it, but the context is clear enough.

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

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

Beyond the readOnlyHint annotation, the description discloses that in-context figures go stale after queueing or approving sends, making a re-call necessary. It also explains the return value's configurable_limits semantics (default, ceiling, custom cap, and that None means using the default), adding 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?

The description is front-loaded with the core purpose, followed by concrete when-to-use guidance and a structured returns section. Each sentence earns its place; there is no fluff or repetition of schema/annotation data.

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 tool with no output schema, the description is complete: it states what the tool does, when to call it, when to call it again, what the return contains, and which sibling covers per-contact queue details. Nothing essential is missing.

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

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

The tool has zero parameters and the schema description coverage is 100%, so there are no parameter semantics to explain. The baseline for zero-parameter tools is 4; the description adds no unnecessary parameter information.

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

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

The description opens with a specific verb and resource: 'Check LinkedIn usage limits and invite queue counts.' It clearly distinguishes itself from the sibling check_email_daily_usage (email usage) and explicitly scopes out manage_linkedin_invite_queue's per-contact queue status, so an agent can tell which tool is which.

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

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

Usage guidance is explicit: call before sending multiple LinkedIn messages/InMails/connection requests to get a fresh read, and re-call after queueing or approving sends because prior figures become out of date. It also names the exact alternative (manage_linkedin_invite_queue with action='status') for per-contact queue details.

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, which is sparse. The description goes far beyond by disclosing that classification runs in the background, results are not immediate, credits are charged at a flat per-message rate, the return provides exact count and cost, and the run is blocked if balance is insufficient. It also clarifies that a run never charges more than balance and that blocked runs are reported in the return. This is comprehensive behavioral transparency.

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

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

The description is well-structured with a <summary> and <returns> section, front-loading the purpose and then detailing behavior, cost, and return format. It is a bit lengthy but every sentence carries information; no redundancy. The structure makes it scannable and easy to parse for an agent.

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

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

The tool has no output schema, but the description's <returns> section explicitly details both enqueued and blocked return dicts with exact keys. It covers cost implications, async behavior, filtering options, and points to result-reading tools. It also handles the edge case of insufficient credits. For a complex background operation, this is exceptionally complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds semantic context for force (re-tag after editing), channel (narrows to LinkedIn/email), and sent_after (only messages on/after instant). It reinforces the default behavior and clarifies the effect of each filter beyond the schema's literal definitions. However, it does not mention agent_ids at all, leaving that to the schema (which is adequate). Overall, it adds meaningful value.

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

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

The description opens with a clear purpose: "Kick off classification of the group's in-scope sent messages, in the background." It specifies the resource (sent messages for a group), the action (classify), and the async nature. It also distinguishes itself from sibling tools such as estimate_message_tag_classify_scope (which estimates scope) and get_message_tag_rates (which reads results), and its scope definition via criteria (channel, campaigns, positions, teammates) makes it unambiguous.

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

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

The description states when to use the default (incremental catch-up of unclassified messages) and when to use force=True (re-tag after editing group/tags). It also explains filters (channel, sent_after) and how to retrieve results afterward with get_message_tag_rates / query_tagged_messages. However, it does not explicitly mention the alternative cost-estimation sibling (estimate_message_tag_classify_scope) as a pre-check, though usage is strongly 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 only declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new behavioral context: it is asynchronous (~15 min tagging delay), costs credits at a flat per-person rate, never charges more than the balance, and is simply not enqueued when the balance is insufficient.

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 summary sentence followed by usage, cost, and return semantics, each earning its place. No redundant restatement of the name 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?

Even with no output schema, the description documents the return shape for both enqueued and blocked outcomes, the credit/balance semantics, and the async nature. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning over the schema: without force only not-yet-classified people are processed, while force triggers a full re-tag after editing the group or its tags. This clarifies the practical effect of the flag.

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+resource: 'Kick off classification of the group's in-scope canonical people, in the background.' It also defines scope (campaigns and teammates) and distinguishes itself from the sibling classify_message_tag_group and the read-side get_segment_rates / query_segment_people.

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

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

Explicit when-to-use: 'call this right after creating a group to tag the people already there now, or with force=True to re-classify everyone.' It also says results are not immediate and directs the agent to get_segment_rates / query_segment_people afterward, and to relay blocked runs.

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, but the description adds substantial behavior: the correction REPLACES existing tags, recomputes group rates and message views immediately without re-classification, and persists past later re-tags so newly-added tags are not applied. These are non-obvious traits an agent must know.

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 prose is dense and front-loaded, leading with the core purpose before prerequisites and edge cases. It runs long, but nearly every sentence (persistence, recompute, empty-list clearing) carries actionable meaning, so little is wasted.

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

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

For a 4-required-param mutation tool with no output schema, the description covers identifiers, tag semantics, side effects, persistence, and even an inline returns block describing the confirmation dict — leaving nothing an agent needs missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics beyond the schema: a single-tag comparison accepts at most one tag id and an empty list clears to 'No match'. It also reinforces that tag ids must come from the group's tags, tying parameters to the workflow.

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 — setting or correcting tags on one sent message within a tag group — and immediately scopes it as the 'human-set override' for a single (group, message), distinguishing it from sibling bulk classifiers like classify_message_tag_group.

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 trigger conditions ('when the classifier got it wrong or skipped it') and names the sibling tools to source the required identifiers from (list_sent_messages, query_tagged_messages, list_message_tag_groups). It also states behavior for the edge case of clearing to 'No match'.

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 (write-capable, non-destructive), the description discloses the tool's directional stage effects, explains the not_interested stage semantics and its funnel treatment, and explicitly notes it can lower or raise stages. This is substantive behavioral context that annotations alone do not provide.

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

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

The description is long but densely informative, with a clear front-loaded summary and structured sections. Every sentence adds decision-relevant detail, and the return format is neatly separated. No filler or repetition of schema content.

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 moderate complexity, the fully documented schema, and the rich description, an agent has everything needed to select and invoke it correctly. It covers the alternative tool, parameter semantics, message_id sourcing, and return value shape despite no output schema.

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

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

Schema coverage is 100%, so the schema already documents the three parameters well. The description adds non-obvious semantic value by explaining what outcome='not_interested' does to the prospect's stage and how it is counted in the funnel, plus how to obtain message_id from message-search tools.

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+resource: re-judge one inbound reply's outcome and re-derive the prospect's stage. It clearly differentiates the tool from sibling update_prospect by noting that this tool moves the stage in either direction while update_prospect only raises. The scope is unambiguous.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use it to correct false positives/under-called replies, and reach for update_prospect when marking a rung with no reply behind it. It also names the lookup tools for finding message_id, leaving the agent with a clear decision path.

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 readOnlyHint=false and destructiveHint=false, the description still clearly discloses that this replaces a person's tags, that an empty list clears to 'No match', that rates/people views recompute immediately, and that the override persists across re-tags. This is rich behavioral context beyond what the annotations provide.

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

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

The summary is front-loaded with the purpose, then follows with identity/the ID sources, parameter constraints, side effects, and persistence. Every sentence adds operational value, and the returns section is compact and 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 persistent, state-changing override with no output schema, the description is thorough: it explains the return value, the empty-list clearing behavior, immediate recomputation, and the fact that a later re-tag will not overwrite the correction. Nothing needed to call it correctly appears to be 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 input schema already has 100% description coverageasiatic. The description largely restates the tag_ids semantics and the sources for group_id/person_id, adding only minor workflow guidance about identifying the person first and passing corrected tag ids from the group's tags.

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: it corrects/replaces the tags on one person for a segment group when the classifier is wrong. It distinguishes itself from message-classification and reply-outcome correction siblings by scoping to 'one person' and 'segment group' tags.

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: use this as the human-set override when the classifier got a person's tags wrongging. It also names the source queries for person_id and explains constraints for single-tag groups states an explicit when-condition but does not name alternatives like classify_segment_group or correct_message_classification.

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 provide almost no coverage (readOnlyHint=false, destructiveHint=false are defaults), so the description carries the full burden. It discloses important behavioral traits: code runs on the trigger's next firing, template_id runs template setup and incomplete seeding leaves the agent unwired, and get_skill_guide('trigger_code') is a mandatory prerequisite. This is substantial behavioral context beyond the schema.

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

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

The description is structured into short, purposeful paragraphs, each carrying a distinct decision or rule: purpose, exclusion, template wiring, and the code prerequisite. The most important scoping statement is front-loaded, and every sentence earns its place; nothing is redundant 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?

Given the tool's complexity — multiple trigger types, template wiring, and the need to reference an external skill guide — the description covers the critical decisions needed to call the tool correctly. The input schema provides the detailed trigger shapes, and the description supplies the inter-field relationships and mandatory prerequisites that the schema cannot express. No return-value explanation is needed for a creation tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining template_id behavior, the dependency between template_id and workspace.inputs, and the required get_skill_guide call before writing trigger code. It doesn't deeply expand every parameter, but it meaningfully supplements the schema.

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

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

States a specific verb and resource: 'Create a background agent that runs automatically based on triggers.' The opening sentence conveys exactly what the tool produces, and the second paragraph explicitly distinguishes it from add_trigger, so an agent can tell it apart from the most relevant sibling without ambiguity.

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

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

Gives explicit when-not-to-use guidance: 'Do NOT create a new agent for follow-ups, event handlers, or scheduled checks that continue an existing agent's work — use add_trigger on that agent instead.' It also provides template-selection rules, when to omit template_id, and when workspace.inputs must be seeded. This is direct, actionable 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 (readOnlyHint=false, destructiveHint=true) already establish this is a mutating write, and the description does not contradict them. It adds genuinely useful behavioral context beyond the annotations: a video link is auto-included unless in_person is true, and user confirmation is mandatory before invocation. No contradiction detected.

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

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

The description is compact, front-loaded with the core purpose, and structured with <summary> and <returns> tags. Every sentence earns its place — the confirmation requirement and attendee-lookup routing are operationally necessary, not filler. Slight deduction for the returns clause being thin, though that is more a completeness than a conciseness issue.

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?

Operational context is strong: confirmation protocol, provider ambiguity handling, and attendee lookup are covered. However, there is no output schema, and the returns section only says 'Dict with success status and event details' without specifying keys, error cases, or the shape of the created event — a notable gap for an 8-parameter creation tool with no structured return definition.

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 all 8 parameters in detail, including unusually rich guidance on in_person and provider. The description's prose adds only the in_person/video-link linkage, which is a modest supplement; the baseline of 3 is correct since the schema carries the parameter-semantics burden.

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

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

States a specific verb and resource ('Create a calendar event') with clear scope ('user's connected calendar (Outlook or Google)'). The video-meeting-link behavior further disambiguates it from siblings like update_calendar_event, create_task, and create_todo, so an agent can select it correctly without opening the schema.

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

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

Gives an explicit gate for when to call the tool ('ALWAYS present the event details to the user and ask for explicit confirmation before calling') and explicit alternative routing for attendee discovery ('Use search_emails or search_calendar... use find_email'). This is actionable, conditional guidance rather than implied usage.

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

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

Annotations only indicate it is a non-read, non-destructive operation mirroring a create. The description adds meaningful behavior beyond annotations: the task is visible on the team-wide Tasks view, can stand alone or link to a person/company/deal, and will not send a due-date notification.

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

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

Well-structured with a summary and return section, front-loading the core action and purpose. Every sentence adds value-the examples, link behavior, team visibility, and no-alarm caveat are all useful and no redundant filler exists.

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

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

For a 7-parameter create tool with no output schema, the description provides the essential return shape ('same shape as query_crm_tasks row'), clarifies visibility, linking options, and due-date behavior. The schema covers parameter syntax, so nothing needed for a correct call is missing.

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

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

The input schema already covers 100% of parameters with helpful descriptions, so the description does not need to re-explain semantics. It adds context about linking to people/companies/deals and the return shape, but these are minor complements to a fully-documented schema.

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

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

The description clearly states it creates a task (a to-do) in the user's CRM-has a specific verb, resource, and scope. It distinguishes itself from siblings like create_calendar_event and update_crm_task by emphasizing CRM task semantics and linking to deals/people/companies.

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 use cases ('remind me to send pricing to Jane on Friday') and explicitly warns that this is not an alarm, telling the agent to communicate that limitation. It does not name alternative tools explicitly, but the context and examples make when-to-use reasonably clear.

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

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

Annotations only say readOnlyHint=false and destructiveHint=false, so the description carries the burden of disclosing side effects. It adds valuable behavioral details: the created deal appears on the Deals view for the whole team, creation requires a person or company, and the tool refuses duplicate open deals while naming the existing deal. This goes well beyond the annotations and the schema's individual field descriptions.

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

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

The description is compact and front-loaded: purpose and team visibility come first, then the linking/creation logic and duplicate policy, then the return shape. Every sentence contributes either to selecting the tool, passing parameters correctly, or understanding the result. No filler or redundant restatement of 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 11-parameter creation tool with no output schema and minimal annotations, the description covers the essential context: core semantics, duplicate handling, link-vs-new patterns, and return shape ('same shape as a query_deals row'). It could be more complete by describing the created deal row fields or permission requirements, but it points to query_deals for the shape and the schema handles per-parameter defaults.

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 baseline is 3. The description adds cross-parameter semantics not obvious from the schema: 'A deal needs a person or a company (or both)', and explains when to use person_id/company_id versus new_person/new_company. It also gives meaning to allow_duplicate by tying it to the refusal behavior. This is meaningful added value 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?

Description opens with a specific verb and resource ('Create a deal in the user's CRM pipeline') and clarifies this is how a person or company enters the CRM. It differentiates from the sibling update_deal by explicitly saying to 'update that deal instead' when a duplicate open deal exists. An agent can confidently distinguish create_deal from query_deals and update_deal.

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?

Description gives explicit when-to-use: 'this is how a person or company gets into the CRM.' It also provides clear alternatives: link existing people/companies via query_people/query_companies, or pass new_person/new_company; and if an open deal exists, 'update that deal instead, unless the user wants a second one (then pass allow_duplicate=true).' This leaves no ambiguity about when to call this tool versus update_deal.

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 key behavioral nuance that creating a group does not classify anything and that tag descriptions are read by the classifier. It also discloses the return shape. No contradiction with annotations.

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

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

The summary is front-loaded with the core purpose, then gives mode guidance, tag guidance, and the follow-up in tight prose; the return format is cleanly separated. No filler or 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 5-parameter creation tool with no output schema, the description covers the essential semantics (mode, tag descriptions, no classification side effect, follow-up) and supplies the return dict. Criteria is left to the already-detailed schema, which is acceptable given 100% 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%, so the baseline is 3, but the description adds real meaning for mode (mutually exclusive vs several tags with concrete examples) and for tag descriptions (the classifier reads them). It does not elaborate on criteria, but the schema already documents that 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?

Opens with a specific verb and resource ('Create a message tag group') and defines it as 'a dimension to classify sent outreach along,' which clearly separates it from segment-group creation and from classification itself. The summary also names the follow-up classify_message_tag_group, reinforcing what this tool uniquely does.

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 concrete mode-selection guidance (single for mutually exclusive tags, multi for several per message) and explicitly states that creating a group does not classify anything, directing the agent to follow with classify_message_tag_group. It does not spell out when to prefer update_message_tag_group or list_message_tag_groups, so it stops short of full when-not/alternatives coverage.

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

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

Goes well beyond the readOnlyHint=false/destructiveHint=false annotations by disclosing the real costs and commitments: every person in scope gets tagged, at a per-person credit charge, within ~15 minutes of LinkedIn lookup or first contact. It also explains that the classifier reads tag descriptions and the person's profile, which is exactly the behavioral context an agent needs before committing.

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 mode decision, then cost/latency, then the follow-up call. The <returns> block is somewhat verbose for a dict shape, but every sentence otherwise earns its place.

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

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

With no output schema, the returns block supplies the response shape (id, name, mode, criteria, tags), and the combination of mode semantics, cost, timing, and follow-up tool makes the description sufficient to call this mutation safely and completely.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds genuine meaning: it explains why a tag description matters ("the classifier reads it, and reads the person's profile") and frames mode semantically, not just enumeratively. The criteria/scope caveats largely mirror the schema text, so it is not fully 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+resource and immediately defines the domain concept ("a dimension to classify your canonical people along") plus what it creates alongside it (its tags). An agent can distinguish this from sibling group tools like create_message_tag_group or classify_segment_group 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 explicit guidance for choosing between `single` and `multi` mode with concrete examples (seniority vs traits), and names the follow-up tool (classify_segment_group) for tagging people already in scope. It lacks explicit when-not-to-use guidance versus the message-tag-group siblings, but the operational context is clear.

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

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

Annotations only declare readOnlyHint=false / destructiveHint=false; the description adds substantial behavior beyond that — re-authoring replaces the prior sequence, dropped-node prospects return under off_sequence_nodes, on_enter rows are reconciled/deleted per kept-or-dropped node, and minted-default code is regenerated only if unedited. That said, it does not call out auth/permission requirements or rate limits, and 'replace the prior sequence' with per-node row deletion sits somewhat uneasily with destructiveHint=false (though prospects are explicitly preserved).

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

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

It is front-loaded with the purpose and core derivation rule before the per-kind reference, and nearly every sentence carries operational detail. It is nonetheless very long for a description and repeats some rules (the business-day `d` default is stated more than once, as is the message_templates-holds-the-message rule), so it is dense but not maximally tight.

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 where results surface (templates 'come back on get_campaign_flow', experiments on get_message_experiments) and covers enrollment side effects, re-authoring reconciliation, and structural validation constraints — everything an agent needs to author the DAG 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%, but the description goes far beyond it, defining the semantics, defaults, and interaction rules for nearly every field: the `entry.after` vs bare advance distinction, business-day `d` vs calendar `cd` units, `message_templates` as an input-only A/B list including `['', note]`, decision arms requiring non-blank cases, and where a step's message belongs (message_templates vs on_enter prompt vs workspace.inputs).

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 states a specific verb+resource ('Author (or replace) the campaign's flow sequence — a DAG of outreach nodes') and immediately frames the grammar as the schema. It is clearly distinguishable from siblings like update_node (single node), get_campaign_flow (read), and the setup_*_sequence 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?

It gives explicit selection rules across alternatives: manual vs automation vs action/send ('Use `manual` ONLY when a human must act... an automatable side-effect is an `automation` node'), when to use a decision vs chained decisions, how to run a second channel (via a held advance, not a second start), and a pre-condition to confirm with the user before enrolling an existing prospect backlog.

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

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

Annotations already mark destructiveHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations: the record is retained internally for a short window, the agent stops running, and confirmation is mandatory. This helps the agent understand recoverability and side effects.

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 and front-loaded: it opens with the core action, immediately states the behavioral consequences, and places the critical confirmation requirement before the return note. No filler or redundant restatement.

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 tool, the description is complete: it covers the effect, the retention behavior, the user-confirmation requirement, and the return type. There is no output schema, but the return description ('Dict with success status') suffices for this simple operation.

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

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

The input schema has 100% coverage with a single parameter, agent_id, already described as 'ID of the agent to delete.' The prose adds no further semantic detail, so the schema carries the burden; 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 ('Delete an agent') and explains the observable consequences: the user stops seeing it and it stops running. This clearly distinguishes it from sibling tools like create_agent, update_agent, and get_agent_details.

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?

Includes an explicit operational guardrail: 'ALWAYS confirm with the user before calling this,' which tells the agent when not to invoke it casually. It does not name alternatives or exclusion cases, such as using update_agent instead for non-destructive changes, so it misses a top score.

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

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

With destructiveHint=true and readOnlyHint=false already in the annotations, the description goes beyond by disclosing that the operation is 'Irreversible' and that the deletion cascades to the tag's classifications, not just the tag record itself. It also clarifies the scope boundary ('The rest of the group is untouched'), which is valuable behavioral context beyond the annotation flags. No contradiction with annotations.

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

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

The summary is three tight, high-information clauses: the action, the irreversibility warning, and the scope boundary. The optional returns block is a compact dict example. No filler or repetition; every sentence earns its place.

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

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

For a one-parameter destructive tool, the description is nearly complete: the parameter is fully documented in the schema, the return value is specified as a confirmation dict, and the destructive/irreversible nature and cascade scope are explicit. Minor omissions like permission requirements or implications for messages bearing the tag are not material here, so this is close to 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% — tag_id is described as 'The tag to delete (from a group's tags list).' The tool description adds no additional parameter-level semantics beyond echoing the schema. Baseline 3 is appropriate since the schema fully carries the 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 uses a specific verb and resource: 'Delete a tag and its classifications.' It explicitly distinguishes itself from the nearest sibling, delete_message_tag_group, by adding 'The rest of the group is untouched,' so an agent can tell this deletes a single tag while preserving the group. This is a clear, differentiating statement of purpose.

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

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

The description implies when to use this tool — when you want to remove an individual tag (plus its classifications) but keep the rest of the message tag group — through the phrase 'The rest of the group is untouched.' However, it never names the alternative (delete_message_tag_group) explicitly nor gives a when-not-to-use condition, so the routing guidance is implied rather than stated.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context beyond the annotations: the operation is irreversible and cascades to delete all tags and classifications in the group. This directly informs the agent about the full destructive scope.

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 and front-loaded: the summary states the action and its scope in one sentence, and the returns section concisely specifies the confirmation dict. Every sentence earns its place with no redundancy or filler.

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

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

For a simple destructive tool with one required parameter, the description is complete: it covers the action, the cascade effect, irreversibility, and the return shape. The schema and annotations cover parameter constraints and safety profile, leaving no critical information 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 schema has 100% coverage for the only parameter, group_id, and already explains that it identifies the tag group from list_message_tag_groups. The description does not add additional parameter-level meaning, so a baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Delete') and a clear resource ('a tag group') and further clarifies scope by stating that all associated tags and classifications are deleted. This distinguishes it from siblings like delete_message_tag and update_message_tag_group without ambiguity.

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

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

The description clearly implies when to use this tool—when an entire tag group and its associated tags/classifications need to be removed. However, it never explicitly names alternative tools like delete_message_tag for single-tag deletion or states when not to use this tool, leaving the guidance implicit rather than 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 destructiveHint=true, and the description adds specificity beyond that: 'Irreversible' and the cascading deletion of 'all its tags and classifications'. This tells the agent exactly what will be destroyed, which is valuable beyond the annotation.

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 extremely compact: a summary sentence states the action, scope, and irreversibility, followed by a minimal returns block. No fluff, and the critical warning 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?

With one parameter, full schema coverage, a clear destructive annotation, and the description covering scope, irreversibility, and the return value, nothing essential is missing. The returns block even specifies the confirmation payload format.

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%: the group_id parameter is described as 'The segment group to delete (from list_segment_groups).' The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb ('Delete') and resource ('a segment group'), and clarifies it also removes 'all its tags and classifications', distinguishing it from sibling tools like delete_segment_tag. The 'Irreversible' warning adds meaningful scope. This is unambiguous and differentiated.

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

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

The description gives clear context that this tool is for deleting the whole group and its contents, not just a tag or classification. It does not explicitly name alternatives such as delete_segment_tag for partial deletion, but the scope is evident from the cascade description.

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 indicate destructive behavior, and the description adds meaningful detail: the deletion is irreversible, classifications are removed, and the rest of the group is unaffected. This goes beyond the annotation hints.

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

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

The summary is two short sentences with no filler, and the return value is provided in a separate compact block. Key facts—irreversibility and scope—are front-loaded.

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

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

For a single-parameter delete action, the description covers the action, irreversible nature, scope, and return format. Combined with annotations and full schema coverage, nothing essential is missing.

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

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

Schema description coverage is 100% and tag_id is clearly documented as 'The tag to delete (from a group's tags list).' The description itself adds no extra parameter details, 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 states a specific verb and resource: 'Delete a segment tag and its classifications.' It also clarifies the scope by noting the rest of the group is untouched, which distinguishes it from group-level deletion 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?

The description gives useful scope context but does not explicitly state when to choose this tool over alternatives like delete_segment_group or update_segment_tag. The usage is implied by the description, not spelled out.

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

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

With annotations only declaring readOnlyHint=false and destructiveHint=false, the description adds meaningful behavioral detail: it specifies that the operation only applies to queued outreach emails and that the attachment id comes from a queue status read. This goes beyond the annotations and clarifies the operational scope without contradicting them.

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

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

The description is compact and front-loaded with the core action. Every sentence adds value: the first states the purpose, and the second clarifies targeting constraints and parameter sourcing without repetition.

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

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

For a simple two-parameter tool with no output schema, the description covers the action, the applicable email state, and how to obtain both parameter values. It could have mentioned what happens to the file after removal (e.g., whether it is deleted or just detached), but the essential context for invoking the tool 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?

The input schema already documents both parameters with 100% coverage. The description enhances this by explaining that recipient_email targets a queued email and that id is the attachment's id as shown in the queue status read, which gives the agent a precise way to source the required values.

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

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

The description opens with a specific action and resource: 'Remove a file already attached to a queued outreach email.' It clearly distinguishes this from related tools by noting 'Email queue only, mirroring attach_to_outreach,' so an agent can tell it apart from broader outreach management 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?

The description explains the target state ('queued email (pending or awaiting approval)') and references the companion tool attach_to_outreach, giving clear context for when this tool applies. It does not explicitly list exclusions or alternative tools for non-queued attachments, but enough guidance is 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 declare readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate safety. The description adds valuable behavioral context: it creates a draft (not sending), routes automatically by provider, and requires user confirmation before sending. It also discloses that the draft is created in the connected mailbox. The only minor gap is not detailing what happens on failure or whether drafts are saved to drafts folder, but the core behavior is well covered.

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

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

The description is compact and front-loaded with the core purpose. The summary section is two sentences, and the returns section is one line. It avoids redundancy with the schema. The only slight inefficiency is the parenthetical provider list, but it's useful context. Overall it earns its place without bloat.

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 tool with 100% schema coverage and no output schema, the description covers the essential context: what it does, provider routing, confirmation requirement, and email-finding alternatives. The returns section describes the output shape (success, draft_id, provider, draft details). The only missing piece is explicit error-handling or edge-case behavior (e.g., invalid recipient), but the schema's detailed parameter docs compensate. This is complete enough for an agent 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 description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds value by explaining the 'to' parameter must always be a list of dicts, and the body parameter's Markdown rendering behavior. The schema itself is exceptionally detailed (including examples and rationale for optional name), so the description doesn't need to repeat that. The description's mention of provider routing and confirmation flow complements the schema's parameter docs.

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

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

The description clearly states the tool creates a new email draft in the user's connected email account, names the supported providers (Gmail, Outlook, Superhuman), and notes automatic routing. It distinguishes itself from send_email by explicitly instructing to ask for confirmation before calling send_email, and from draft_reply by focusing on new drafts rather than replies. The verb 'create' and resource 'email draft' are specific and unambiguous.

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

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

The description provides explicit when-to-use guidance: it tells the agent to always present draft details and ask for confirmation before calling send_email, and it names alternatives for finding email addresses (search_emails, search_linkedin_message_history, find_email). This is strong routing guidance that helps the agent decide when to use this tool versus siblings.

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

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

Annotations are minimal, so the description carries the burden. It adds meaningful behavioral context beyond annotations: the draft is created but must be confirmed before sending, and it discloses the return shape (success, draft_id, provider, original email context). It does not fully describe side effects like mailbox persistence, but the core behavior is transparent.

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

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

The description is compact and front-loaded: the action, target, and provider are in the first sentence, followed by the prerequisite workflow and safety rule. The <summary>/<returns> structure is clean and every sentence contributes.

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 no output schema, the description helpfully names the returned fields and gives the essential call sequence. It is complete enough for an agent to invoke correctly, though it could add a bit more about when the draft is actually persisted and what happens if the email_id is invalid.

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 all six parameters in detail, including examples and edge cases. The description adds little parameter-level meaning beyond telling the agent to pass the email id from search_emails, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource: "Create a reply draft to an existing email thread (Outlook or Gmail)." It clearly scopes the tool to replying to existing emails, distinguishing it from a general compose flow, and the workflow reference to send_email reinforces its role.

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 usage context: use search_emails first, pass the resulting id, and always present the draft for confirmation before send_email. This clearly positions the tool in the reply workflow, though it does not explicitly state when not to use it (e.g., for new emails) or name draft_email as an alternative.

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

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

The description goes well beyond the readOnly/destructive annotations, explaining incrementality, swap semantics, URL/slug collapsing, no-op re-adds, next-scheduled-run timing, and the billing pitfall of re-echoing a dropped URL. This is rich behavioral context that an agent needs to use the tool safely and correctly.

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

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

The description is well-structured with a summary, behavior details, usage routing, and a returns block. Every sentence carries information; none is filler. The most decision-relevant facts (incremental edits, which tool to choose) are front-loaded.

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

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

For a five-parameter tool with no output schema, the description is complete: it documents the return dict's fields, the operational timing, the deduplication behavior, and the sibling tool's role. An agent has everything needed to invoke this tool correctly and to decide when not to.

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

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

The input schema already covers all five parameters at 100%, which earns the baseline 3. The description adds meaningful semantic detail for add/remove: they accept full URLs or vanity slugs, a swap is one call, and duplicate forms collapse to one member. These semantics genuinely help parameter construction beyond the schema alone.

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

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

The description uses a specific verb phrase ('Add and/or remove watched people') tied to a precise resource ('existing list-mode LinkedIn monitor'), and immediately distinguishes itself from setup_linkedin_monitoring. An agent can tell exactly what this tool does and what it is not.

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

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

The description is explicit about when to use this tool instead of setup_linkedin_monitoring, gives concrete user-intent examples ('also watch Bob', 'drop Alice'), and states which cases belong to the alternative tool (changing schedule/voice/action flags, first members, resetting the list). This leaves no ambiguity about routing.

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

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

Annotations only declare readOnlyHint, so the description carries the rest and does so richly: 0.1 credits per profile returned, misses free, 24h cache, the 0.05 company-domain lookup, the 500-profile approval threshold, background-run behavior, and the 50KB direct-return truncation that still charges for unreturned rows.

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?

Long but well-organized with summary/returns sections and front-loaded purpose. A few passages (cost restatement, repeat of the batching point) could be trimmed, but nearly every sentence carries operational weight for a paid, batch-limited 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 cost/approval gating, invocation strategy, caching, failure modes, and even return-shape caveats (unsorted experience, sparse dates, 'Present' end dates). With no output schema, the embedded returns description fills that gap thoroughly.

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 the single `linkedin_urls` param, so the schema already documents accepted forms and the 1000 cap. The description reinforces the mixed identifier types and stresses passing the whole list in one call, adding light value 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+resource (bulk LinkedIn profile enrichment) and enumerates exactly what fields come back (headline, title, company, location, connection/follower count, employment and education history). It distinguishes itself from sibling lookups by naming `setup_linkedin_sequence(action_type='resolve')` for the connection-status case it cannot cover.

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 (questions about a list of people — filtering by connection count or seniority, labelling employers, career-history questions), when-not (connection status, network distance, shared connections), and alternative selection (prefer over per-person lookups; use run_code rather than a direct call except for a handful of profiles).

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

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

Annotations already indicate this is not read-only and not destructive. The description adds meaningful behavioral context: Sliq automatically stamps the user, surface, and agent, and the summary is read by a teammate with no other context. This helps the agent understand downstream consequences and how to write the summary.

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-loaded with the core purpose. Every sentence contributes: the trigger condition, the guidance to escalate rather than change topic, the auto-stamping behavior, and summary content instructions. The returns section is brief and 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 simple two-parameter tool, the description fully covers when to use it, what to write, what happens after, and what the return value looks like. Even without an output schema, the returns note gives the agent enough to know what to expect.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by specifying what the summary should contain ('what the user wanted, what went wrong, and what you already tried'), which goes beyond the schema's 'plain-text description' and improves the agent's ability to fill the parameter correctly.

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

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

The description states a specific action ('Flag a problem to the Sliq team') and a clear trigger condition ('when you're stuck and a human should step in — something you can't resolve'). It clearly distinguishes this from ordinary problem-solving by requiring that the agent has already tried its own 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?

Provides explicit when-to-use guidance: after trying and failing to resolve with own tools. It also says to prefer this over switching subject or channel. It doesn't name specific sibling alternatives, but the boundary between escalation and normal resolution is clear.

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

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

Annotations already mark this read-only; the description adds further behavioral clarity with 'Nothing is created or charged' and 'as in a real run.' It also clarifies the estimate-versus-exact distinction. No contradiction with annotations exists.

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

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

The description is compact, front-loaded with the core purpose, and organized with a summary and returns section. Every sentence earns its place, and there is no redundant filler.

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

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

For a no-output-schema tool with full parameter documentation, the description supplies the return dict shape, the cost-estimation purpose, the no-side-effect guarantee, and the sibling tool for post-creation usage. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents all five parameters. The description's mention of 'conversation positions' restates the positions parameter but adds no new meaning beyond the schema's detailed definitions.

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

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

The description opens with a specific verb and object: 'Quote the first classify run of a message tag group that doesn't exist yet' and names the concrete outputs (sent-message count and credited charges). It also distinguishes itself from classify_message_tag_group by noting the latter is for existing groups.

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

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

The description explicitly states when to use it: 'Use it to tell the user the cost before creating the group.' It also tells the agent when to switch to classify_message_tag_group: 'once the group exists.' This gives clear routing guidance with no inference 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 readOnlyHint annotation is reinforced by the explicit statement 'Nothing is created or charged,' and the description adds the important nuance that this is an estimate, not the exact run figure. This goes beyond the annotation by clarifying the no-side-effect scope and the estimate-vs-exact distinction.

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

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

The description is compact and front-loaded with the core purpose, followed by usage guidance and the return contract. The phrasing 'Quote the first classify run' is slightly awkward, but every sentence adds value and the returns section is appropriately included given there is no output 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?

The definition covers purpose, when to use it versus the sibling, the no-side-effect guarantee, and the return shape in the returns block. Since there is no output schema, including the returned keys is essential, and this description fills that gap completely for an estimate 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 itself already documents both parameters. The description adds context about campaigns the segment would track, but it does not need to repeat parameter details; the baseline of 3 applies because the schema carries the semantic 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 description states a specific verb and resource: 'Quote the first classify run of a segment group that doesn't exist yet' and clarifies it returns a people count and credit estimate. It also distinguishes itself from classify_segment_group by noting that the sibling returns the exact figure once the group exists.

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

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

Usage is explicit: use it to tell the user the cost before creating the group, and once the group exists use classify_segment_group instead. This names the exact alternative and the condition that selects between them, leaving no ambiguity.

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

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

The annotations provide only readOnlyHint=true, so the description carries the entire behavioral disclosure burden — and it over-delivers. It reveals the two-provider routing (identifier-pinned database vs name-matched fallback), the profile-snapshot staleness (~weekly refresh), the near-namesake failure mode ('Acme' admitting 'Acme Robotics'), the reject/rejected contract, retry-on-5xx behavior, the 5-concurrent fan-out limit, and the Sliq credit cost including the empty-result-still-charges and insufficient-credit soft-fail. It even discloses that persistence (saving rows) is the default side effect, which sits alongside a readOnlyHint annotation. The description is consistent with the annotation and adds rich context on top of it — no contradiction.

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

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

This is a wall of prose running to well over a thousand words split across summary and returns sections, far beyond what an agent needs to invoke the tool correctly. While nearly every sentence carries real information, there is redundancy: the Acme/Acmely near-namesake example appears both in the main description and again in the company parameter comment, and the provider-routing explanation is revisited in multiple places. It is front-loaded (purpose, then usage, then details) but not appropriately sized — the density genuinely impedes quick parsing for an agent spending tokens on every 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?

With no output schema and an unusually complex tool (batched searches, two providers, identifier pinning, reject reasons, cost, concurrency, stale data), the description is exceptionally complete. The returns section documents the per-slot success and error shapes, the identifier-pinned variant's missing score/order/seniority fields, the InsufficientCreditsError refusal, and the overflow-error retry path. Nothing an agent needs to call this correctly and interpret its output 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 every parameter already has an unusually detailed schema comment (query's POSITIVE-FORM warning, titles OR-ed substring semantics with 'VP'/'Vice President' examples, company's 'Acmely' near-namesake filtering, persist's save-vs-fold behavior). The description's marginal adds — the provider-pinning distinction, the stale-profile disclosure — are behavioral rather than parameter-specific. With the schema already doing the heavy lifting, the baseline 3 is correct; the description complements but does not substantially extend parameter understanding.

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 'Find people on LinkedIn for one or more company searches' names a specific verb, resource, and scope, and the return contract ('Results are always LinkedIn URLs') pins down the deliverable unambiguously. It also distinguishes itself from its siblings — exa_search_news (news), find_companies_by_tech_stack (companies), search_linkedin_people (direct person search) — by positioning itself as the post-company-find batch person finder. An agent can tell what this does without opening a schema.

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

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

Usage context is explicit and strong: 'Use AFTER companies have been identified (company-find step in the same agent, user named a target, CRM lookup, etc.)', plus a mandatory prerequisite call to get_skill_guide('exa_find_people') that owns the query/system_prompt split. It also explains when to deviate — passing null for company on cross-company and alumni searches, and using persist=False to fold results into company rows via record_search_results. What it never does is name a direct sibling to prefer in an alternative scenario (e.g., 'use search_linkedin_people instead when X'), so the when-not dimension is implicit rather than explicit.

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

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

Annotations only mark readOnlyHint, so the description carries the behavioral burden. It adds substantial detail beyond annotations: parallel fan-out, 10 articles per query, server-side lookback filtering, dedup by domain with first-article-wins, partial vs. total failure behavior, credit costs, and error raising. No annotation contradiction exists.

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?

Though long, the description is structured with a summary and returns section, and every sentence adds operational value: cost model, failure modes, deduplication, and querying rules. It is information-dense without 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 provides the full return shape: company rows, fields, dedup behavior, `exa_available` and `error` on total failure, and credit-refusal behavior. An agent has everything needed to invoke the tool and interpret its results.

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

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

Schema coverage is only 50% because `lookback_days` is undocumented. The description compensates fully: it explains `lookback_days` default of 30 and server-side exclusion, and gives concrete guidance for `queries` including positive-form composition, one-query-per-signal, and an example.

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: 'Discover companies from recent news via Exa's semantic news search.' It clearly differentiates from siblings by explaining that articles come back as pre-extracted company rows, 'unlike tavily_search there is no article-extraction step.'

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

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

The description explicitly positions the tool within the News-mode routing, names its alternatives (`search_news_events`, `tavily_search`), and states when it is appropriate: it covers narrative signals typed categories miss and fills zero-result gaps. It also gives concrete query-composition rules, lookback guidance, and batching instructions.

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 meaningful behavioral traits absent from the annotations: criteria reuse, lack of refinement support, specific refusal conditions, and clamp behavior with a `clamp_notice` to surface. This goes well beyond the minimal readOnly/destructive hints and tells the agent what to expect at runtime.

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 densely informative with no filler. It front-loads the core action, then covers exclusions, alternatives, refusal conditions, and edge-case behavior in a compact, logically ordered block that earns each sentence.

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

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

For a 3-parameter tool with no output schema, the description covers invocation semantics, failure modes, clamping behavior, and user-facing notices. The only minor gap is that it does not explicitly describe the success return payload, but the tool's purpose and schema make that reasonably inferable.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that additional_count is clamped when balance covers fewer results and that list_name should be a fresh slug when starting a new list. This enriches the static schema definitions.

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

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

The description opens with a specific verb and resource: 'Add more results to a named list on an agent.' It clearly distinguishes itself from the sibling start_find_search by noting it reuses the list's original criteria and does NOT support refinement, so an agent can tell what this tool is for immediately.

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

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

Provides explicit routing guidance: if the user wants to narrow criteria, tell them to start a new list via start_find_search with a fresh list_name. It also lists concrete refusal conditions, giving clear when-not-to-use context beyond what any schema or annotation conveys.

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

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

Annotations only declare readOnlyHint, but the description adds substantial behavior: results are written back to the local store so later searches see them, an empty result is authoritative rather than a cache miss, the fetch is capped (truncated flag), and errors mentioning reconnection require the user to reconnect in Settings. These are traits the annotations do not convey.

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

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

Front-loaded summary of what it does and when to use it, followed by the returns/error contract. No filler sentences; every clause carries operational information (backfill window, write-back, provider_id sourcing).

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?

Even without an output schema, the <returns> block documents success/failure shape, chat_id handoff to setup_linkedin_sequence, message fields, truncation, and the connection_request_note edge case, including why it is excluded from messages/count. Nothing an agent needs to call or interpret the result 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 already documents as_teammate thoroughly, but the description still adds real value: it identifies provider_id as a LinkedIn provider_id with named sources (prospect row, search_linkedin_connections, prior message) and explicitly forbids guessing from a name. That closes a common misuse path the schema alone does not.

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 summary states a specific verb and resource ('fetch the user's full LinkedIn message history with one person') plus the source ('live from LinkedIn via Unipile'). It explicitly distinguishes itself from the sibling local-store tool search_linkedin_message_history, so an agent can route 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 an explicit ordering rule ('Query the local store with search_linkedin_message_history first. Reach for this tool only when...'), names the three triggering conditions (cache miss, older than the ~2-week backfill, need certainty about existence), and states what an empty result means. This is textbook 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?

Discloses far beyond the annotations: visibility limits ('private or deleted posts return a plain error'), the 500-reaction + 500-comment cap with a `truncated` flag, 6-hour cache cost exemption, and the shared daily budget. It also details the materialization side effect (agent_search_results rows with entity_type='person' and the specific data fields) and idempotent re-runs ('updates existing rows rather than duplicating'). This is consistent with readOnlyHint=false and destructiveHint=false — no contradiction.

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

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

The description is front-loaded — core purpose and use case land in the first paragraph — and organized into distinct knowledge blocks (visibility, limits, budget, materialization, workflow). It is long, and some operational advice ('set that expectation with the user before calling') leans toward prose rather than specification, but nearly every sentence carries a distinct fact an agent needs before calling. Slight overlap with the persist/list_name parameter descriptions keeps it at a 4 rather than 5.

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

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

For a mutating tool with 4 parameters, a budget interaction, caching, and a follow-up pipeline, the description covers every decision point: input forms (URL types are in the schema), error conditions (visibility, budget exhaustion, rate-limit pause), return structure via the detailed `<returns>` block, and the exact downstream calls. Nothing an agent needs to invoke it correctly is left to guesswork. The `<returns>` block effectively substitutes for the missing output schema.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and the baseline is 3. The description adds workflow rationale beyond the schema, notably why `persist=False` exists ('records only a filtered subset itself, so the full unfiltered list wouldn't also clutter the Output tab') and the `list_name` default path ('absent, they land in the 'default' list'). That extra context lifts it to 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?

The summary opens with a specific verb-resource pair ('Fetch the people who reacted to or commented on a LinkedIn post') and immediately states the storage side effect ('store them as queryable engagement rows'). It distinguishes itself from the neighboring query tool by naming `query_linkedin_post_engagements` as the post-fetch filter step, and the use-case phrasing ('everyone who liked this post', 'who commented on her launch post') is unmistakable. The only near-sibling (`queue_linkedin_post_engagement`) isn't explicitly contrasted, but fetch-vs-queue is semantically clear from the text.

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 — 'Use when the user wants to turn a post's engagers into leads' — with two concrete example phrasings. It adds cost and latency gates an agent must weigh before calling ('counts one action against the shared daily engagement-fetch budget', 'takes around half a minute') and explicitly instructs setting user expectations on big posts. It closes with a precise follow-up workflow naming `query_linkedin_post_engagements` and `setup_linkedin_sequence` and what to pass each.

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

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

Annotations only provide readOnlyHint, so the description carries the full burden — and it excels. It discloses the detection method (job-posting text, not storefront crawling), the meaning of absence ('not detected here'), the two-part pricing model, the chat-response requirement to state count and cost, the failure return shape, and the slug-resolution mechanics. All of this goes well beyond what the annotations state.

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

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

The description is long, but well-structured and front-loaded: a one-line summary, then usage rules, caveats, pricing, and mechanics in logical order. Every section carries essential information for correct invocation; the density is justified by the tool's complexity, though it could be trimmed slightly without losing value.

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

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

Despite lacking a formal output schema, the returns block documents the exact JSON shape including the failure case (`theirstack_available: False`), and the description covers pricing, detection caveats, exclusions, pagination behavior, and chat-side instructions. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter. The description still adds meaningful context: AND semantics for `technologies` ('EVERY supplied technology must be present'), per-page billing implications for `limit`/`offset`, and guidance to prefer the user's requested number for `limit`. This exceeds the baseline without duplicating 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 opens with a clear verb+resource statement: 'Find companies whose technographic profile matches a target tech stack.' It then explicitly differentiates from the closest sibling, `theirstack_search`, by contrasting 'investment intent' vs 'installed base,' so an agent can confidently tell the two apart.

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 'Use ONLY when...' conditions with concrete examples ('find DTC brands using Shopify and Klaviyo'), names the exact alternative (`theirstack_search`) for the hiring-signal case, and provides exclusions (recruiting agencies excluded, don't quote the figure as a price). This is textbook when-to-use vs when-not-to 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?

The description directly contradicts the readOnlyHint=true annotation by stating that verified emails are 'written for you onto the person's canonical profile' and 'onto their prospect row in your campaigns.' This is a state-modifying side effect, so per rubric the score is 1 and the contradiction must be flagged. Apart from that, the description is transparent about costs, caching, and provider fallback behavior.

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

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

The description is long but front-loaded with the core purpose and organized into summary and returns sections. Every paragraph carries operational necessity, though some sentences are dense enough that a bit of trimming could improve readability. Overall efficient for the tool's complexity.

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

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

Even without an output schema, the description fully defines the return shape, error semantics, side effects, cost model, cache behavior, and provider fallback logic. An agent has everything needed to invoke the tool correctly and interpret results, including when to stop and ask the user.

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 semantics: the contacts parameter's single-vs-batch usage, parallel lookup behavior, provider pinning effects, and the cache/credit implications of choosing provider or leaving it unset. These details go well beyond the schema's field descriptions.

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

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

The description opens with a specific verb and resource: 'Find email addresses for one or more people.' It clearly distinguishes itself from sibling tools like find_phone_number and find_linkedin_url by the object being found, and further clarifies batch versus single lookup without ambiguity.

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

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

Provides strong operational guidance: pass single contacts as a one-entry list, batch contacts for parallel lookup, don't re-run finalized misses, and only run backfills after explicit user approval. It does not explicitly compare against alternative tools or state when to prefer find_email over apollo_enrich or other siblings, so it stops short of a 5.

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

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

Beyond the readOnlyHint annotation, the description discloses real behavioral costs: 'Costs 1 Sliq credit per verified hit. Free when the user has connected their own Apollo key.' It also explains the 429 throttle behavior and distinguishes transient rate-limiting from a permanent no-match result. This meaningfully exceeds what the annotation alone conveys.

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

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

The core purpose is front-loaded in the first sentence, with use cases, alternatives, cost, and return behavior following in a logical order. The phrasing is mostly efficient, though the 'queue boundary' explanation in the setup_email_sequence suggestion is somewhat jargon-heavy and could be clearer.

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 <returns> section does its job by defining success shape, no-match shape, and the rate-limited shape. The description covers inputs, provider, cost, alternatives, and error semantics, making it complete for an agent to decide when to call it and what to expect.

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 both parameters: email and optional name for narrowing the match. The description restates email as the lookup key but adds no new parameter-level meaning beyond the schema, matching the baseline expectation.

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

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

The description opens with a specific verb and resource: 'Find a LinkedIn profile URL for a person given their email, using Apollo.io.' It also identifies itself as 'The reverse of find_email', which clearly distinguishes it from a key sibling tool without requiring schema inspection.

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

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

The description gives concrete usage contexts: deduping a later LinkedIn step against an email step, and supplying the URL required by find_phone_number. It also explicitly names an alternative, setup_email_sequence(enrich=True), and says to prefer it for email outreach when LinkedIn touches may follow. This is strong, actionable routing guidance.

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

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

Beyond the readOnlyHint annotation, the description discloses parallel batch behavior, one-tool-call loop-guard behavior, order preservation, persistence behavior ('persists nothing'), credit costs, the up-front worst-case balance check, InsufficientCreditsError, and per-item error isolation. This far exceeds what annotations alone provide.

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

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

The description is long but densely informative; the core summary is front-loaded and the cost/credit details are structured into clear sections. Every sentence carries operational meaning an agent would need before calling or deciding not to call.

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 one parameter and no formal output schema, the description fully compensates by specifying return shape per hit/miss/error, failure handling, cost implications, BYO-key behavior, and the prerequisite LinkedIn-URL constraint. Nothing an agent needs 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 schema already documents linkedin_urls with an example (100% coverage), and the description adds important semantics: one URL per person, single or batch, parallel execution, one tool call vs N, and same-order results. It doesn't go much beyond that, but the added batch and ordering semantics are valuable.

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

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

The description opens with a specific action (find phone numbers) and the exact input (LinkedIn URLs), and explicitly contrasts with what it cannot do (look up by email or name). This clearly distinguishes it from siblings like find_linkedin_url and find_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 context (when you have LinkedIn URLs), explicit exclusions (no email/name lookup), and an explicit alternative workflow: call find_linkedin_url(email=...) first when only an email is available. It also instructs to repeat resolve-then-lookup per record and skip if no URL can be obtained.

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

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

The description goes well beyond the readOnlyHint annotation by disclosing background execution, pacing (1-5 minutes between targets), LinkedIn safety limits, daily budget behavior, credit costs per target, deferral of targets beyond budget, and the single-slot concurrency constraint. It also explains the 'sample vs complete set' caveat for targets returning 10 mutual connections. This is rich behavioral context that annotations alone do not provide.

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

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

The description is long but information-dense, with clear sectioning via <summary> and <returns> tags. It front-loads the core purpose and target format, then covers operational details. While it could be tightened, every sentence carries operational or behavioral information an agent needs; the length is justified by the tool's complexity.

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

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

The description is complete for a complex background tool: it covers input format, output location and format, result interpretation caveats, cost/budget behavior, concurrency, and failure modes. The <returns> section documents the three possible status dict forms. Nothing an agent needs to call this tool correctly and interpret its results 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 schema already documents both parameters. The description adds meaningful context beyond the schema: it explains what kinds of identifiers are accepted (profile URLs, username slugs, provider_ids), how list_name is used as a bucket/slug for grouping results, and that reusing a slug accumulates into one list. This adds value beyond the schema's basic descriptions.

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

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

The description states a specific verb ('find'), a specific resource ('warm-intro paths' via the user's 1st-degree LinkedIn connections), and the target input format. It clearly distinguishes itself from sibling tools like search_linkedin_people or search_linkedin_connections by focusing on the warm-intro path use case.

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

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

The description explicitly explains when to use this tool (to find warm-intro paths to target people), how to pass targets, how to read results via query_search_results, and what to do with partial results (treat 10-mutual-connection targets as a sample). It also gives operational guidance: confirm with the user before large lists, re-run tomorrow for deferred targets, and only one search at a time per account.

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 (readOnlyHint=false, destructiveHint=true), the description discloses the concrete side effects: it charges 1 credit, flips the post's feed status to 'queued', refuses ineligible posts, and returns one of three distinct state forms. It also notes the 'same Sliq drafting the monitor sweep uses' for consistency. This is rich behavioral context that the annotations alone do not provide.

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

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

The text is dense but well-organized: a first-sentence summary, an explicit routing rule, eligibility/refusal conditions, and a structured returns block. Every sentence earns its place, especially since there is no output schema and the returns block is the sole documentation of the tool's return contract.

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 two parameters, no output schema, and meaningful side effects, the description covers all essentials: what it does, when to use it, which inputs to pass, which states are refused, credit/status consequences, and all possible output shapes. An agent has everything needed to call it correctly and understand the outcome.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra selection semantics by specifying which row statuses make a monitored_post_id valid ('skipped', 'skipped_no_credit', 'engagers_only', 'surfaced') and by clarifying the credit-charge consequence. This goes beyond the property descriptions, though the schema already covers the core parameter meaning well.

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

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

The description opens with a specific verb phrase — 'Draft a comment on demand for one monitored post ... and queue it for approval' — naming both the resource (monitored post) and the action. It distinguishes this tool from its nearest sibling by name, explicitly contrasting it with queue_linkedin_post_engagement and tying it to query_monitored_posts.

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

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

The description gives a direct routing rule: 'Prefer this over queue_linkedin_post_engagement ... when acting on a post from the agent's monitored-posts feed.' It also states that the caller should pass a row id from query_monitored_posts and enumerates the eligible statuses and refusal conditions, leaving no ambiguity about when this tool applies.

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, so safety is covered. The description adds substantial behavioral context: pagination via `recent_runs_truncated`, the meaning of `recent_runs`, how to handle `mcp_changes`, and how to interpret `tracking_summary` funnels. It does not contradict the read-only annotation.

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

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

The description is front-loaded with a clear summary and then uses a structured returns section. It is lengthy, but much of the length substitutes for a missing output schema by explaining return fields and pagination behavior. The structure is effective, though not maximally concise.

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 that there is no output schema, the description fully documents the return shape, paging behavior, truncation signal, and how to interpret nested summaries like `tracking_summary.funnel`. It also connects related tools (`get_run_transcript`, `get_mcp_change_calls`, `append_learning`). Nothing essential for correct invocation or interpretation appears 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 description largely repeats the schema's paging guidance for `recent_runs_offset` rather than adding new parameter meaning. It clarifies return fields, but those are not input parameters. The baseline score of 3 is appropriate when the schema already documents all three 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: load full details for a single agent, including workspace, learnings, recent runs, and tracking summary. It explicitly distinguishes itself from `list_agents` and routes run-level transcript access to `get_run_transcript`, so an agent can tell it apart from 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?

It names the exact user intent ("when the user asks about a specific agent's progress, history, or contents") and the alternative tool (`list_agents`) with the condition that selects this one. It also clarifies how to continue to run transcripts, leaving little to inference.

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

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

With only readOnlyHint=true in annotations, the description adds substantial behavioral context: null `sequence` for a flowless campaign, `off_sequence` marking stranded node ids, `removed` prospects still resting but excluded from current/blocked/pending, and `pause` explaining why a node has pending occupants but no throughput. These are exactly the caveats an agent needs before interpreting the live view.

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 front-loads the summary and use cases before diving into DAG and occupancy semantics. Much of the length is necessary because there is no output schema, though the `<returns>` block repeats some pause details already explained above.

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 no output schema and a complex nested return shape, the description fully documents `sequence`, `nodes`, and `pause`, including null and empty cases, node kinds, routing fields, and the distinction between blocked and pending. An agent has everything needed to call and interpret the tool correctly.

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

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

Schema coverage is 100%, so the schema already defines `agent_id` as 'ID of the agent (campaign) to read.' The description adds meaningful scope beyond that: the parameter can be any of the user's campaigns and is not limited to the agent in context. This is a useful clarification, though not a syntax or format detail.

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

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

The description opens with a specific verb and resource: 'Read the live Campaign Flow for an agent: the authored `sequence` DAG plus, per node, how many prospects currently rest there.' It distinguishes this view from sibling tools by tying it to the Campaign Flow tab and to diagnostic questions about prospect location and step firing.

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 use cases: answer 'where are my prospects', 'how many are stuck at the connect step', or trace the campaign's shape. It also clarifies scope: 'Pass any of the user's campaigns; it is not limited to the agent in context.' It does not name when to choose this over sibling tools like get_node_history, so it stops short of full when-not/alternative routing.

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

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

Annotations already declare readOnlyHint=true, and the description adds genuinely useful behavior: it returns a dict with title, message count, has_more, and ordered messages, plus notes that has_more indicates older messages remain. No contradiction. It doesn't discuss failure modes, but with readOnly covered and return shape documented, 4 is appropriate.

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?

Short, front-loaded summary followed by a compact returns spec. Every sentence earns its place; there is no filler or 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?

Despite no output schema, the description documents the return dict and paging semantics. For a simple 3-param read tool with a required session_id and detailed schema descriptions, nothing essential is missing.

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

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

Schema covers all three params in detail (limit default/max, offset paging, session_id), so baseline is 3. The description adds value by explaining where session_id comes from (search_chat_history), which is not in the schema and helps correct invocation.

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 operation ('Retrieve readable messages') on a clear resource ('a past chat session'), and the workflow mention of search_chat_history distinguishes it from the sibling search tool. An agent can tell this is the read-after-search step 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?

Explicitly instructs to call search_chat_history first to obtain the session_id, then use this tool to read the conversation. This gives a concrete when-to-use and names the relevant alternative.

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

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

Annotations only declare readOnlyHint. The description adds substantial behavioral context: team is None for solo users, seats_used vs seats_active meaning, per_member_spend excludes removed members and unattributed charges, and unattributed spend groups by activity label. This goes well beyond the annotation.

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 every sentence earns its place by explaining return semantics, aliases, or edge cases. The purpose is front-loaded, and the return structure is compactly presented before deeper caveats.

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

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

With no output schema, the description must fully document the return shape, and it does: nested structures, None cases, counting semantics, and non-summation caveats are all covered. For a zero-parameter read-only tool, nothing needed to invoke it correctly is missing.

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

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

The tool has zero parameters, so there is no parameter semantics burden to carry. Per the zero-parameter baseline, the description appropriately spends no space on inputs that do not exist.

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: it retrieves the current Sliq credit balance, 30-day agent spend, and the workspace team block. This clearly distinguishes it from sibling get_* and check_* tools by data domain rather than relying on the name alone.

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

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

The description gives clear context for when this tool is relevant: whenever credit balance, spend by agent, or team seat/credit data is needed. It does not explicitly name alternatives or exclusions, but the scope is specific enough that an agent can route to it confidently.

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 says the tool 'upload[s] it to S3', which is a write side effect, while the annotations declare readOnlyHint=true. This is a direct annotation contradiction, making the behavioral signal unreliable for an agent.

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

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

The description is compact and well-structured: a short summary block and a return contract. Every sentence earns its place, and the key action 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 simple two-parameter tool, the description covers the operation, parameter source, and return shape, which is especially important because there is no output schema. It does not describe failure cases or size limits, but the core calling contract is sufficiently clear.

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

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

The schema already documents both parameters fully, so the baseline is 3. The description adds value by instructing that both values come from search_emails results and that both should be provided, clarifying provenance and intended usage 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 states a specific action: fetch an email attachment, upload it to S3, and return a URL. It conveys the resource and outcome well, though it does not explicitly distinguish itself from sibling tools like read_attachment or list_attachments.

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 usage context: 'Use this when you need to access a file attached to an email' and points to where the identifiers come from. It does not provide explicit exclusions or alternative tool guidance, so it stops short of a 5.

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

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

The description usefully discloses the return shape (dict with count and emails array) and the 6000-character truncation, which annotations cannot convey. It doesn't detail failure behavior or consent-gated teammate rejection, but readOnlyHint covers side-effect safety and the schema already documents the consent rule.

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

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

The description is compact and well-structured with summary and returns sections. It front-loads the core action and includes only essential workflow and return information, with no filler.

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

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

With no output schema, the description provides the return contract (count and truncated emails array) instead of leaving the agent to guess. Combined with 100% schema parameter coverage and readOnlyHint, the tool is fully actionable.

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

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

Schema coverage is 100%, so both ids and as_teammate are fully documented in the schema, including the max 20 limit and consent gating. The description's 'by ID / after search_emails' context adds only a high-level workflow cue, not deeper parameter semantics.

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

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

The description states a specific verb and resource ('Fetch full email content by ID') and clearly positions it as the follow-up to search_emails. This differentiates it from sibling search and attachment tools well enough for an agent to select it correctly.

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

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

It explicitly says to use this tool after search_emails and when closer inspection is needed, which gives the agent a clear invocation path. This effectively communicates when this tool is appropriate versus relying on search results alone.

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

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

Beyond the readOnlyHint annotation, the description discloses detailed behavioral nuances: the meaning of a missing key, that shared_calendars is not a connection-status entry, and the distinct slack flags (connected vs slack_mcp_connected). This goes far beyond what annotations provide and prevents misinterpretation.

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 structured with a summary and a returns section, each sentence serving a distinct purpose. It is compact yet comprehensive, with the most critical usage context front-loaded and the return details logically organized without 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?

Since there is no output schema, the description fully covers the return format, edge cases, and ambiguous keys. It explains how to read results, what missing keys mean, and the special handling for slack and shared_calendars. An agent can rely on it alone to correctly interpret 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?

There are zero parameters, so the schema already covers everything. The description doesn't need to explain parameters and correctly focuses on the return structure. Baseline of 4 is appropriate because no parameter info is missing or needed.

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

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

The description clearly states the tool returns which integrations the account has connected, keyed by the same integration_id used in get_tool_connect_url. This specifies the resource and its scope, and it differentiates itself by mentioning the keying scheme and the sibling tool it complements.

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

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

The description gives explicit, actionable usage guidance: call this before telling a user an integration is unavailable, or before minting a connect link for one they say is already connected. This provides clear when-to-use context and indirectly sets expectations about when not to use it (i.e., when you already know the 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?

Beyond the readOnlyHint annotation, the description discloses substantial behavior: default summary vs. roster drill-down, pagination with offset/limit and truncated flag, the exact URL shape expected by setup_linkedin_monitoring, timezone semantics for run_weekdays, and last_run_at being null before first run. This goes well beyond what annotations alone provide.

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

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

The description is long but every sentence earns its place: core purpose, editing caveat, default behavior, drill-down behavior, paging algorithm, field semantics, and return shapes. It is structured with summary and returns sections, making the volume navigable and front-loading the primary purpose.

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

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

Given a read-only tool with no output schema, the description fully compensates by specifying both return dict shapes, all key field meanings, pagination semantics, blank-value conventions for engager fields, and the empty-list case. The parameter schema and readOnlyHint annotations are also complete, so an agent has everything needed to invoke the tool correctly.

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

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

The input schema already documents all four parameters with good descriptions (100% coverage), so the baseline is 3. The description adds extra meaning for monitor_id by explaining that its id comes from each summary row, and it clarifies paging behavior for offset/limit with the truncated flag. That enrichment justifies 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?

The description opens with a specific verb-resource pair: 'Read the LinkedIn post monitors configured on an agent', then enumerates exactly what is returned (mode, schedule, writing instructions, enabled actions). This clearly separates it from sibling tools like setup_linkedin_monitoring, edit_monitor_members, and query_monitored_posts, which have different purposes.

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

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

The description gives explicit guidance on when to use the tool: read current config before editing a monitor because setup_linkedin_monitoring overwrites unpassed fields. It also explains when to use the default summary vs. the monitor_id drill-down. It does not explicitly list alternative read tools or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral burden and exceeds it. It discloses the recency window, response status semantics, exclusion of reshares and quote-posts, credit costs, the large-batch gate, and the skipped_profiles_due_to_credits behavior. This is far more than typical and gives the agent an accurate mental model.

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 it is well-structured with clear sections and every major paragraph serves a functional purpose: usage, recency semantics, batching, cost, and return shape. It is denser than strictly necessary, especially around cost and the large-batch gate, but the structure and front-loading keep it navigable.

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

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

There is no output schema, but the description fully compensates by documenting the return keys, status values, and engagement-count semantics. It also covers failure modes, credit limits, approval policy, batching constraints, and profile URL input rules. An agent has everything needed to call this tool correctly and interpret its 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 the baseline is 3, but the description adds meaningful semantic context beyond the schema. It explains the credit cost formula, when large_batch_approved may be set, how profile_input maps responses to requested URLs, and why unresolvable_profiles are not charged. Some details like limit defaults are only in the schema, but the added context justifies a score above baseline.

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

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

The description opens with a specific verb and resource: fetch recent LinkedIn posts from one or more profiles using Apify. It further distinguishes this tool from post-history tools and from fetch_post_engagers by emphasizing the recency window and noting that engagement counts are not the people who engaged. This makes the tool easy to separate from siblings even without opening schemas.

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

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

It explicitly states when to use the tool: to check what someone posted recently and to personalize outreach off something they actually said. It gives clear when-not guidance by saying this is not for post history, by warning against widening posted_within_days unless asked, and by naming fetch_post_engagers as the alternative for the actual list of engagers. The ALWAYS BATCH instruction also gives concrete operational 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 the description builds on that by disclosing no-truncation pagination, inclusion of both upcoming and past events, and the exact return shape (dict with events array and count). It adds useful behavioral context such as ISO 8601 UTC timestamps and id prefix evt- that annotations do not provide.

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

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

The description is front-loaded with the core action, then organizes behavioral details and return fields into clear summary and returns sections. Every sentence adds value, and the enumerated useful fields prevent ambiguity without bloating the description.

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

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

For a zero-parameter read-only tool with no output schema, the description is fully self-sufficient. It covers scope, ordering, completeness, return structure, and relevant field formats, and it links to the sibling tool that consumes the output. Nothing essential is missing for correct invocation or interpretation.

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

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

The tool has zero parameters, so the schema is trivially complete and no parameter documentation is needed. The description focuses on return-value semantics instead, which is appropriate for a no-input read tool.

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

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

The description opens with a specific verb and resource: 'List all events on the user's Luma calendar, most recent first.' It further distinguishes itself by noting it fetches every page with no truncation, making it a complete-calendar listing rather than a filtered search. It also references get_luma_guests as the consumer of the returned event id, clarifying its role among 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?

The description gives concrete usage contexts: answering 'which event is next', finding an event's id for get_luma_guests, and handling luma_event_created trigger fires. It does not explicitly state when not to use it or name exclusion alternatives, but the guidance is clear enough for an agent to select it appropriately.

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?

Despite readOnlyHint=true in annotations, the description discloses meaningful additional behavior: it persists each guest to the agent's Output tab, records rows keyed by LinkedIn identifier or email, updates in place, and keeps removed guests removed. It also states persist failures never fail the read. This goes well beyond the annotation and gives the agent an accurate mental model of side effects. No contradiction with readOnlyHint exists because the external Luma data is never mutated.

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 every sentence carries load: the summary front-loads the exhaustive-roster guarantee, the middle paragraph justifies the design and reveals side effects, and the returns section is organized. There is no filler or repeated schema data. The structure with summary and returns sections makes it easy to scan.

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

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

With no output schema, the description fully documents the return shape: event_id, guests array, count, list summary, and the useful fields inside each guest object including approval_status, invited_at, registration_answers, and utm_source. It also covers persistence behavior, failure semantics, and re-run behavior, so an agent has everything needed to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the structured schema already fully documents event_id (including the "evt-" prefix) and list_name (including default behavior). The description adds no extra parameter-level meaning beyond the schema; it only mentions how the saved person rows are keyed. This meets the baseline but does not exceed it.

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

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

The description opens with a specific verb-resource pair: "List every guest of a Luma event, with full registration detail." It also immediately clarifies the tool's exhaustive scope (all approval statuses, paginates to exhaustion), which distinguishes it from event-listing tools like get_luma_events. This is unambiguous and actionable.

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

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

The description provides strong usage context: it warns that inferring "who hasn't registered yet" from a partial roster causes false negatives and re-nagging, and explains why the tool deliberately avoids trimming. This tells the agent when to rely on the complete output. It stops short of explicitly naming alternatives or saying "use X instead when Y," so it loses the top point for missing explicit exclusions.

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