HookSend

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful context beyond that: the internal breakdown of the credit total, the expiry behavior, and the list of features that actually consume credits, which supports the diagnostic use case. It omits auth requirements and any caching or refresh 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 main answer is front-loaded in the first clause, and the final sentence cleanly covers the two use triggers. The middle sentence enumerating every credit-consuming feature is long and listy, but it earns most of its place by grounding the 'an AI feature stopped working' scenario.

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

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

With no output schema, the description carries the return-value burden and does so by naming the three credit components and the expiry timing. For a zero-parameter, read-only query tool this is complete enough to call and interpret correctly.

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

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

The tool takes zero arguments, so per the rubric the baseline is 4. The schema itself documents 'This tool takes no arguments', and the description correctly adds no parameter detail because there is none to add.

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 precise verb and resource: reporting how many AI credits remain, broken into plan-granted, top-up-purchased, and manually-added amounts, plus expiry timing. The narrow AI-credit framing inherently separates it from the generic account_usage sibling, so an agent can identify scope 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?

It gives two explicit trigger conditions: 'how many credits do I have left' and 'when an AI feature has stopped working'. That is clear when-to-use guidance, though it names no alternative tool or exclusion, so it falls short of a full when/when-not/alternatives treatment.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds genuine behavioral context: it 'does not call Instagram' and is a 'quick lookup,' signalling it is cheap and side-effect-free. It omits any return-shape or pagination detail, keeping it just short of 5.

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

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

Three sentences, front-loaded with the core function, then routing guidance, then a reassurance about cost. All earn their place, though the final 'no reason to avoid it' sentence is slightly padding.

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

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

For a no-parameter, no-output-schema lookup tool, the description is nearly complete: it explains the purpose, the key returned field (the account id), and when to call it. A brief note on what other fields are returned would make it fully 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The schema confirms 'This tool takes no arguments,' and there are no parameters for the description to otherwise clarify.

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 ('Lists') and resource ('the Instagram accounts connected to this HookSend workspace'), and uniquely positions itself as the source of the account id that 'every other tool uses to narrow its answer.' An agent can distinguish it from siblings like instagram_profile or account_usage without opening a schema.

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

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

Explicitly says to 'Start here whenever a question names a particular account or handle, or when you need an account id for another tool,' giving both the trigger condition and the downstream dependency. This is exactly the routing guidance an agent needs for a root lookup tool.

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

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

Annotations already declare a safe read operation, and the description adds genuinely new semantics: a null limit means unlimited on this plan, and pricing is deliberately excluded. It does not cover auth requirements or any pagination/refresh behavior, but for a zero-argument plan lookup those gaps are minor.

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

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

Front-loaded with the resource and its contents, followed by usage triggers and two boundary clauses; almost every clause carries information. The first sentence is long and densely list-like, which slightly taxes readability but nothing is filler.

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

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

With no output schema, the description carries the full burden of describing return content, and it does so field-by-field (allowances, usage counts, slots) plus the null-means-unlimited convention. Nothing an agent needs to call or interpret this tool is missing.

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

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

The tool takes no arguments, so per the rubric the baseline is 4; there is nothing for the description to clarify beyond the schema's own 'This tool takes no arguments.'

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

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

The description states a specific resource (the workspace's current plan) and enumerates exactly what it reports: DM usage against the monthly allowance, extra messages purchased, Instagram account and live-campaign allowances vs. usage, and knowledge base/flow slots. An agent can distinguish it from account_ai_credits or account_instagram_accounts because those cover single counters while this is the consolidated limits view.

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 is given: any question about limits, what is left, whether something is about to run out, or why HookSend stopped sending. It also draws one boundary (pricing belongs on the customer's billing page), but names no sibling alternative for overlapping questions, 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?

Despite annotations already marking it non-read-only and non-destructive, the description adds rich context: the campaign goes live immediately and messages real people on its own, it is reversible via campaigns_pause, it counts against the customer's plan, and paid-only features or plan limits are refused with a specific sentence the agent should relay verbatim. This goes well beyond the annotations and is exactly the behavioral detail an agent needs.

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

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

The description is a single dense paragraph, but it is front-loaded with the core action and then layers on live behavior, reversibility, and plan constraints. Every sentence carries operational weight for a 26-parameter creation tool, though the lack of structure makes it slightly harder 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?

For a complex create operation with 26 parameters and no output schema, the description covers the critical agent-facing concerns: immediate live behavior, reversibility, plan accounting, paid feature restrictions, and how to handle refusals. The schema handles parameter details, so the description is complete for correct invocation.

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

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

With 100% schema description coverage, the schema already documents all 26 parameters. The description only adds a grouped note that story triggers, the follow gate, lead capture, and follow-up messages are paid-only features, which is useful but does not substantially extend parameter meaning beyond what the schema provides.

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

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

The description gives a specific verb and resource: creates a comment-to-DM campaign that watches an Instagram post/story/inbox for keywords and sends a DM. It clearly distinguishes its live-by-default behavior from campaigns_pause as the off-switch, but it does not differentiate itself from the sibling campaigns_create_full, which an agent may need to choose between.

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 implies when to use it by describing the default live behavior and the isActive: false escape hatch, and it names campaigns_pause for reversal. However, it gives no explicit guidance on when to pick this tool over the sibling campaigns_create_full or campaigns_update, leaving that choice to inference.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description carries far more: the campaign starts messaging real people immediately unless isActive:false, it is reversible via campaigns_pause which preserves collected data, paid features are itemized (carousel, story trigger, follow gate, email question, follow-up, one live campaign too many), and refusals are described as a plan-naming sentence to repeat as written.

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

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

Purpose is front-loaded in the first sentence, followed by the sibling routing, then the go-live warning and plan-limit caveats. It is long, but for a 45-parameter mutation tool each sentence (live messaging risk, reversibility, plan refusals) earns its place. Slightly dense but not padded.

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

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

For a 45-param mutation with no output schema, the description covers the critical gaps an agent needs: default go-live behavior, reversibility path, paid-feature refusals, and the sibling choice. Return values are unnecessary since no output schema exists. Minor gap: it does not hint at which parameter clusters are mutually exclusive beyond what the schema states.

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

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

Schema description coverage is 100% with 45 well-documented parameters, so the schema already does the heavy lifting and the baseline is 3. The description adds little parameter-level syntax beyond schema — mostly grouping features by name — though it does reinforce the button ceiling and trigger set conceptually.

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 ('Creates a campaign') and then enumerates the builder components it can fill at once — carousel/message, trigger, keywords, greeting, follow gate, email question, follow-up, buttons, public reply. It explicitly distinguishes itself from the sibling campaigns_create ('Use this rather than campaigns_create whenever the customer wants more than a keyword and a message').

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

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

Names the alternative (campaigns_create) and the exact condition that selects this tool over it. Adds operational guidance: the campaign goes live unless isActive:false, plan limits apply as in the dashboard, and a refusal sentence should be relayed verbatim. When-to-use, when-not, and prerequisites are all present.

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

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

Annotations already establish readOnlyHint=true/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: message text is shortened in the response, and results/per-campaign totals live in campaigns_list — a real data-limitation caveat an agent needs to avoid misreporting.

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 lead phrase 'Everything about one campaign' is front-loaded and the routing sentence and truncation caveat are well placed. The middle enumeration is a long run-on list that overlaps with sibling setter names and could be tightened, but every element does describe a returned field, so it earns most of its length.

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

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

With no output schema, the description correctly compensates by enumerating the returned structure, and it adds the important truncation caveat plus the pointer to campaigns_list for totals. Only minor gaps remain (no mention of error cases for an invalid/foreign campaignId), which is acceptable for a simple single-item read.

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 campaignId is already documented as 'as returned by campaigns_list', so the schema fully carries the parameter. The description adds no format, sourcing, or constraint detail beyond it — baseline 3.

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

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

States a specific verb and resource ('Everything about one campaign') and then enumerates the exact contents returned: trigger, watched post, keywords, messages, buttons, links, and each switch. This is clearly distinguishable from the sibling setters (campaigns_set_*) that mutate those same fields.

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

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

Explicitly routes the agent: 'Use it after campaigns_list when someone asks what a particular campaign says or does, or why it is not firing.' It names the sibling to call first and the two motivating conditions, with no need for inference.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the description's added value is its caveat that all counts are lifetime totals because HookSend has no per-campaign date filter. That is a genuine behavioral constraint not derivable from structured fields. It stops short of describing pagination or ordering tie-breaks, but covers the main trap an agent would hit.

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 verb and resource, then usage guidance, then the lifetime-totals caveat, which is a sensible ordering. The long enumeration of returned fields is a little bloated for a single sentence, but it is doing real work because 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?

With no output schema, the description compensates by listing the returned fields, and it closes the main correctness risk (date filtering does not exist, so totals are lifetime) that a caller would otherwise assume. Combined with full schema coverage on the three parameters, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so limit, liveOnly and instagramAccountId are already fully documented in the schema, including the note that counts always describe every campaign regardless of liveOnly. The description adds nothing beyond that for parameters, so the baseline 3 applies.

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

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

States a specific verb and resource (lists the workspace's campaigns) with scope (newest first) and enumerates exactly what each row contains. It also differentiates itself from the sibling campaigns_get by naming the lookup use case, so an agent can route correctly without opening either schema.

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

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

Explicitly names the user questions it answers ('how are my campaigns doing', 'which campaign sends the most') and the downstream action it enables (finding a campaign's id before calling campaigns_get). This is concrete routing guidance, not 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 state it is not read-only and not destructive; the description adds substantial context beyond that — it stops answering new comments immediately, preserves leads/statistics/keywords/messages, is fully reversible with campaigns_resume, and is always allowed regardless of plan. This goes well past the annotation bar.

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 core action and scoping, and each sentence contributes (preservation, reversibility, plan independence, misuse routing). It is slightly verbose with some restatement of the 'stop/remove/get rid of' framing, but nothing is wasted.

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

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

For a single-parameter mutation tool with annotations and no output schema, the description covers behavior, side effects, reversibility, permission model, and sibling routing — everything an agent needs 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% with a single documented campaignId, so the schema already carries parameter meaning. The description adds no format or syntax details about the id, 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 gives a specific verb and resource ('Switches one campaign off') and immediately distinguishes it from siblings by naming campaigns_resume as the inverse and noting no delete tool exists. An agent can identify what this does without opening the schema.

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

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

It explicitly states when to use it ('when someone asks to stop, remove or get rid of a campaign') and names the alternative (campaigns_resume for reversal). It also pre-empts the misuse case by explaining no deletion tool exists, so the agent knows pausing is the correct substitute.

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

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

Goes well beyond the annotations (readOnly=false, destructive=false) by disclosing non-obvious traits: it does not retroactively answer comments left while paused, the action is reversible via campaigns_pause, and it consumes a plan-limited live-campaign slot, causing a refusal that names the plan and number. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the core action, then layered with the important caveats (no retroactive replies, reversibility, slot-limit refusal) in a logical order. Each sentence earns its place, though the final clause is slightly dense with instructions about relaying the refusal message.

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 resume tool with no output schema, the description covers the action, its limits, reversibility, and the failure mode and expected response. Nothing an agent needs to call or handle errors 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% and the single campaignId parameter is documented in the schema; the description adds no additional meaning about the parameter. Baseline 3 is appropriate when the schema already carries the 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?

States a specific verb+resource ('Switches a paused campaign back on') and clarifies the ongoing scope ('answers comments again from now on'). It explicitly names the sibling campaigns_pause as the reversible counterpart, letting an agent distinguish the pair 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?

The description makes clear this is for resuming a paused campaign and names the alternative (campaigns_pause) for the inverse action. It also flags the plan-slot condition under which the call will be refused, though it stops short of a fully explicit when-not statement.

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, but the description adds rich behavioral context: it REPLACES all existing cards irreversibly, removes link buttons (with click history), keyword buttons, and the email question, requires confirmation, and is gated by a paid plan with a specific refusal message. This far exceeds what annotations convey.

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

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

The description is long but front-loads the core action and then layers on consequences and caveats. Most sentences earn their place by conveying destructive effects, paid-feature gating, or alternative tooling, though the explanation of HookSend's automatic behavior could be trimmed slightly.

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 destructive nature, paid gating, and lack of an output schema, the description covers all critical aspects: what it does, what it destroys, what it removes, the confirmation requirement, and the alternative for a plain reply. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters in detail. The description provides a high-level summary of card contents but adds no parameter-specific syntax, defaults, or constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: turning a campaign into a product carousel and supplying its cards, with details on card content. It also names a sibling (campaigns_use_standard_reply) for the reverse operation, so an agent can distinguish it from other campaign tools without reading schemas.

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

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

It clearly indicates when this tool applies (to create a carousel campaign) and names an alternative for going back to a plain written message. It also explains that HookSend handles the delivery logic automatically, removing a decision. However, it does not explicitly state when NOT to use this tool beyond that reverse case.

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 carries the real behavioural weight: it DMs everyone who commented a trigger word in the window, can reach many people, is off by default, is reversible via enabled=false but already-sent messages cannot be recalled, and is capped at 7 days by Instagram. That is exactly the context the 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?

Purpose is front-loaded and every clause earns its place, but the prose is dense and runs long across several semicolon-heavy sentences. Justified for a high-blast-radius switch, though slightly more than strictly needed.

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, yet the description explains what the confirmation returns (what the campaign is set to now), the limits, reversibility, and the campaigns it does not apply to. An agent has everything needed to call it safely.

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

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

The schema already documents all three parameters at 100% coverage, including the days ceiling and the enabled default. The description reinforces the default-off behaviour and the read-back pattern (call with only campaignId), adding modestly beyond the schema rather than repeating it verbatim.

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?

It states a precise verb and resource: letting a campaign answer comments that already existed when the post/campaign was made, and explicitly positions this against the default behaviour ('Normally a campaign only answers comments left after it was made'). Against siblings like campaigns_set_public_reply or campaigns_set_trigger, the scope is unmistakable.

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

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

It says exactly when this matters (putting a campaign on an old post that 'appears to do nothing'), how to read the current value (call with only the campaign id), and when it stays off (story, DM, live or ad campaigns). No plan check applies is also 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?

Goes well beyond the annotations: discloses that the operation replaces the whole set, that it is reversible by resending old values, that nothing is counted against a button, that the Instagram limit is three, and that no plan check applies. These are exactly the mutation-consequence details the annotations (destructiveHint=false) cannot convey.

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

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

Front-loaded with the core action, then limits, reversibility, and the empty-list case. Every sentence carries information, though the 'no plan check applies' and reversibility clauses make it slightly longer than strictly necessary.

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

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

For a mutation tool with no output schema, the description covers the consequence of the write (full replacement, reversibility, no counting, no plan check) and the limits an agent must respect. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the keyword is what the flow or AI answers and must match what they are 'listening for', and the list ordering/three-item cap is reinforced. This complements the schema's per-field docs rather than merely repeating them.

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

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

States a specific verb+resource ('sets the buttons under the campaign's message') and immediately distinguishes it from the sibling set_links tools by naming the alternative button type that competes for the same slots. An agent can tell this apart from campaigns_set_links and campaigns_set_carousel 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?

Explains the operational context clearly — what the buttons do, the three-button cap, that link buttons take precedence, and that an empty list removes them. It stops short of explicitly naming the sibling to use for other button types, but the constraint that 'the campaign's own link buttons take their places first' effectively routes the agent.

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

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

With only readOnlyHint=false and destructiveHint=false from annotations, the description carries substantial extra load: it discloses credit consumption per answer, the fallback to the written message when nothing is found or credits run out, full reversibility of both detach and pause, the paid-plan and ownership preconditions, and that a refusal returns a one-sentence reason to be relayed verbatim. This is rich behavioral context beyond the annotations.

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

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

Front-loads the core purpose before detailing fallback, credits, and error handling, and every sentence carries information. It is on the verbose side with some redundant clauses, but nothing is wasted.

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

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

For a four-parameter mutation tool with no output schema, the description covers the side effects, failure modes, cost model, prerequisites, and reversal path, and points to knowledge_list for discovery. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema descriptions already explain reversibility, ownership, and the attach-switches-on behavior, so the description largely restates them. It adds little parameter-level syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Points a campaign at one of the customer's knowledge bases') and immediately clarifies the effect: answering DMs from the customer's own documents rather than a fixed message. An agent can distinguish this from knowledge_create or campaigns_update without opening a schema.

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

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

Gives clear conditions for the main parameter modes — attach to switch answering on, aiReplyEnabled: false to stage it without going live, detach: true to remove it — and routes the agent to knowledge_list for ids. It does not explicitly compare against sibling set_* tools, so it stops short of full 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 flag destructiveHint=true, but the description goes well beyond them: it explains tracking behavior, that changes are irreversible, that removing a button destroys all recorded clicks so they vanish from reports, and that the rest of the campaign is untouched. This is exactly the behavioral context an agent needs for a destructive operation.

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

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

Front-loads the core action in the first sentence and each subsequent sentence carries distinct information (tracking, irreversibility, confirmation request, scope limits). It is slightly long but avoids waste; minor tightening possible in the tracking explanation.

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

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

For a destructive 8-parameter mutation tool with no output schema, the description covers the danger, the confirmation expectation, and the untouched scope, which is everything the agent needs to call it safely and correctly.

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

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

Schema description coverage is 100%, so all eight parameters are already documented in the schema (including confirm, removeLink, and removeSecondLink semantics). The description adds the tracked-link framing but no syntax or format detail beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb (sets) and resource (the two link buttons the campaign's message can carry, plus the addresses behind them). This clearly distinguishes it from siblings like campaigns_set_keyword_buttons or campaigns_set_carousel, since it names the exact artifact being modified.

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 strong usage context: instructs the agent to 'read the customer what you are about to change and ask first,' and notes that no plan check applies. However, it does not explicitly compare against alternative link/button tools or state when this tool is the right choice versus other set tools.

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

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

Annotations only say readOnlyHint=false / destructiveHint=false, so the description carries the real behavioral load and does it well: it discloses reversibility, warns that switching the reply off clears the stored wordings, explains the live-campaign exception, and notes that the confirmation reflects the state. This is well 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 critical operational facts — reversibility and the destructive clearing of wordings — are buried after a rhetorical aside about reading like a robot. Sentences like 'the same sentence repeated under every comment is what Instagram treats as spam' are colorful but consume space without adding callable information.

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

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

For a three-parameter mutation tool with full schema coverage, no output schema, and non-destructive annotations, the description is largely complete: it covers the mutation, its reversibility, the data-loss caveat, and a usage exclusion. Only the missing sibling differentiation keeps it short of full completeness.

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

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

Schema coverage is 100% and the field descriptions already explain enabled's public/clear semantics, the up-to-ten rotation list, and whole-list replacement. The description restates much of this and adds only the rationale for multiple wordings, so the schema is doing the heavy lifting.

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

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

The description states a specific verb and resource: it sets the public reply a campaign leaves under a comment, plus the private DM. It is understandable in isolation, but it never names or distinguishes itself from adjacent siblings like campaigns_use_standard_reply or campaigns_set_earlier_comments, so the agent must infer which one applies.

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

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

It gives a clear when-not ('A live campaign never gets a public reply') and explains why multiple wordings are supplied (rotation, spam avoidance). It also notes that no plan check applies and that re-calling restores old wordings. What it lacks is any explicit routing between this tool and the other reply-setting siblings.

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

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

Adds a great deal beyond the annotations (readOnlyHint=false, destructiveHint=false): only passed fields are touched, every change is reversible, switching a step off clears its wording, story campaigns strip these steps, and three steps are paid features refused with a sentence to repeat verbatim. These are exactly the behaviors an agent must know before calling.

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 in the opening sentence, then the warnings, then the plan-level caveat. Dense and long, but nearly every clause carries operational information; the four-step enumeration could be tightened without loss.

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 13-parameter mutation tool with no output schema and only safety annotations, the description covers partial-update behavior, reversibility, plan gating, and the story-campaign edge case. It refers to a 'confirmation' response but does not otherwise say what the tool returns, which is the only real gap.

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

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

Schema description coverage is 100%, so the schema already documents every parameter with constraints and paid-feature notes. The description groups the parameters into the four conceptual steps, which adds light meaning, but adds no syntax, format, or constraint detail the schema lacks.

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

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

Names a specific verb (switches on/off, writes wording) applied to a specific resource (the four conversation steps of a campaign), and enumerates those steps so the agent knows exactly what is being configured. This cleanly separates it from siblings like campaigns_set_trigger, campaigns_set_links or campaigns_update.

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?

Establishes context well: partial-update semantics, the story-campaign exclusion, and the paid-plan refusal path. It does not name a sibling alternative for any of those cases, so it stops short of explicit when-to-use-this-vs-that routing, but the boundaries 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?

With only readOnlyHint=false and destructiveHint=false from annotations, the description carries the real behavioral load: it discloses that story triggers silently switch off and clear the opening greeting, follow gate, email question and follow-up wording, that the confirmation reports what survived, that keywords are retained across moves, and that a paid-plan refusal returns a sentence to repeat verbatim. This is far more than the annotations convey.

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

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

Front-loaded with the core action and then the two warnings, with no filler or marketing language. The trigger enumeration in the first sentence duplicates the triggerType enum, so a little length is spent on information the schema already carries.

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 14-parameter mutation tool with no output schema and thin annotations, the description covers reversibility, destructive side effects, cross-tool follow-up, and the paid-feature error path, plus a note on what the confirmation returns. An agent has everything needed to call it and to warn the user beforehand.

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 genuine cross-parameter meaning the schema cannot express — the keyword/matchAnyWord carry-over requirement after a trigger move, and the interaction where a story trigger wipes unrelated message settings. It does not restate the per-field POST/AD/LIVE gating, which the schema already handles 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?

States a precise verb (changes) plus the resource (what starts an existing campaign) and then enumerates every accepted trigger, so an agent can distinguish it from campaigns_update and campaigns_create without opening a schema. The scope word 'existing' correctly excludes creation.

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

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

Gives clear conditional guidance (reversible by calling again; story triggers refused on unpaid plans; a campaign moved from story mention to post trigger needs a keyword set via campaigns_update), which routes the agent to a sibling for the keyword step. It stops short of an explicit when-not-to-use statement or a direct contrast with campaigns_update's broader remit.

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 supply readOnlyHint=false and destructiveHint=false; the description goes well beyond them by stating partial-update semantics ('Only the fields you pass are changed'), reversibility ('every change is reversible by calling this again with the old values'), and, most valuably, that paid-feature refusals come back from the plan and should be 'pass[ed] back as written.' That last point is real behavioral guidance an agent cannot get from structured fields.

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

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

Three sentences, front-loaded with the mutation scope, then the partial-update/reversibility semantics, then the routing exclusion and the plan-refusal rule. No sentence is filler and each adds a distinct, decision-relevant fact.

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 26-parameter partial-update tool with 100% schema coverage and no output schema, the description supplies the mutation semantics, reversibility, sibling routing for on/off, and plan-refusal handling an agent needs. The only gap is not addressing the overlapping set_* siblings, which is a genuine but secondary omission.

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

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

Schema description coverage is 100% and every one of the 26 properties is documented in-schema, including enums and paid-feature flags, so the schema carries the parameter burden. The description's field list (name, keywords, DM, link button, public reply, follow-up) lightly mirrors that without adding syntax, formats, or default semantics beyond 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?

Opens with a specific verb+resource ('Changes the settings of an existing campaign') and enumerates the field families it touches (name, keywords, DM, link button, public reply, follow-up). It also explicitly distinguishes itself from campaigns_pause/campaigns_resume, so an agent can separate it from the most confusable siblings without opening a schema.

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

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

Gives an explicit when-not with the correct alternative: 'It cannot switch a campaign on or off — use campaigns_pause and campaigns_resume for that.' However, it is silent on the many overlapping set_* siblings (campaigns_set_public_reply, campaigns_set_links, campaigns_set_trigger, campaigns_set_keyword_buttons, campaigns_set_steps), whose fields this tool also appears to change, leaving that routing ambiguity unresolved.

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 covering readOnlyHint=false and destructiveHint=false, the description adds rich behavioral detail: cards are retained and not sent, the change is reversible, and restoring via campaigns_set_carousel removes any link/keyword buttons or email questions added meanwhile. It also discloses that no plan check applies.

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 purpose is front-loaded in the first sentence, and each subsequent sentence adds useful constraints or alternatives. It is slightly dense but no sentence 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?

No output schema exists, and annotations are sparse, but the description covers the reversibility, side effects, alternative tool, parameter guidance, and pricing note needed to invoke the tool correctly. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds rationale for dmMessage — that a campaign previously sending cards may have no other message, so you should pass the new text — which goes beyond the schema's definition of the field.

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 (switches back) and resource (carousel campaign to plain written message), and explicitly names the sibling it relates to (campaigns_set_carousel). An agent can distinguish this from other campaign update tools 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 clearly describes the operation's context and the reverse operation, and notes that no plan check applies when switching a paid feature off. However, it stops short of an explicit 'use this when…' directive or stating when not to use it beyond the named alternative.

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

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

Annotations already declare readOnly/non-destructive, and the description goes well beyond them: brand, budget and deliverables are model-extracted from prose and may be wrong, confidence scores should be checked, and an AI provider must be configured. This is exactly the kind of caveat an agent needs before quoting figures.

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?

Content is dense and complete, but the opening sentence is a long run-on that crams the return shape into one clause chain. Information is front-loaded with the primary output, so it remains usable despite the length.

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

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

With no output schema and no annotations beyond read-only hints, the description carries the full burden and delivers: it enumerates returned fields, notes the monthly aggregates, discloses the AI extraction risk, and covers the provider requirement. Nothing an agent needs to call or interpret this tool 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 page, show, limit and instagramAccountId are fully documented in the schema itself. The description adds only indirect hints (newest first, monthly totals) and no per-parameter syntax beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource (lists brand collaboration offers found in DMs) plus the exact fields returned and ordering ('newest first'). It is clearly distinguishable from siblings like inbox_conversations or leads_recent, which cover different data domains.

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 user phrasings that should route here ('has anyone offered me a collab', 'how much have I been offered this month') and a distinct use case (checking what awaits a reply). It also warns that detection requires an AI provider and that an empty list is not equivalent to no interest, which prevents a misread of results.

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 goes well beyond: it discloses the initial state (unpublished, one trigger, one reply), that nothing reaches anyone until flows_publish is called, that the operation is safe, and that a paid-plan gate can refuse the call with a customer-facing reason string. That is exactly the side-effect and failure context an agent needs.

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

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

Front-loaded with the core action and resource, then the safety/state facts, then the plan gate, then the boundary against flows_set_steps. Every sentence carries information an agent would otherwise have to guess.

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

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

With no output schema, the description still covers the resulting state of the created resource, the safety profile, and the error/refusal path, which is everything needed to call it correctly. Nothing material is missing for a single required-parameter create tool.

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

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

Schema description coverage is 100% and every parameter already has a clear description, so the baseline is 3. The description adds no syntax or format detail beyond the schema (it only alludes to templates indirectly), so it does not earn above baseline.

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

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

States a specific verb and resource ("Creates a DM flow") and then defines what a DM flow actually is — a branching script that answers a DM step by step with questions and buttons. It also distinguishes itself from flows_publish and flows_set_steps by naming the publishing step and the canvas as the place steps are built.

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

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

Explicitly says when this is safe ("creating one is always safe" because the flow starts unpublished), what to do instead of building steps here ("done by the customer on the flow canvas, not through this tool"), and what to do on refusal (repeat the reason as written). Alternatives and conditions are all named.

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

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

Beyond the readOnly/destructive annotations, it discloses that reading is free, sends no messages, returns publish blockers in the dashboard's own wording, and returns steps in the exact shape flows_set_steps accepts. These are behavioral facts an agent cannot infer from the annotations or schema.

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

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

Front-loads what the tool returns before moving to usage rules, and every sentence carries routing or safety information. It is on the longer side, but nothing is filler or restated from the name/title.

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

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

There is no output schema, so the description carries the burden of explaining the return value, which it does thoroughly (contents, publish blockers, compatibility with flows_set_steps). Combined with the explicit pre-mutation workflow rule, 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 coverage is 100% and the single flowId parameter is already documented in the schema with its source (flows_list or flows_create). The description adds no additional syntax or format detail about the parameter, 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?

Names a specific verb (reads) and resource (one DM flow) and enumerates exactly what is returned: steps, their joins, name, live status, the connected Instagram account, and re-trigger behavior. This is clearly distinguishable from flows_list, which enumerates flows rather than reading one in full.

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 must-do rule ('ALWAYS call this before flows_set_steps on a flow that already has steps') with the reason (flows_set_steps replaces the whole flow, so unread content is deleted). It also names concrete user intents ('what does my flow say', 'why can I not publish this', quoting wording) that select this tool over siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: exactly what each row reports (published/draft status, step count, unresolved problems, entry counts, link-button taps) and what is deliberately omitted. Return-shape disclosure is valuable since there is no output schema.

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

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

Front-loaded with the core purpose, then return details, then usage cues, then the exclusion. Slightly long but each sentence carries distinct information; the final sentence justifies why contents are omitted rather than padding.

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

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

No output schema exists, so the description must carry the return-value burden, and it does so thoroughly by enumerating the reported fields and the deliberate exclusion. Complete for an agent deciding whether to call it, with only minor room to name the alternative detail tool explicitly.

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

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

Only one parameter (limit) with 100% schema description coverage, so the schema fully documents it. The description adds nothing about the limit or ordering beyond what the schema states, so the baseline 3 is appropriate.

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

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

States a specific verb (Lists) and resource (DM flows in the workspace) and clarifies what a 'flow' is. It also distinguishes itself from flows_get by explicitly stating the step-by-step contents are NOT included, so an agent can separate the two list/detail siblings without opening either schema.

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

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

Gives concrete usage contexts ('what flows do I have', 'is my flow live', 'is anyone getting through it'), which maps well to likely intents. It does not explicitly name flows_get as the alternative for step contents, though the exclusion note implies it.

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

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

Annotations already declare destructiveHint=false, and the description reinforces this with concrete behavioral detail: it stops answering new messages immediately, retains all steps, is fully reversible via flows_publish, and is always permitted. This adds real value beyond the annotations, though it says nothing about what the call returns or any rate limits.

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

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

Front-loads the core action, then layers reversibility, permission posture, and usage guidance in short sentences. Each sentence carries information, though the closing clause about there being no delete tool is slightly tangential for a 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 single-parameter toggle with no output schema, the description covers state effects, reversibility, and permission posture, which is everything an agent needs to call it correctly. No material gap remains.

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

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

Only one parameter, flowId, and schema description coverage is 100%, so the schema fully documents it. The description implies which flow is being acted on but adds no format or lookup guidance beyond the schema, making the baseline 3 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 ('Switches a DM flow off') and immediately differentiates itself from siblings by naming flows_publish as the reverse operation and noting no delete tool exists. An agent can distinguish this from flows_update or flows_publish without opening any schema.

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

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

Explicitly says when to use it ('when someone asks to stop, disable or remove a flow'), names the tool that undoes it (flows_publish), and states the exclusion that no deletion tool exists. Both the when and the alternatives are 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?

Annotations only declare readOnlyHint=false and destructiveHint=false. The description goes well beyond that: it discloses reversibility, the two distinct refusal modes (unfinished steps, live-flow plan limit), the rationale for the silent-failure rule, and the important fact that a refusal leaves state unchanged so the user can retry. Only auth/permission behavior is unstated.

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

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

Front-loaded with the action and its effect, then the reversal path, then the failure modes. Every sentence adds operational value, though phrasing like 'a sentence worth repeating' is slightly editorial and could be tightened.

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

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

For a single-parameter mutation with annotations covering the safety profile and no output schema, the description is nearly complete: action, effect, reversal, and failure conditions are all covered. The missing piece is permission/auth requirements.

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 there is a single required 'flowId' parameter, so the schema already carries the parameter semantics. The description adds nothing about the id format or where to obtain it, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Switches a DM flow on') plus the concrete effect (it will answer matching direct messages). It explicitly names flows_pause as the counterpart, so an agent can separate this from the other flows_* siblings without opening a schema.

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

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

Names the alternative for the reverse operation ('Reversible with flows_pause') and lays out the two conditions under which the call is rejected. It gives clear context for when the tool applies, though it doesn't spell out prerequisites like required scopes or trigger configuration.

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, but the description adds substantial context beyond them: omitted steps are deleted, HookSend validates and refuses the whole write atomically ("nothing is half-saved"), edges are auto-derived, saving never sends messages and a live flow updates the instant it returns. These are the exact behavioral traits an agent needs for a destructive full-replace call.

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

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

Front-loaded with the critical warning ("THIS REPLACES THE ENTIRE FLOW") and organized into purpose, step model, three gotchas, a worked example, and save semantics. It is long, but for a destructive full-replace tool with 17 step kinds the length is largely justified; a few of the gotchas overlap schema field text.

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, yet the description covers what the agent needs: atomic validation behavior, canvas-only step kinds, publish gating, flowId semantics, and a concrete example payload. Nothing material is missing for correct invocation of a complex destructive 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, but the description adds a conceptual model beyond the field docs: how straight-through steps use `next` vs branching steps naming targets, how a conversation terminates (end/handoff/jump), and the wait/24-hour Instagram constraint. This framing meaningfully exceeds what the per-field schema text conveys.

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

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

States a specific verb and resource ("Writes the steps of a DM flow") and immediately scopes it ("the whole conversation, in one call"), then flags the destructive scope in caps. An agent can distinguish it from flows_update, flows_create, and campaigns_set_steps without opening a schema.

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

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

Gives explicit when-to-call guidance: call flows_get first unless the flow was just created by flows_create and holds only the starter trigger/reply, and send back the steps with changes folded in ("Read the flow, do not remember it"). It also states when-not to use it — steps needing a photo (cards) or the customer's webhook address are built on the canvas, not here.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds genuinely new behavioral context: the list is fixed and built into HookSend, no customer account is touched, and nothing is charged. It does not describe the returned shape, but the safety profile is more than adequately 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?

Front-loads the purpose, then the workflow guidance, then the side-effect reassurance, in four compact sentences. Nothing is repeated from the title or restated tautologically.

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-argument read tool with no output schema, the description supplies what an agent needs: what it returns, how to consume the id, and that it is side-effect free. Only the precise content/shape of each template entry is left implicit, which is minor given no output schema is declared.

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

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

Zero parameters, so the baseline is 4 and the schema already declares that it takes no arguments. The description adds cross-tool value by explaining what the returned template id is used for in flows_create, which the empty schema cannot convey.

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

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

States a specific verb and resource ('Lists the ready-made flows') and immediately ties its output to a sibling's parameter ('the id flows_create takes as its template'). An agent can distinguish it from flows_list, flows_get, and flows_create 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 sequencing ('Call this before flows_create whenever the customer describes something a template already does') and names the follow-up call ('then flows_get the new flow'). It also states when not to bother writing from scratch, which is a real routing decision.

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 beyond the annotations by disclosing that the operation is reversible ('Reversible by calling it again with the old value') and that it is 'free of any plan check' — both are non-obvious behavioral traits for a write tool that the destructiveHint=false annotation alone does not convey. It does not describe permissions or what the response returns.

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

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

Three sentences, no filler: capability list first, sibling exclusion second, reversibility/cost third. Every sentence carries information an agent needs.

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

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

Covers scope, the sibling boundary, reversibility and the absence of a plan gate for a mutation tool with no output schema. The main omission is any mention of required permissions or account-scope preconditions, which an agent may need to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description maps each capability to a parameter (rename, reassign account, change re-entry behavior), adding intent-level meaning on top of the already detailed schema text. The instagramAccountId=null semantics are left entirely to the schema.

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

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

States a precise verb set and resource ('Renames a DM flow, moves it to a different connected Instagram account, or changes what happens when somebody triggers it a second time') and explicitly disambiguates from the sibling flows_set_steps. An agent can distinguish it from flows_create, flows_pause or flows_set_steps without opening any schema.

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

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

Explicitly routes step-editing work to flows_set_steps ('It does not change the flow's steps'), which is a clear when-not-this-tool rule. It gives no guidance on ordering versus flows_publish or flows_create, but the primary boundary with the closest sibling is 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 mark it read-only and non-destructive, but the description adds substantial behavioral detail beyond that: it reads live from Instagram, runs every enabled rule, is slower than other tools, covers up to 500 comments, scores only the first 150 with AI rules, reports unscored comments as aiNotScored, returns account-authored comments as KEEP, and warns that read and flagged counts will not add up. It also states that nothing here counts against plan limits.

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 read-only preview behavior, then layers in necessary caveats about coverage, scoring, KEEP comments, and plan limits. Every sentence adds operational context for a tool with unusual counting behavior, and none appears redundant.

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

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

Given no output schema and only read-only annotations, the description compensates fully by explaining return semantics (aiNotScored, KEEP), scope limits, live-read behavior, and how counts may differ. An agent has enough context to call it correctly and interpret the 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 schema already documents mediaId, accountId, and limit thoroughly. The description does not add parameter-specific syntax or defaults beyond what the schema provides, 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 states a specific verb and resource: it reads existing comments on a customer's post and reports what Comment Guard's current rules would do, without modifying anything. It also distinguishes itself from guard_cleanup_run by explaining that this is the source of comment ids for that tool, so an agent can tell them 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 clearly frames the tool as a required preview step before guard_cleanup_run, saying a sweep is always shown to the customer before it is run. That gives strong context for when to use it, but it does not explicitly state when not to use it or name other guard siblings as alternatives.

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

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

Annotations already flag destructiveHint=true, but the description goes well beyond them: it spells out that DELETE is permanent and unrecoverable on Instagram, that even HIDE is visible to the commenter, that work happens asynchronously in the background, that concurrency is limited to one sweep per account, and that no plan check applies. This is exactly the operational context an agent needs before an irreversible action.

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

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

Front-loads the action and its scope in the first clause, then layers risk, prerequisite, and limits. Every sentence carries distinct operational weight — nothing is filler, including the plan-check note.

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

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

For a destructive mutation with no output schema, the description covers risk, prerequisites, batch limits, and concurrency. It does not address partial-failure behavior (e.g., some ids invalid) or what the call returns, which is a minor remaining gap given no output schema exists to define the response.

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

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

Schema description coverage is 100%, so the enum semantics for action, the confirm flag, and the 500-item cap are already documented in the schema. The description reinforces the permanence of DELETE and the confirmation step but adds no syntax or format detail beyond what the schema supplies, so the baseline 3 applies.

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

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

States a specific verb (hides or deletes) plus resource (existing comments on a post) and scope (one sweep, in the background). It also implicitly distinguishes itself from the sibling guard_cleanup_preview by telling the agent to source comment ids from that preview rather than calling this blind.

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

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

Gives explicit prerequisites and ordering: fetch ids from a cleanup preview first, show the customer the list or count before confirming, and note that only one sweep per account runs at a time so a second call is refused. That is clear when-to-use and when-it-will-fail guidance rather than inference.

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

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

Annotations already declare a safe read, yet the description still adds substantial behaviour: the full verdict vocabulary, the fact that WOULD_HIDE/WOULD_DELETE mean the comment was never touched, that FAILED means Instagram refused the action, and the 48-hour text-retention window that makes older rows incomplete. This is exactly the context an agent needs to interpret results honestly.

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

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

Front-loaded with what the tool returns before going into verdict semantics, and every clause carries information since no output schema exists to carry the return shape. It is long, but the enumeration of verdicts and retention caveat are load-bearing rather than 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 takes on the full burden of describing the return payload — handle, comment, verdict, deciding rule, confidence, per-verdict counts, rules fired in the last day, and repeat handles — plus the data-retention caveat. Nothing an agent needs to interpret the response is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by mapping the filter enum values to concrete verdicts — notably that 'watch' corresponds to WOULD_HIDE/WOULD_DELETE, which the enum label alone does not convey. It also explains the default scope of instagramAccountId (whole workspace when omitted).

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

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

Names a specific verb (reports what Guard decided), a specific resource (recent comment decisions) and a scope (one Instagram account, newest first). An agent can distinguish it immediately from guard_rules_* (rule management) and logs_recent (generic activity log) without opening a schema.

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

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

Usage is implied rather than stated: this is the moderation-log reader, and the description justifies why kept comments appear ('a moderation log that showed only removals gives no way to tell quiet from broken'). It never names an alternative tool or an explicit when-not-to-use, and the only routing guidance ('leave it out to cover every account') is attached to a parameter rather than to the tool.

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

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

Annotations already declare readOnlyHint=false / destructiveHint=false, so the safe-create profile is covered; the description usefully adds the off-by-default behavior, the 60-rule ceiling with a repeatable error sentence, and the permission requirement. However it does not describe the response (returned rule id/shape), so the add-on value is real but not comprehensive.

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

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

Front-loaded with what the tool does, then constraints and safety in descending priority. Dense but each sentence carries a distinct fact; the closing sentence on the rule limit and permissions is slightly trailing but not wasteful.

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

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

For a 12-parameter mutation tool with no output schema, the description covers the critical facts an agent needs: the rule is inert until enabled, deletion is irreversible, quota and permission limits, and the sibling that activates it. No meaningful gap remains.

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, including all three enums, is already documented in detail. The description paraphrases the kind-to-field relationship (words/prompt/pattern) and the permanence of DELETE, but adds no semantics the schema does not already carry, so the baseline 3 applies.

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

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

States a specific verb and resource ('Writes a new Comment Guard rule for one Instagram account') and enumerates the three matching modes (WORDS, PROMPT, REGEX), which cleanly separates it from guard_rules_update, guard_rules_delete and guard_rules_set_enabled.

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

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

Explicitly names the follow-up tool and condition ('guard_rules_set_enabled switches it on once the customer has agreed'), warns to disclose the action first, and states prerequisites (admin/owner only, 60 rules per account). Nothing about when-to-use is left to inference.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantially more: irreversibility with the concrete loss ('words, description or pattern... gone and would have to be written again from scratch'), the hard restriction on built-in rules including the refusal behavior, the permission requirement, and a confirmation workflow. This goes well beyond the annotation payload.

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

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

Front-loaded with the action and its irreversibility, then the preferred alternative, then restrictions and permissions, then the UX confirmation step. Every sentence carries distinct operational value; there is no filler or repetition of the title.

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

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

For a destructive two-parameter mutation with no output schema, the description covers the safety profile, the recommended alternative, the failure mode (built-in rules), authorization, and the confirmation requirement. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so ruleId and confirm are already documented, including that ruleId comes from guard_settings. The description adds no syntax or format detail beyond the schema, and the 'read the rule's name back before confirming' instruction is workflow rather than parameter semantics. Baseline 3 is correct.

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

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

States a specific verb and resource ('Deletes one of the customer's own Comment Guard rules') and implicitly scopes it against guard_rules_create/update and guard_rules_set_enabled, which the description names directly. An agent can distinguish this from every sibling without opening a schema.

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

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

Explicitly tells the agent to prefer guard_rules_set_enabled with enabled false, and explains why ('a rule that is switched off stops being applied immediately, keeps everything in it') plus the user intent that selects it ('what somebody asking to "get rid of" a rule almost always means'). It also states when the tool cannot be used at all (built-in rules) and who may call it (admin or owner).

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

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

Annotations already flag destructiveHint=true, but the description adds real consequence detail: an enabled rule deletes future comments permanently from Instagram, deletion cannot be undone, hence confirmation; switching off is immediate and safe. It also discloses no plan check applies, going well past the safety 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?

Purpose is front-loaded and every clause carries weight (consequence, confirmation, off-is-safe, plan check). It is fairly dense with em-dash clauses, slightly heavier than necessary, but no wasted sentences.

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

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

For a destructive, non-read-only mutation with no output schema, the description covers the irreversible consequence, the confirmation requirement, the safe direction (off), and the billing exception. Nothing an agent needs to call this safely is missing.

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

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

Schema coverage is 100% and all four parameters (ruleId, enabled, confirm, accountId) are already documented in the schema. The description adds only implicit framing around confirming and which rule, so baseline 3 is correct.

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

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

States a specific verb (switch on/off) and resource (one Comment Guard rule), and the 'one rule' scoping distinguishes it from guard_rules_create/delete/update siblings. An agent can tell what it does 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 clear operational guidance: confirm with the customer first, tell them which rule and whether it hides or deletes, and notes 'No plan check applies.' It doesn't explicitly name alternative tools (e.g. guard_rules_update for changing a rule's action), so it stops short of full when/when-not 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 flag destructiveHint=true, and the description substantially enriches that: it explains which changes are reversible, why confirmation is required (DELETE on an already-enabled rule permanently removes matched comments with no recovery), and that built-in rules ignore name/words fields. This is exactly the beyond-annotation context the rubric rewards.

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

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

Front-loaded with the core action and the destructive exception is clearly signposted. It is dense across five sentences and the 'Tell the customer what the rule will do before confirming' sentence is more workflow instruction than tool semantics, but no sentence is filler.

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

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

For a 13-parameter mutation tool with no output schema, the description covers the safety profile, reversibility, confirmation trigger, permission model, sibling routing, and built-in rule edge cases. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is 100%, so the schema carries the per-field detail and the baseline is 3. The description adds framing value by grouping the 13 parameters into conceptual categories (name, what it looks for, what it does, which posts) and flagging that built-in rules ignore the name/matching fields, going slightly 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 opens with a specific verb (changes) and resource (an existing Comment Guard rule) and enumerates the four editable dimensions (name, matching criteria, action, watched posts). It distinguishes itself from siblings by explicitly naming guard_rules_set_enabled as the tool that toggles rules on/off.

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

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

Explicit routing: 'It cannot switch a rule on or off — guard_rules_set_enabled does that,' plus the rationale for the separation. It also states the permission prerequisite (admin or owner) and the confirmation workflow, so an agent knows when this tool applies and when it does not.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: watch-only mode is explained as recording intent without touching comments, and it notes that AI-dependent rules become inert once the AI allowance is exhausted, which is a non-obvious operational constraint an agent would otherwise miss.

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 opening clause states the scope immediately and the usage phrases are tacked on at the end, so it is front-loaded. The first sentence is a long comma-separated enumeration that is dense but each item is a real returned field, so little is wasted; only slight trimming of the field list would tighten it.

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

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

There is no output schema, so the description correctly carries the burden of describing the return shape, and it does so thoroughly with the enumerated configuration fields. The one material gap is the account-fallback behavior, where description and schema disagree, leaving the agent unsure whether omitting the id returns one account or all accounts.

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

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

Schema coverage is 100% and the parameter is fully documented, so the baseline would be 3. However, the description's statement that omitting the account 'answers for the workspace's first connected account' directly conflicts with the schema description, which says leaving it out 'covers every account in the workspace.' This contradiction adds confusion rather than meaning, so it scores below 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 names the exact resource (Comment Guard configuration for one Instagram account) and enumerates the concrete fields returned: on/off state, watch-only mode, AI rule enablement and confidence threshold, protected users, allow lists, per-rule action and enabled flag, plus the AI allowance. This level of detail cleanly separates it from guard_settings_update (writes), guard_rules_* (rule CRUD) and guard_recent_decisions (decision log) without opening any schema.

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

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

It supplies three natural-language trigger phrases ('is Comment Guard on', 'what is it set to do', 'why did it not catch this') and states the no-argument behavior, which is solid context for selecting the tool. It stops short of explicitly naming alternatives or when-not-to-use conditions (e.g. 'use guard_recent_decisions for the actual decision history'), so it is clear but not fully 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?

Beyond the annotations, it discloses the real risk model: only passed fields change, everything is reversible on its own, but enabling Guard hands comments to live rules and a DELETE rule removes comments permanently from Instagram. It also notes the AI allowance dependency and the admin/owner authorization requirement.

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 opening sentence is long but front-loads the scope, and subsequent sentences add privileged operational context (reversibility, permanence, prerequisite, permission) with little waste. Slightly dense, but every clause earns its place.

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

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

For a 14-parameter mutation tool with no output schema and minimal annotations, the description supplies the missing safety, permission, prerequisite, and rollback context an agent needs before invoking. Nothing essential to correct invocation is omitted.

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 carries the bulk of parameter documentation and baseline is 3. The description adds framing value by grouping parameters by intent (allow-lists, protected parties, AI certainty) and by positioning watchOnlyHours and enabled in operational terms, though it does not add syntax the schema lacks.

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 (changes) and resource (Comment Guard settings) and enumerates the exact aspects it controls: on/off, watch-only, AI rules and confidence, protected parties, and allow-lists. It is clearly distinguishable from siblings like guard_rules_update or guard_settings.

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

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

It gives explicit when-to-use guidance and prerequisites: consult guard_settings for live rules before enabling, use watchOnlyHours as the cautious way to start, and only admins/owners may change settings. It also recognizes the nervous-customer scenario and the alternative ramping 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds important behavioral context: it reads live from Instagram, is slower than most tools, covers one account at a time, and returns only short excerpts. It also explains the meaning of the handedOverByFlow, flowNotice, and cameFrom flags, which is valuable for interpreting 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?

The purpose is front-loaded and every sentence mostly earns its place by explaining return fields, flags, and limitations. However, the description is long and uses dense semicolon-linked clauses rather than a more scannable structure, so it is informative but 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 no output schema and only two simple annotations, the description provides a thorough account of what rows represent, what the key flags mean, what is not included, and which sibling to call for full messages. It also covers the live-read performance trade-off and single-account scope, making it complete for correct invocation.

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

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

Schema description coverage is 100%, so the limit and instagramAccountId parameters are fully documented in the schema itself. The description mentions one account at a time and most recently active first, but does not add parameter-level syntax or constraints beyond what the schema already provides; baseline 3 is appropriate.

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

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

The description states a specific verb (read/list) and resource (Instagram direct message conversations on a connected account), with ordering and key fields. It clearly distinguishes itself from inbox_thread for actual messages and from referrals_overview for the affiliate programme, so an agent can identify the right tool without opening schemas.

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

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

It gives explicit use cases such as 'what is in my inbox', 'who has written to me', 'is anyone waiting for a reply', and 'which of my ads are people messaging me from', plus finding thread and person ids for other inbox tools. It also names the alternative inbox_thread for actual message content and clarifies the relationship to referrals_overview, leaving little to inference.

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

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

Annotations already flag destructive/not-readOnly, but the description adds substantial context beyond them: the message cannot be unsent, edited or recalled; it consumes one unit of the workspace's monthly DM allowance and HookSend refuses when exhausted; and automatic replies pause for that person afterward. This is exactly the behavioral disclosure an agent needs before a destructive send.

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

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

Front-loaded with what the tool does and its irreversible nature, and nearly every sentence earns its place. Slightly long, with some overlap between the confirmation guidance and the schema's confirm 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?

No output schema exists, and the description covers the full calling context: identity of the sender, source of personId, the irreversible-send constraint, rate/allowance gating, the 24-hour window, and the confirmation workflow. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds marginal value by reinforcing the confirm semantics ('get their agreement, before confirming') and restating the personId source, though much of that duplicates the schema text.

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

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

States a specific verb+resource+scope: sends an Instagram DM from a connected account to one person as a reply in an existing conversation. It is clearly distinguishable from siblings like inbox_conversations and inbox_thread, which only read.

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

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

Explicit when-to-use and prerequisites: get personId from inbox_conversations, confirm with the customer first, the 24-hour reply window, and the monthly DM allowance gate. It also names account_usage as the place to check remaining allowance.

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

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

Annotations already declare a safe read, but the description adds substantive behavior: Instagram serves only recent history (~20 messages, no older ones), long messages are truncated, and the content is private and must be reported only to the account owner. That is real context beyond the annotations, though nothing is said about whether the returned order interacts with the limit window.

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

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

Front-loaded with what is returned, then usage, then identifier plumbing, then behavioral caveats and the privacy warning. Four dense sentences; the privacy sentence is arguably a slight expansion but it is operationally load-bearing, so nearly 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?

With no output schema, the description does the job of describing the return shape (messages with sender and timestamp) and the truncation/recency limits. Missing nothing critical for calling it, though a note on pagination or what happens if the threadId is stale would fully close the loop.

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

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

Schema coverage is 100%, so every parameter (including the 50-cap on limit and the default account fallback) is already documented in the schema. The description only reinforces the threadId sourcing, adding no new semantics. Baseline 3 applies.

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

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

States a specific verb+resource ('The messages of one Instagram direct message conversation') plus return shape ('oldest first, each with who sent it and when'). This is clearly distinct from inbox_conversations (list threads) and inbox_send_reply (write), so an agent can route 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?

Names the sequencing ('Use it after inbox_conversations') and the triggering intents ('what a particular person said, what was already answered, or wants help drafting a reply'). It also tells the agent where the required identifier comes from, which is explicit when-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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond them: it reads live from Instagram, is slower than the other tools, and covers one account at a time.

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

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

Three sentences, front-loaded with what it returns, then when to use it, then the operational caveat. Given there is no output schema, enumerating the returned fields earns its space rather than wasting it.

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

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

With no output schema, the description correctly carries the burden of describing return fields, and it also discloses latency and per-account scope. Nothing material is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so limit and instagramAccountId are already documented with ranges and sourcing. The description adds the 'newest first' ordering and the single-account scope, though the schema's own parameter text largely duplicates these points.

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

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

The description names the resource (posts and reels on a connected Instagram account), the shape of the result (caption, media type, publish time, link, likes, comments) and the ordering (newest first). An agent can immediately tell this is the read-only listing tool and distinguish it from the per-post stats sibling.

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

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

It gives three concrete triggering scenarios ('what have I posted lately', finding the best performer before campaign placement, and fetching the post id that campaigns_create needs). It stops short of stating when NOT to use it, e.g. reaching for instagram_post_stats when per-post detail is wanted.

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

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

Annotations already cover the read-only safety profile, and the description layers on non-obvious behavior: it is the slowest tool because Instagram reports per-post (ten posts = seconds, fifty = most of a minute), and it discloses the permission requirement plus the failure mode (empty values with insightsAvailable=false meaning 'not measured, not zero'). This is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the deliverable, then usage, then performance cost, then the permission caveat. Every sentence carries unique information and none is wasted despite the length.

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

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

With no output schema, the description carries the return-value burden and does so fully: field list, row granularity, aggregate totals, follower count/history, and the insightsAvailable sentinel. Nothing an agent needs to call it correctly or interpret 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 description coverage is 100%, and the count parameter's own schema text already explains the per-request cost rationale, so the description adds little parameter syntax beyond the schema. The permission note loosely relates to the account parameter but is not parameter-specific. Baseline 3 applies.

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

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

States a specific verb and resource with the exact returned fields (views, reach, likes, comments, saves, shares, one row per post, totals, follower count and history). It explicitly distinguishes itself from the sibling instagram_posts, which 'only tells you what exists', so an agent can route correctly without opening a schema.

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

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

Names concrete triggering questions ('which post did best', 'how is my reach', picking a post for a campaign) and gives the alternative (instagram_posts) plus the scoping rule to request the fewest posts that answer the question. When-to-use and the tradeoff are both explicit.

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

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

Annotations cover the read-only/non-destructive safety profile. The description adds real behavioral context beyond that: it reads live from Instagram rather than a cached copy, covers one account at a time, and discloses the null-vs-zero follower edge case. It also carves out explicitly what it does NOT return (per-post views/reach/saves). Loses a point only for not describing error/rate-limit behavior on a live external call.

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

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

Front-loads the purpose well, but it is a long run-on collection of clauses. The sibling contrast, null behavior, exclusion of per-post stats, and the aside about the reports screen all share one unwieldy sentence. Information is valuable but could be structured more tightly.

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

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

No output schema and only one param, so the description carries the return-shape burden and does so by naming the returned fields, the null edge case, and the explicit exclusion of per-post stats. An agent has enough to call it correctly and interpret the result; only error-path detail is absent.

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

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

Schema description coverage is 100% and the single parameter is already fully documented in the schema, including the default-first-account behavior and the reference to account_instagram_accounts. The description adds no parameter detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource: fetches the live Instagram profile of a connected account, and explicitly enumerates the returned fields (handle, display name, follower count, profile picture URL). It distinguishes itself from the sibling account_instagram_accounts by contrasting live-from-Instagram vs stored copy.

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

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

Gives concrete when-to-use triggers ('how many followers do I have', 'whose account is this', 'wants the picture', handle may have changed since connection) and names the alternative tool with the condition that selects it. Also states the explicit scope limit of one account at a time.

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 it is a non-destructive write, but the description adds real behavioral context: indexing happens immediately, the document becomes usable by the AI for DMs, the operation is reversible via the knowledge screen, and refusals carry a reason. That goes well beyond what the structured fields expose.

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 action and the text-or-url rule are front-loaded, and nearly every sentence carries a distinct constraint (indexing, reversibility, plan refusal, PDF limitation). It drifts slightly across the middle sentences, but nothing is filler.

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

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

For a mutation tool with no output schema, the description covers the full picture: what happens after the call, how it can be undone, what failure modes occur, and which inputs are out of scope. 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 description coverage is 100%, so each parameter is already documented. The description reinforces the text/url exclusivity and the no-file constraint, but adds little syntax or format detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Adds one document to a knowledge base') and immediately scopes it to the two supported sources (pasted text or a fetched web page). An agent can distinguish this from knowledge_documents, knowledge_create, and knowledge_update 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 mutual exclusion ('Pass either text or url, not both') and explicit when-not routing: PDFs and files must go through the dashboard, and plans without knowledge bases are refused. These are exactly the conditions an agent needs to avoid a failed call.

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/destructiveHint=false, so the safety profile is covered. The description adds real value by enumerating what is reported (AI-disclosure line, message splitting, quiet-period, knowledge bases count, remaining credits) and the per-account (not per-workspace) scoping. It omits return format/pagination, but for a read tool this is solid.

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

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

Purpose is front-loaded and the dense middle sentence packs many returned fields efficiently. It is long and list-heavy, but each clause names a distinct setting rather than padding, so it earns most of its length.

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

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

With no output schema, the description compensates by spelling out the returned settings and the per-account scoping, plus the routing hint to account_instagram_accounts. It stops short of describing the response shape or error behavior, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100% and the single parameter already documents that the id comes from account_instagram_accounts and is required because settings are per-account. The description largely restates that, adding little beyond the schema, so the baseline 3 applies.

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

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

States a specific resource (AI reply settings) with a clear read verb and precise scope ('for one connected Instagram account'), and enumerates the concrete settings it returns. It is clearly distinguishable from the write sibling knowledge_ai_settings_update.

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

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

Explicitly says to ask for the account in question, names account_instagram_accounts as the source of ids, and directs the agent to call this before knowledge_ai_settings_update to report current state. When-to-use and the alternative are both named.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds substantially more — patch semantics ('Only the fields you pass are changed'), full reversibility, the credit-spend side effect, the fact that enabling 'Answer every DM' causes the AI to answer DMs no campaign/flow/keyword handled, and an authorization requirement. None of this 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?

Front-loaded with the list of settings, then moves to constraints, prerequisites and warnings in a logical order, and every sentence carries information. The opening sentence, however, is a long run-on enumerating five settings, which slightly hurts readability.

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 mutation tool with no output schema, the description covers what changes, patch semantics, reversibility, credit cost, authorization, prerequisite read, and refusal conditions. Nothing an agent needs in order to call it safely is missing.

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

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

Schema description coverage is 100% and each parameter already carries a detailed description (including enum-like constraints for aiHumanPauseMinutes and clear semantics for the nullable strings). The description's high-level enumeration of the settings largely restates what the schema documents, so baseline 3 applies; only the 'fields you pass are changed' patch semantics is genuinely 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 and resource (change AI reply settings for one Instagram account) and enumerates exactly which settings are affected: 'Answer every DM', disclosure line and text, short-message splitting, writing style, and human-pause duration. It also implicitly distinguishes itself from the sibling read tool knowledge_ai_settings, which it names.

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

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

Explicit when-to-use and prerequisites: 'Read knowledge_ai_settings first and tell the customer what is set now', warn the customer about AI credits before enabling 'Answer every DM', and note that only an admin or owner may call it. It also names the condition under which the tool refuses (plan without knowledge bases), which is a genuine exclusion.

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

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

Annotations only declare this is a non-read-only, non-destructive mutation. The description goes well beyond that: it discloses the paid-plan constraint, the important edge case that the base is still created but saved switched off when at the live limit, that the confirmation message states this, that the agent should relay it, and that no messages are sent to anyone. This is unusually rich 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?

One front-loaded paragraph: purpose first, then the follow-up route, then the plan/limit edge case. Every sentence carries information, though the instruction to 'tell them it is there' slightly restates the preceding clause about the confirmation saying so.

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

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

With no output schema, the description compensates by describing what the confirmation contains and what state the created base ends up in. For a simple 3-param create tool with annotation safety hints, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters (name, description, instagramAccountId) are already documented in the schema. The description adds no syntax, format, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('Creates an empty knowledge base') and immediately defines the domain concept ('the set of documents HookSend's AI answers direct messages from'), which distinguishes it from knowledge_add_document and knowledge_update. The word 'empty' also disambiguates it from tools that populate a base.

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

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

Explicitly routes the agent to the follow-up tool ('Add documents to it with knowledge_add_document') and gives a clear conditional rule for the paid-plan slot limit and what to tell the customer. It lacks a 'do not use this when...' exclusion versus siblings like knowledge_update, but the usage context is otherwise unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by describing the returned document fields, sort order, indexing states, and failure reason, though it does not discuss pagination or permission requirements 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 two tightly written sentences with no filler. It front-loads what the tool returns and then immediately follows with concrete usage guidance.

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

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

There is no output schema, so the description carries the burden of explaining return values, and it does so thoroughly: title, type, indexing state, length, passage count, and failure reason. Combined with complete input schema coverage and read-only annotations, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so both knowledgeBaseId and limit are fully documented in the schema. The description does not add parameter-level meaning beyond what the schema already provides, which is the baseline when schema coverage is high.

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

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

The description clearly identifies the resource (documents inside one knowledge base) and the returned fields, including sort order and indexing states. It also distinguishes itself from knowledge_list by naming that sibling and the follow-up scenario in which this tool is used.

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 knowledge_list when the user asks what a knowledge base contains or why an upload is not used in answers. This gives both the alternative tool and the triggering conditions with 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?

With no output schema, the description carries the full burden of disclosing return semantics and does so richly: per-entry on/off state, keyword triggers, the subtle keywordsOnly rule ('Answer every DM' never uses it; no keywords means it never answers), connected account, document counts and indexing status. It also discloses the plan requirement and the live-base cap.

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 purpose and then packs return-field semantics and use cases efficiently. The keywordsOnly parenthetical is dense but earns its place; overall tight with little waste.

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

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

For a read-only listing tool with no output schema, the description is complete: it explains the shape of each returned entry, the trigger logic, and the plan constraint, so an agent can interpret results and decide when to call knowledge_documents next.

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

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

Schema coverage is 100% for the single limit parameter, so the schema already documents the default and maximum. The description adds nothing about limit syntax or ordering beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource ('Lists the knowledge bases in the workspace') and immediately defines what a knowledge base is (sets of uploaded documents the AI answers DMs from), which disambiguates it from siblings like knowledge_documents and knowledge_create.

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

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

Gives concrete use scenarios ('why isn't my AI answering', 'what have I uploaded') and explicitly routes to knowledge_documents for a base's id. It stops short of naming when NOT to use it versus a sibling, so it is clear context without exclusions.

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

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

Annotations only say non-read-only and non-destructive. The description layers on genuinely new context: PATCH semantics ("Only the fields you pass are changed"), reversibility ("every one of them can be set back"), a plan-limited failure mode for activation plus what the refusal reports, and the guarantee that switching off loses no documents.

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 purpose, then partial-update semantics, then the activation caveat and the disable-vs-delete advice — a logical order where each sentence carries weight. It is dense and the field enumeration partially duplicates the schema's own descriptions, costing a little efficiency.

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

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

For an 8-parameter settings update with full schema coverage and no output schema, the description supplies the operational facts an agent needs: partial semantics, reversibility, the plan limit that can reject activation, and the safe deactivation alternative. Nothing required to call it correctly is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented at the field level and the baseline is 3. The description restates the same field list without adding syntax, formats, or per-parameter constraints beyond what the schema provides.

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

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

Opens with a specific verb+resource ("Changes a knowledge base's") and then enumerates the mutable surface — name, description, keywords, keyword-only mode, fallback message, and active state. An agent can tell this is the settings-mutation tool distinct from knowledge_create or knowledge_add_document 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 one explicit routing directive — "use that rather than asking for a knowledge base to be deleted" — which steers the agent away from a destructive path. However, it never frames when to reach for this tool versus siblings like knowledge_ai_settings_update, so guidance is solid but not exhaustive.

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

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

Annotations already declare it a safe read, yet the description adds real context: newest-first ordering, that the response enumerates tags in use, and a firm data-handling constraint (personal data the customer owns, hand back only). It does not describe pagination limits 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?

Front-loads the core purpose and return contents, then guidance, then the privacy constraint. Dense but each sentence carries content; the cameFrom explanation is slightly verbose but still justified.

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

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

No output schema exists, so the description correctly compensates by describing the response fields and the tag list in the answer. Combined with the privacy note and usage cases, an agent has enough to call and interpret the 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 all five parameters are already documented with cross-references to campaigns_list and account_instagram_accounts. The description restates tag filtering and handle/email lookup but adds no syntax or format detail the schema lacks, so baseline 3 applies.

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

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

Names a specific resource (captured leads) with a concrete verb-like framing and enumerates the returned fields — handle, campaign, collection location, tags. An agent can immediately tell this apart from conversations or campaign tools.

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

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

Gives explicit usage scenarios ('show me my recent leads', 'how many leads did this campaign get', look up by handle or email) and a concrete routing rule for the cameFrom field (which ad/link produced leads). It stops short of naming alternatives to use when the user does NOT want lead data.

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 read-only and non-destructive; the description adds the crucial behavioral facts an agent needs: no date filter (must page and read timestamps), ordering (newest first), and the full semantics of each status including the Instagram hourly cap and monthly plan limit. This is well beyond annotation coverage.

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

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

Front-loaded with the resource and row shape, then the status glossary, then the routing advice. Dense but every sentence carries information; the status enumeration is long but genuinely needed because the enum values are opaque.

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 takes on the burden of describing the returned columns (time, campaign, handle, comment, keyword, outcome) and it does so fully, plus covers the filtering limitation and the alternative tool. Nothing an agent needs is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by explaining the meaning behind status values (SKIPPED_DEDUP, SKIPPED_PLAN_LIMIT, etc.) and the absence of a date filter, which changes how page/limit must be used. It stops short of explaining page/limit interplay explicitly since the schema already covers those.

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

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

States a specific resource (the send log) with explicit shape ('one row per comment or message HookSend acted on') and enumerates the returned fields. An agent can immediately tell this apart from stats_overview, leads_recent, and guard_recent_decisions.

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

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

Names two concrete use cases ('check whether something is actually being delivered', 'explain a particular failure'), states the limitation ('there is no date filter'), and routes to the alternative ('for weekly and monthly totals use stats_overview instead'). Full when/when-not/alternative coverage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real context beyond that: no personal details are returned because the route sends none, amounts are in ordinary currency units not paise/cents, and it is workspace-scoped with no account id. Return-shape disclosure is a useful addition.

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

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

Front-loads the purpose and the enumerated contents, then moves to usage triggers and caveats. The first sentence is a dense run-on list, but every clause carries distinct information about what is returned, 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?

With no output schema, the description compensates by spelling out the returned fields (code, link, counts, commission rate, earnings buckets, recent sign-ups with date and plan) plus the currency-unit and privacy caveats. An agent has everything needed to call and interpret it.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents limit fully (default 20, max 50, newest first). The description adds nothing about the limit parameter, so the baseline 3 applies.

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