fnlowl

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

Annotations already flag destructiveHint=true and openWorldHint=true, yet the description still adds real value: sending is timed and unattended, and the server performs no human-confirmation check, so the caller owns that gate. It stops short of saying whether activation is reversible or what happens to leads already mid-sequence.

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

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

Two sentences, both earning their place: the first defines the action and effect, the second escalates the risk. The consequence is front-loaded with zero filler.

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

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

For a destructive, no-output-schema mutation, the description supplies the key operational facts: emails will go out on a timer and no human-confirmation check exists server-side. The remaining gap is failure/reversal behavior for `sequenceId` (non-draft sequences, idempotency).

Complex tools with many parameters or behaviors need more documentation. 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 50%: `project` is documented in the schema, but the required `sequenceId` has no description anywhere. The description mentions no parameters at all, so it fails to compensate for the undocumented required field (e.g., that it must reference a draft rather than an active sequence).

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

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

"Activate a draft sequence" states a specific verb and resource plus the state transition (draft → active) and the downstream effect on lead enrollment. It is clear on its own, but it never names the inverse (pause_sequence) or the creator (draft_sequence) as siblings, so explicit differentiation is left to inference.

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

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

The phrase "so future matching leads are enrolled and may receive its emails" gives the agent the condition that makes this the right call, and the human-confirmation note signals a prerequisite to check first. There is no explicit when-not-to-use guidance or named alternative (e.g., pause_sequence to reverse 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?

Adds genuinely non-obvious behavior beyond the annotations: the call consumes an AI credit, which is a cost signal no structured field carries, and it clarifies the advisor can read live account objects. 'It is read-only' merely restates readOnlyHint=true (consistent, not contradictory), and latency or answer format is not disclosed, so it falls short of a 5.

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

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

Four sentences, front-loaded with purpose, then capability scope, then usage cues, then cost/caveat. Every sentence carries distinct information and the cheaper-alternative warning lands last where an agent will still read 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?

For a 2-parameter tool with no output schema, the description covers capability scope, cost, safety, and alternatives adequately. It does not indicate what the response looks like (prose answer vs. structured data) or how long it may take, which matters for an AI-backed call.

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

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

Schema coverage is only 50% (the `question` param has no description), so the description compensates by specifying 'plain English' and 'one self-contained question' — a real constraint telling the agent not to send follow-ups or rely on prior turns. The 2000-character cap and the project-scoping behavior are left to the schema.

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

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

States a specific verb and resource ('Ask the fnlowl Advisor a question in plain English') and then enumerates the exact knowledge domains the advisor covers (widgets, embed, sequences, campaigns, sending, credits, plans, MCP) plus the account data it can read. This distinguishes it clearly from the read_* and list_* siblings, which it explicitly references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 example phrasings ('how does X work', 'why is Y empty', 'what should I do next') that define the intended use class, and names the alternative with the selecting condition: 'a direct read tool is cheaper when the data needed is already known.' Both when-to-use and when-not-to-use are present.

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

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

With annotations already declaring readOnlyHint=false and destructiveHint=true, the description adds the key non-obvious trait: projects cannot be deleted from here, so creation is effectively permanent. It also tells the agent what is returned (the project id) and how it is propagated to subsequent calls. It does not mention permissions or 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?

Three short sentences, front-loaded with the action, then the return value, then the usage note, then the constraint. No filler.

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

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

No output schema, but the description covers the return (project id) and irreversibility. The gap is the complete absence of parameter guidance for a tool with 0% schema description coverage, leaving emoji semantics entirely undefined.

Complex tools with many parameters or behaviors need more documentation. 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 0% and there are two parameters (required `name`, optional `emoji`), yet the description never mentions either. The agent must infer that name is the project name and emoji is a display icon purely from field names and minLength constraints.

Input schemas describe structure but not intent. Descriptions should explain 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 project') and even defines the resource ('one more site or brand under the account'), plus the return value (its id). It doesn't explicitly differentiate from other create_* siblings, but the resource is unambiguous.

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

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

Gives downstream usage guidance (pass the returned id as the `project` argument or via x-fnlowl-project / FNLOWL_PROJECT) which implies when this is needed, but never says when to create a project versus working within an existing one or calling list_projects first.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation profile is covered. The description adds genuinely new behavioral context beyond the annotations: placeholder substitution rules ('a placeholder nobody supplies is replaced with nothing') and the fact that creation does not send. It does not cover what is returned (template id?) or duplicate-name 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?

Three tight sentences, front-loaded with the purpose and the required category values before the placeholder rules. The enumeration of category values is slightly redundant against the schema enum but reads as a quick reference 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?

For a 5-parameter mutation tool with no output schema and 20% schema coverage, the definition leaves gaps: no mention of the return value (presumably a template id needed for later update/send), no uniqueness or duplicate-handling guidance for 'name', and no note on required vs optional fields.

Complex tools with many parameters or behaviors need more documentation. 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 only 20%, so the description must carry more weight. It explains the placeholder convention for subject/body, which is real added meaning, but the category list merely restates the enum already in the schema, and the 'name' parameter is never explained (uniqueness, identifier usage).

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

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

Opens with a specific verb+resource: 'Create a transactional template.' The verb distinguishes it naturally from update_template and list_templates in the sibling set, though it never names those siblings explicitly. Purpose is unambiguous.

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

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

Adds a useful scope boundary — 'It creates the template only — sending needs a person' — which tells the agent creation does not trigger delivery. However, it never states when to create vs. reuse/update an existing template, nor does it name list_templates as a prerequisite check.

Agents often have multiple tools that could apply. Explicit usage 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 key behavior: widgets are created as drafts, the result includes an issues list for missing go-live requirements, publishing is a separate step, defaults apply when fields are omitted, and popups/bars load sitewide unless URL rules are supplied. This is rich behavioral context for a create tool.

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

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

The description is long but appropriately front-loaded: it starts with creation, draft state, issues, and publish separation before going into per-kind requirements. The dense single-paragraph format makes it harder to scan, but most sentences add necessary detail for a 58-parameter tool.

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

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

Given no output schema, sparse annotations, and minimal schema descriptions, the description is unusually complete for the main creation workflow and per-kind requirements. It still leaves gaps for advanced optional parameters and only briefly mentions the returned issues list rather than the full result shape.

Complex tools with many parameters or behaviors need more documentation. 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 only 2% schema description coverage, the description carries most parameter meaning and does so well for core and kind-specific fields, including nested shapes, defaults, enum-like choices, and formulas. However, many of the 58 parameters, such as layout, article, firstStep, popupWidth, reward fields, audienceRules, and questionRoutes, are not explained.

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

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

The description opens with a specific verb and resource: 'Create a widget in the current project.' It also identifies the six widget kinds and explicitly distinguishes this operation from update_widget and request_widget_publish, so an agent can separate it from sibling tools without inspecting schemas.

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

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

It explicitly routes post-creation fixes to update_widget and publishing to request_widget_publish, and explains that creation is always draft-only. It also tells the agent it can send only name and kind while the rest defaults, which is clear usage guidance.

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

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

Annotations already flag destructiveHint=true and openWorldHint=false, and the description goes well beyond them by explaining the real risk model: sending hits real inboxes, burns unrecoverable deliverability reputation, and cannot be undone. It also discloses automatic filtering of unsubscribed and bounced addresses, which is behavior an agent cannot infer from 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-loaded with the action and scope, then the safety context, then the parameter rule. The middle sentence about deliverability reputation is slightly rhetorical, but it carries genuine decision-relevant weight for an irreversible-adjacent operation, so it mostly 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?

Covers purpose, safety, and the one non-obvious parameter for a 5-parameter mutation tool with no output schema. The only gap is that it never says what comes back (e.g., a campaign id usable with update_campaign), which an agent would likely need for a follow-up call.

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

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

Schema coverage is only 20%, so the description must carry weight, and it does: recipientScope is defined as either "all" or a single widget id, and the auto-exclusion of unsubscribed/bounced addresses is a semantic detail absent from the schema. name, subject, and body are self-evident and need no elaboration.

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

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

States a specific verb and resource (create a campaign) plus a critical qualifier (AS A DRAFT, capitalized for emphasis). It also preempts the obvious next question by declaring that no sending tool exists, so an agent won't go hunting for one.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 bounds the tool's role in the workflow: draft here, a human sends from the dashboard, there is no send tool. That is strong when-to-use context. It does not, however, differentiate from the similarly named sibling draft_sequence, which an agent could confuse with this one.

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

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

Adds substantial semantics beyond the annotations: delays are standalone steps allowing back-to-back emails, branch paths resolve first-match-wins left to right, and a null-field filter always matches so belongs last. It doesn't disclose what is returned or whether the draft is inert until activated, but the structural rules are genuinely valuable.

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

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

Three dense sentences, front-loaded with the draft constraint, then steps, then branch semantics. No filler; every clause conveys a rule the 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?

With no output schema and a required-nullable widgetId, the description should say what widgetId means and what comes back (e.g. an id usable with activate_sequence). The nested steps/branch semantics are well covered, but these gaps leave an agent guessing.

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

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

Schema coverage is only 20%, and the description richly compensates for steps and branch (filter fields, ordering, allowed values). However widgetId — required and nullable — is left completely unexplained in both schema and description, and name's role is never addressed.

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

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

States a specific verb, resource and lifecycle state ('Create a sequence AS A DRAFT'), which implicitly routes the agent away from update_sequence and activate_sequence. It never names those siblings explicitly, so the differentiation is implied rather than stated.

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

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

The draft framing hints that activation is a separate later step, but there's no explicit 'use this when' or exclusion against update_sequence/create_template. Usage is inferable but not stated.

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

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

Annotations already declare this as a safe read-only operation, so the safety burden is covered. The description adds useful behavioral context by stating the sort order and clarifying that open/click numbers come from the sent-email ledger rather than a per-campaign counter, but it omits pagination or result-volume 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?

Two tight sentences with no wasted words. The scope and ordering are front-loaded, and the metric-provenance caveat follows immediately.

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

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

For a low-complexity, read-only listing tool with one optional parameter and no output schema, the description is nearly complete: it covers scope, ordering, status inclusion, and data provenance. It could be slightly stronger by mentioning result limits or pagination, but nothing essential is missing.

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

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

Schema description coverage is 100%, so the single optional 'project' parameter is already fully explained in the schema. The description's phrase 'in this project' slightly reinforces scope but does not add syntax or fallback behavior beyond what the schema already documents.

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

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

States clearly that it lists campaigns with their status, scoped to a project and ordered newest first. It is easy to separate from other list_* siblings by resource, but it does not explicitly differentiate itself from them (e.g., list_sequences, list_templates).

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

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

The description implies usage by naming the resource and scope, but it gives no explicit when-to-use guidance, no exclusions, and does not point to alternatives such as read_analytics or list_email_deliveries for related 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 already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new behavior: recipients are masked, and the two send counters differ because sentToday is a rolling 24-hour window while sharedTrial.sendsUsed is lifetime. It stops short of describing ordering, default page size, or what a record contains.

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

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

Four short sentences, front-loaded with purpose and privacy behavior, then usage, then the counter-disambiguation, then a one-line negative guarantee. Nothing is filler and no sentence repeats a structured field verbatim.

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

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

With no output schema, the description does meaningful work by naming two return counters and disclosing recipient masking, which an agent needs to interpret results. It still leaves the per-delivery record shape and pagination behavior implicit, but for a simple two-parameter read tool this is close to sufficient.

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

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

Schema coverage is 50%: the 'project' parameter is documented in-schema, but 'limit' carries no description anywhere, and the description never mentions it (no default, no ordering implication). The discussion of sentToday and sharedTrial.sendsUsed explains response fields rather than parameters, so it does not compensate for the gap.

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

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

States a specific verb and resource ('List recent email outcomes for this account') and enumerates the outcome states the listing surfaces, which is far more than a restatement of the name. It does not, however, distinguish itself from nearby read tools such as read_sending_status or read_integration_delivery_status that an agent could easily confuse it with.

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

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

'use this to diagnose queued, delivered, opened, clicked, bounced, complained, or failed mail' gives a concrete diagnostic intent that tells the agent when the tool applies. There is no explicit exclusion or pointer to the sibling status tools, so overlap with read_sending_status and read_integration_delivery_status remains 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?

Annotations already declare readOnlyHint, openWorldHint=false and destructiveHint=false, so safety is covered structurally. The description adds one genuinely new fact — 'Credentials are never returned' — which tells the agent the output is safe to surface without redaction, but says nothing about scope, paging, or connection states.

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

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

Two short sentences, zero filler, with the action and the security guarantee front-loaded. Nothing could be removed without losing 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 zero-required-param, read-only list tool with no output schema, the description covers what is listed and one key output property. A brief note on paging or which fields constitute 'health' would close the remaining gap.

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

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

Schema description coverage is 100% and the single optional 'project' parameter is already documented with a cross-reference to list_projects. The description adds no syntax or scoping detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('List native integration providers') plus what the listing conveys ('connection health'), which separates it from siblings like read_integration_delivery_status. It never explicitly names that sibling or read_plan_usage, so the differentiation is implicit rather than stated.

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

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

No guidance on when to call this versus the adjacent integration and delivery-status tools, and no prerequisites or exclusions. The agent must infer the trigger condition from the word 'list' alone.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that. Beyond the annotations it adds substantial context: 200 is a hard cap not a raiseable default, rows are ordered newest first, quality verdicts come from capture-time checks, and bad leads are stored but were never mailed.

Agents need to know what a tool does to the 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, then paging constraints, then the quality semantics. Dense but every sentence carries information an agent needs; no filler.

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

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

No output schema exists, so the description must convey what a row looks like; it names the quality field and its values but doesn't enumerate other row fields. For a list tool with annotated safety and clear paging, this is nearly complete.

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

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

Schema coverage is only 25%, so the description must compensate, and it does for limit (hard cap) and offset (paging semantics with example), plus the meaning of the quality enum values. The project param relies on its own schema description, which is adequate.

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

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

States a specific verb and resource (list captured leads), plus ordering (newest first) and scope (current project). It doesn't explicitly route against the sibling read_lead for fetching a single lead, so it stops short of a 5.

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

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

Gives concrete usage mechanics: the 200 cap is hard, offset paging is shown with a worked example (limit 50 + offset 50 returns leads 51 onward), and quality filters the list. It lacks an explicit when-to-use-this-vs-read_lead 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 cover read-only, non-destructive, closed-world, so the bar is lower. The description adds genuinely non-obvious behavior: results are credential-scoped, and the row flagged current reflects the call's existing scoping, with no current row when reads span the whole account.

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

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

Dense but front-loaded: purpose first, domain definition second, scoping mechanics last. The final sentence about the current row is slightly convoluted, but every sentence carries real information and nothing is padding.

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

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

There is no output schema, so the description must carry return-shape burden; it covers the id and the current flag but never states the other likely fields (e.g. name/slug/status). Otherwise it is complete enough for a zero-parameter discovery call.

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

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

This tool has zero parameters, so the baseline is 4. The description still adds value by explaining how the ids it returns are consumed by other tools (project argument, x-fnlowl-project header, FNLOWL_PROJECT).

Input schemas describe structure but not intent. Descriptions should explain 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 projects') plus scope ('this credential can act on'), and then defines what a project is in this domain. An agent can immediately distinguish it from create_project and from the other list_* 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?

Explains the practical follow-on: take an id and pass it as the project argument, header, or env var, and note that with neither, tools read across the whole account. That is strong when-to-use context, though it never explicitly says 'call this first to discover valid project ids' or when not to call 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 readOnly/openWorld=false/destructive=false, so the safety profile is covered. The description adds genuine context beyond that: a hard cap of 100 rows and oldest-first ordering, which an agent needs to reason about truncation and result ordering. It stops short of pagination or ordering-control guidance.

Agents need to know what a tool does to the 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 answer (who is enrolled and where), then the diagnostic use case. Dense but purposeful; the em-dash aside is slightly overloaded, though every sentence carries information.

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

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

With no output schema, the description does the work of describing the returned fields and the 100-row ceiling, which is substantial for a read-only list tool. The remaining hole is the all-optional filter combination — an agent cannot predict the result set when it passes no filters or both.

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

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

Schema coverage is only 33% — leadId and sequenceId are undocumented in the schema — and the description does recover both by naming them alongside their meaning. However, with 0 required parameters it never says whether the two filters combine, or what happens when neither is supplied, leaving the calling contract ambiguous.

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

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

Names the resource precisely (sequence enrollments), the two access paths (leadId or sequenceId), and enumerates the returned fields — status (active/finished/stopped), current step, next due date. This clearly separates it from list_sequences, which lists sequences rather than who is enrolled in them.

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

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

Gives an explicit use case — answering "why did this lead get, or not get, the follow-up" — plus interpretive rules (no enrolment means never enrolled; activating a sequence only enrols future leads). It never names a sibling alternative or states when not to use it, so it falls short of a 5.

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

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

The annotations already establish that this is a safe read-only, non-destructive operation. The description adds meaningful behavioral context about the returned data shape: it is bounded, linear, with at most one branch point and no nesting, rejoining, or parallel paths. It does not cover ordering or pagination, so it falls short of the richest disclosure.

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

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

Two sentences, neither padded, with the returned resource stated first and the bounded shape explained immediately after. The second sentence is dense but every clause carries useful structural 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 simple list tool with one optional parameter, read-only annotations, and no output schema, the description supplies the key missing context: the bounded shape of sequence results. It still does not describe ordering, pagination, or whether an omitted project means the connection default, but it is largely 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?

There is one optional project parameter, and schema coverage is 100%, so the schema already explains that it scopes the call to a project from list_projects. The description mentions 'this project' but does not add further semantics beyond the schema. This matches the baseline of 3 when the schema does the heavy lifting.

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

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

The description clearly identifies the resource as sequences in the current project and adds that steps and branch structure are included. It is specific enough to distinguish this from sequence mutation tools like activate_sequence or update_sequence, though it does not explicitly state a list verb or name an alternative.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention list_sequence_enrollments, update_sequence, draft_sequence, or any condition for choosing this read/list operation over them.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: built-in starters carry isCustom=false and cannot be deleted, which tells an agent something about the data returned and a downstream constraint. It stops short of covering pagination or result shape.

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

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

Two short sentences with no filler, and the scope statement leads. Slightly clipped to the point of omitting the action verb, which is a minor structural cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 ideally would sketch the returned fields or ordering; it only names one field (isCustom). For a simple single-parameter read tool this is adequate but not 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 single optional `project` parameter has 100% schema description coverage, explaining it comes from list_projects and overrides the connection default. The description adds nothing about it, but the schema already does the work, so baseline 3 applies.

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

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

The phrase "Transactional templates in this account" identifies the resource and scope, but never states the action (list/retrieve) explicitly, leaving the verb to be inferred from the name and title. It also does not differentiate itself from update_template, create_template, or other siblings that touch the same resource.

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

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

There is no statement of when to call this versus list_projects, list_campaigns, or the template mutation tools, and no prerequisites or exclusions. Usage is only implied by the tool name.

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint=false, so the safety profile is fully covered. The description contributes the ordering behavior (best-converting first), which is genuinely beyond the annotations, but says nothing about what metrics are included, whether the list is paginated, or how many widgets are returned.

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

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

Two compact sentences with the sort order front-loaded and the routing instruction second – good ordering. The opening phrase "The same numbers" is the one piece of wasted, ambiguous text, since it presumes unstated context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 burden of explaining the return shape falls on the description, and "the same numbers" does not tell the agent which metrics come back (conversions, views, conversion rate?). For a read-only analytics listing with one optional param this is workable but under-specified.

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

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

There is a single optional parameter (project) with 100% schema description coverage; the schema explains it references list_projects and overrides the connection default. The description adds nothing about parameters, which is acceptable given the schema baseline, but also adds no value.

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

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

"Per widget, best-converting first" identifies the resource and sort order, and the verb is implied by the tool name (list). However, "The same numbers" is a dangling reference to something the agent has no defined anchor for – presumably read_analytics, but that is never named – so what is actually being listed is only partly clear.

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

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

Explicitly gives the triggering question ("which magnet is working") and names the alternative tool with the condition that selects it ("where one widget's traffic came from"). The alternative is referred to as "widget_results" rather than the actual sibling name read_widget_results, which is a small but real lookup cost.

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

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

Annotations already cover safety (readOnly, non-destructive, closed-world), so the description's job is thinner. It still adds genuinely useful behavior: ordering ('newest last') and a content limitation ('summaries only'), naming the exact summary fields returned. It doesn't mention pagination or result caps, which is the remaining gap for a list tool with no output schema.

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

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

Two tight sentences; the scope and ordering come first, then the return-shape caveat, then the sibling redirect. Every clause 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?

For a single optional parameter, read-only list tool, this covers scope, ordering, and return granularity plus the sibling route. The one missing piece is volume behavior (pagination/result limits) on a tool with no output schema, which would matter if projects hold many widgets.

Complex tools with many parameters or behaviors need more documentation. 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 'project' parameter already documents that it runs the call in a different project. The description adds only the 'current project' default framing, which is already implied by the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (list every widget), scopes it to the current project, and distinguishes itself from the read_widget sibling by contrast. An agent can immediately tell this is a summary enumeration rather than a detail fetch.

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

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

Explicit routing: use this for the collection, use read_widget for a single widget's full content. That names the alternative and the condition that selects it, leaving nothing 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 readOnlyHint, destructiveHint=false and openWorldHint=false; the description adds value by confirming 'It changes nothing' and by describing the return payload ('returns the options for the user to answer'), which resolves what happens after the call. It still doesn't say whether the call blocks awaiting an answer or returns immediately for the caller to relay, which is the one behavior an agent most needs to know.

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

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

Three sentences, no filler: shape first, selection criteria second, side-effect/return contract last. The em-dash examples are concrete and load-bearing rather than decorative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 small read-only, 3-parameter tool with no output schema, the description covers what the agent needs to decide and construct the call, and it explains the return in prose. The gap is the interaction model — whether the tool blocks for a user answer or returns control immediately — which matters for sequencing around this call.

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

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

Schema coverage is only 33% (only 'project' is documented in-schema), so the description must carry the rest — and it does, explaining that 'options' is a 2-4 item set whose entries carry a label, a one-line description, and an optional 'recommended' flag, which the schema leaves entirely bare. The 'project' parameter is covered by the schema itself, so combined coverage is effectively complete; the only miss is that 'question' is never explained.

Input schemas describe structure but not intent. Descriptions should explain 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 ('presents the user with a choice') plus the shape of the resource: 2-4 options, each with a label and one-line description, one optionally recommended. An agent knows precisely what the call does, though the nearest sibling (ask_question) is never named, so the boundary between multi-choice and open-ended asking must be inferred from the phrase 'decisions where reasonable options would build different things.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 ('which widget kind, what score ranges, what copy or trigger') and an implicit when-not ('nothing the user said settles it'), which tells the agent to skip this tool when the user has already decided. No explicit alternative is named, so the agent must infer that free-form gaps go to ask_question.

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

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

Beyond the destructiveHint annotation, the description discloses the key behavioral effect: moving to draft stops new enrolments and applies immediately. It also clarifies that reactivation is possible via activate_sequence. It does not fully specify what happens to already-enrolled leads or in-flight sends.

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

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

The definition is front-loaded with the operation and effect, then adds useful contrast with activate_sequence. It is slightly verbose with rhetorical phrasing, but every sentence carries some relevant signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 annotations and no output schema, the description covers the main effect, immediacy, and reactivation path. It leaves some edge-case behavior unclear, such as treatment of existing enrollments, but gives enough to call the tool correctly.

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

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

The description adds almost no parameter-level meaning beyond the schema. With only 50% schema description coverage and no description of sequenceId in the schema, the description does not compensate for the undocumented required parameter or explain the project override.

Input schemas describe structure but not intent. Descriptions should explain 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: move a sequence to draft. It also states the effect, stopping new enrolments, and explicitly contrasts with activate_sequence, so the agent can distinguish this from its key 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?

The description names activate_sequence as the alternative for starting a sequence again, giving clear routing for the inverse operation. It implies when to pause by emphasizing that stopping mail is immediate, but it does not explicitly state when-not to use this tool or mention other nearby siblings such as update_sequence.

Agents often have multiple tools that could apply. Explicit usage 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 and openWorldHint=false; the description reinforces this with "fetches no pages and changes nothing," which is consistent and rules out crawling/HTTP side effects. It also describes the returned snapshot fields in the absence of an output schema, though it omits any note on size limits or cost of the 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?

One dense paragraph, front-loaded with the value proposition before the payload inventory and the step sequence. The em-dash field list is information-rich rather than padded, though it is slightly long for a one-parameter read tool.

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

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

With no output schema, the description carries the return-shape burden and does so by listing the snapshot dimensions, the widget-kind taxonomy, and the recommended follow-up flow; scope defaults are also covered. An agent has enough to call it and interpret the result without opening other tools.

Complex tools with many parameters or behaviors need more documentation. 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 param is documented as a project id from list_projects; the description adds the meaningful default behavior ("Scoped to the current website; pass `project` to pick another") that the schema alone doesn't make explicit.

Input schemas describe structure but not intent. Descriptions should explain 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 (produce a site/lead-capture strategy snapshot) and enumerates exactly what the payload contains: widget kind, live/draft status, views, completions, conversion, the six widget kinds, and suggested steps. This is clearly distinguishable from siblings like list_widgets, list_widget_analytics or read_widget_results, which return raw lists/analytics rather than a strategy-planning bundle.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 trigger phrasings ("what should I do on my site", "audit my site") and an internal workflow (read the site, ask questions via offer_choice, rank 3-5 fixes), plus scope handling: current website by default, `project` to switch. It does not state when to prefer the raw data siblings (list_widget_analytics, read_widget_results) instead, so the alternative-selection guidance is incomplete.

Agents often have multiple tools that could apply. Explicit usage 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 readOnly/destructive, so the description earns credit for adding scope semantics: the record is account-wide and shared across every website, and a website-scoped connection may read but not write it. That is genuinely actionable auth/scope context not present in the annotations, though return shape and edge cases (e.g. what an unset context looks like) are not 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?

Three sentences, front-loaded with the content inventory, then the generation dependency, then the scope caveat. No filler, though the closing sentence is longer than it needs to be for the constraint it conveys.

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

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

With no output schema, the description usefully enumerates the fields the context contains, effectively proxying a return-value summary, and no parameters are required. For a zero-required-param read tool this is nearly sufficient; only failure/empty-state behavior is unaddressed.

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

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

Schema description coverage is 100%, and the single 'project' parameter is already documented as a project id from list_projects with default-override behavior. The description adds nothing about it, so the baseline 3 applies.

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

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

The description enumerates exactly what the AI context holds (blog topic, pricing tiers, value props, testimonials, design direction, tone presets), which is far more specific than the name alone. The verb is only implicit until the closing sentence ('can read it but not change it'), but the resource is unmistakable and is differentiated from update_ai_context.

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

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

It explains that AI-personalised lead magnets are generated from this, which implies why an agent would read it, and it clarifies the read-only nature of a single-website connection. However, there is no explicit 'use this when' statement and no named alternative for the mutation case beyond the oblique 'not change it'.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered; the description adds real value by disclosing the privacy scoping of the response (which fields are deliberately withheld). It still doesn't say how many records 'recent' covers or whether results are paginated.

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

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

Two sentences, zero filler, with the scope of the read front-loaded and the exclusions immediately after. Nothing could be removed without losing 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 read-only single-parameter list tool with no output schema, the description conveys the subject of the read and the withheld fields, which is most of what an agent needs. It stops short of describing the shape of a status record (counts vs. per-run rows), which would be the remaining gap absent an output schema.

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

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

Schema coverage is 100% and the single parameter is documented, but the description implies filtering 'by status and widget' while the schema exposes only `project`. An agent could reasonably expect status/widget parameters that do not exist, which is a misleading gap between prose and schema.

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

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

States a specific verb (Read) and resource (AI lead-magnet generation outcomes) with scoping by status and widget, which is far more specific than the tautological title. It contrasts itself against the richer result tools by naming what is excluded, though it never names an alternative by name.

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

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

The exclusion clause ('visitor answers, generated content, lead ids, and failure details are not returned') implicitly routes the agent elsewhere when it needs details, but no sibling is named and there is no explicit when-not condition. Usage is inferable rather than stated.

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

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

Goes well beyond the readOnlyHint/destructiveHint annotations: it explains that conversion is completions/views computed as a whole percentage, that 0 views yields 0 rather than an error, that completions are not leads (announcement bars and ungated calculators complete without capturing an address), and that leads marked bad are excluded from figures. These are exactly the domain semantics an agent would otherwise misinterpret.

Agents need to know what a tool does to the 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 returned totals, then metric definitions, then the optional date-range behavior. Dense but every clause carries information; the only mild cost is that lead/completion caveats are packed into long sentences rather than separated.

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

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

With no output schema and a low-coverage input schema, the description carries the return-value burden and does so — listing default fields and the extra window/comparison, device, and UTM breakdowns returned with a date range. It stops short of describing ordering, limits, or how many items the breakdown lists can contain.

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

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

Schema coverage is only 33% (only `project` is documented), so the description has to compensate — and it does: `from` and `to` are epoch milliseconds that must be supplied together, and supplying them changes the response contents. The `project` override is covered by the schema itself, so nothing is undocumented.

Input schemas describe structure but not intent. Descriptions should explain 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 scope ("Totals for the current project") and enumerates the exact metrics returned (widget count, page views, completions, conversion %, leads, unsubscribes), so an agent knows precisely what it gets. It does not, however, distinguish itself from sibling tools like list_widget_analytics or read_widget_results, leaving the agent to infer that this one is project-level rather than per-widget.

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

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

There is conditional guidance — "Pass from and to (epoch milliseconds, both) for a date range" tells the agent how to trigger the extended response — and a useful interpretation rule (0 means NO DATA, not failure). But there is no explicit statement of when to choose this over list_widget_analytics or read_widget_results, so tool selection is only implied.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description adds real behavioural context the annotations cannot: the inheritance/override model — project brands are account defaults plus website-level overrides — which tells the agent results differ by scope, not just by filter.

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

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

Two sentences, no filler, and the field inventory is front-loaded so an agent scanning the first clause knows what it returns. It opens with a noun fragment ('The brand: …') rather than a verb, which slightly blunts the front-load, 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?

No output schema exists, and the description compensates by listing the returned fields plus the scoping behaviour, which is enough to invoke and interpret the call. A note on whether values can be null/empty before branding is configured would round it out, but no critical 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 coverage is 100% and the single parameter is documented there as a project id from list_projects, so baseline would be 3. The description goes slightly beyond by explaining the semantic consequence of the parameter — without it you get account defaults, with it you get merged website overrides — which is meaning not present in the schema.

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

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

The description names the resource (brand) and enumerates its contents — site name, accent colour, sender name, logo, postal footer address — so the agent knows exactly what record it gets back. The read semantics come from the name/annotations rather than an explicit verb, and differentiation from update_brand is only implicit, which keeps it out of the top band.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 second sentence clearly states the selection rule: supply a project to get that website's brand, omit it to get account defaults. It does not explicitly contrast with update_brand or state prerequisites (e.g. whether a project id must come from list_projects), but the calling context is unambiguous.

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

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

Annotations already declare the operation as read-only, non-destructive, and closed-world. The description adds substantial behavioral context beyond that: how insufficient_data is handled, that running experiments list every arm, what holdout means, how beatsControlBp should be interpreted, and that verdict.status informs decisions without stopping or publishing anything.

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

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

The description is dense but appropriately sized given the absence of an output schema and the need to explain several result fields. It is not ideally front-loaded with a clear action statement, but most sentences carry useful meaning.

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

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

Because there is no output schema, the description carries the burden of explaining return values, and it does so thoroughly. It is less complete on input parameter semantics and sibling-tool selection, but the output interpretation guidance is strong.

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

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

Schema description coverage is only 50%, and the description does not compensate for the undocumented widgetId parameter. The project parameter is documented in the schema, but the description adds no input-specific meaning and never mentions either parameter by name.

Input schemas describe structure but not intent. Descriptions should explain 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 makes clear that this tool reports A/B experiment results for a widget, including per-arm metrics and verdict details. It does not explicitly distinguish itself from siblings like read_widget_results or list_widget_analytics, but the resource and data returned are specific.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as read_widget_results, list_widget_analytics, start_experiment, or stop_experiment. The description explains output semantics but leaves tool selection to inference from the name.

Agents often have multiple tools that could apply. Explicit usage 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, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: it discloses a data-privacy guarantee that lead identifiers, payloads, and credentials are withheld, which tells the agent what it can and cannot learn from the result. It stops short of describing volume, ordering, or time window 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?

Two short sentences with zero padding; the core purpose comes first and the privacy caveat second. Nothing is redundant with the annotations or the schema.

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

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

With no output schema, the description must convey the return shape. It says what is excluded (identifiers, payloads, credentials) and names the concepts returned (handoff outcomes, retry state), but it never describes the actual fields, ordering, or how many records come back — a moderate but real gap for the only source of return-value truth.

Complex tools with many parameters or behaviors need more documentation. 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 50%: the project parameter is documented in the schema, but limit has no description at all, and the description adds nothing about it (no default, no max, no effect of recency window). 'Recent' loosely gestures at the limit concept but does not compensate for the undocumented parameter.

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

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

States a specific verb (Read) and a well-scoped resource (recent queued ESP/webhook handoff outcomes and retry state), which is more precise than the title alone. It does not, however, distinguish itself from near-neighbors like read_sending_status or list_email_deliveries, leaving overlap unresolved.

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

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

Usage is only implied: an agent can infer it is for inspecting recently queued handoffs and their retries. There is no explicit when-to-use, when-not-to-use, or pointer to read_sending_status / list_email_deliveries as alternatives, which is a real gap given three sibling tools touch delivery outcomes.

Agents often have multiple tools that could apply. Explicit usage 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, openWorldHint=false), so the bar is lower, and the description still adds real value by disclosing that the score is frozen at submission time rather than recomputed. That is a non-obvious semantic an agent could otherwise get wrong when comparing against current quiz state. It stops short of noting not-found behavior or per-project scoping effects.

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

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

Two sentences, both earning their place: the first front-loads the return shape, the second qualifies the score semantics. No preamble, no restating of the tool name.

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

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

With no output schema, the description must sketch the return value, and it does (answers, score, tier). For a two-parameter read-only lookup that is close to sufficient; the remaining gaps are error cases for an invalid or cross-project leadId.

Complex tools with many parameters or behaviors need more documentation. 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 50%: 'project' is documented in the schema as a project id from list_projects for per-call scoping, while 'leadId' is bare. The description adds no parameter-level meaning at all, so it neither compensates for the undocumented leadId nor improves on the documented project param. 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 precisely what comes back: a single lead, its answers, and quiz score/tier when applicable. That distinguishes it in practice from list_leads (one record vs. many), but it never names the sibling, so the separation is inferred rather than stated.

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

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

There is no explicit when-to-use or when-not guidance. An agent must infer from the phrase 'One lead' that this is the single-record counterpart to list_leads, and nothing addresses what to do if the id is unknown or which project context to pick.

Agents often have multiple tools that could apply. Explicit usage 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 "Changes nothing" is largely redundant. The description does add genuinely non-obvious behavior: leads are counted over the billing period while everything else uses the UTC calendar month, and `plan` is null when no plan is active — real semantic detail an agent could not infer. With the safety profile already covered by annotations, a 3 reflects useful-but-partial added 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?

Front-loaded with the verb and the enumerated metrics, then the counting-period caveat, then the null case. Every clause carries information, though the sentence listing quotas could be tightened 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?

With no output schema, the description must convey what comes back, and it does: per-quota usage versus plan limits, plan and website/widget counts, plus the null-plan edge case. It does not describe the shape of the returned object or how usage is expressed (counts versus percentages), leaving a minor gap.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly implies no filtering scope is needed. It does note that the response's `plan` field may be null, which is a small but useful addition about returned 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 and resource (the account's plan plus per-quota usage) and enumerates exactly which quantities are reported: leads captured, emails sent, AI messages, websites, widgets. This is clearly distinct from every sibling, which are per-object reads like read_lead or read_analytics.

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

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

Frames the use case explicitly with the two questions it answers ("what is my limit" and "how close am I to the cap"), which tells an agent when to reach for it. It stops short of naming an alternative tool or a when-not condition, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral detail: the conditional presence of `records` (only while the domain is unverified) and the semantic difference between rolling 24h `sentToday` and lifetime `sharedTrial.sendsUsed`, which preempts a likely misinterpretation. No pagination/rate-limit detail, but none is needed for a status read.

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

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

Three tight sentences, front-loaded with the resource scope, then conditional behavior, then the clock-semantics clarification. The `sentToday` vs `sharedTrial.sendsUsed` sentence is slightly dense but each sentence earns its place by preventing a concrete misreading.

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

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

For a zero-required-param read tool with full annotation coverage and no output schema, the description covers scope, the conditional `records` field, and non-obvious counter semantics. Minor gap: it does not characterize the reputation field's shape, and with no output schema the agent gets no return-value guidance beyond the field names mentioned.

Complex tools with many parameters or behaviors need more documentation. 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 optional `project` parameter is fully described in the schema (id from list_projects, runs in that project vs. connection default). The description adds nothing about the parameter, 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 verb (read) and a specific resource (sending status), then enumerates what that status comprises: readiness, domain verification, daily usage, reputation. The closing "Does not send mail" plus the read-only framing distinguishes it from siblings like read_integration_delivery_status and read_plan_usage.

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

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

Usage context is implied: an agent consulting sending readiness / domain verification should call this, and the note that `records` only appears while unverified tells the agent when that branch is meaningful. However, there is no explicit when-to-use guidance and no named alternative among the many read_* / list_* siblings, so the agent must infer 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 establish that this is a read-only, non-destructive, non-open-world operation. The description adds meaningful behavior beyond annotations: it explains what `issues` represents, that returned fields vary by widget kind, and how `placement` works for popups, bars, and embed-only widgets.

Agents need to know what a tool does to the 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 result (`One widget in full, plus issues`) and then supplies only relevant kind-specific and placement context. The sentences are dense but each earns its place by helping interpret the returned widget data.

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

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

With no output schema, the description carries the burden of explaining the returned payload, and it does so well by describing the widget contents, `issues`, kind-dependent fields, and placement behavior. The main remaining gap is parameter-level detail, especially for `widgetId`, but the return semantics are otherwise sufficiently covered.

Complex tools with many parameters or behaviors need more documentation. 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 documents the `project` parameter but gives only the name and minLength for the required `widgetId` parameter, resulting in 50% description coverage. The tool description does not mention either parameter, so it fails to compensate for the undocumented `widgetId` semantics.

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

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

The description clearly states that this returns one widget in full plus `issues`, including its kind-dependent subobjects. It is specific about the resource and scope, but it does not explicitly distinguish itself from siblings such as `list_widgets` or `read_widget_results`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 through phrases like `issues — what is still missing before it could go live`, suggesting it is useful when checking readiness before publishing. However, there is no explicit when-to-use guidance or comparison to alternative tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by explaining referrer attribution is rough, defining conversions as purchases credited within 14 days of capture, and describing questionDropoff ordering.

Agents need to know what a tool does to the 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 main resource and return contents, and no sentence is wasted. It is dense and somewhat run-on, which keeps it from being 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?

With no output schema, the description does a good job summarizing return fields and caveats. However, it leaves parameter sourcing and date format ambiguous, and it does not guide tool selection among related analytics tools.

Complex tools with many parameters or behaviors need more documentation. 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 only 25%, so the description needs to carry more of the parameter burden. It adds only that from/to are an optional date range matching read_analytics, but does not specify timestamp units or format, and it does not explain where widgetId should come from or how widgetId should be sourced.

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

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

The description states a specific resource and scope: one widget's views, completions, conversions, leads grouped by referrer, funnel, and question dropoff. It is clear what the tool returns, but it does not explicitly name sibling tools such as list_widget_analytics or read_analytics as alternatives.

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

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

The description implies this is for reading a single widget's results, but it gives no explicit when-to-use or when-not-to-use guidance. The only sibling reference is that from/to should match read_analytics, which is not enough to route the agent between similar 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?

Goes well beyond the annotations by disclosing that a pending approval record with a before/after snapshot is created, that the widget does not go live without a signed-in human approver, and that placement alone does not put a widget on a page. It also warns about `warnings` content such as copy promising an email with no active sequence — context the destructiveHint annotation 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 layering disambiguation, return shape, and caveats in a logical order. The parenthetical asides about placement and email sequences are dense but each carries real decision-relevant information; a small amount of redundancy in restating 'it does NOT publish' twice.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 appropriately explains what comes back (pending approval, snapshot, placement, warnings). What remains missing is the meaning of the required widgetId and any permissions/rate-limit expectations, but the behavioral picture is otherwise complete for a two-parameter mutation.

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

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

Schema coverage is 50%: `project` is documented inline, but `widgetId` has no description anywhere. The prose never clarifies that widgetId must reference an existing draft widget, which is the key semantic the schema omits, so the description only partially compensates.

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

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

States a precise verb and resource ('Ask for a draft widget to go live') and immediately disambiguates from the real publish action. An agent can distinguish this from create_widget/update_widget without consulting 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 frames the workflow boundary: this requests publication and requires human dashboard approval, so it is not a substitute for actually going live. It does not name sibling tools (e.g. create_widget/update_widget) as prerequisites or alternatives, so routing is slightly incomplete.

Agents often have multiple tools that could apply. Explicit usage 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 openWorldHint=true, so the safety bar is lower. The description adds real behavioral context beyond them: even split is the default, holdout arms never produce leads so they measure exposure only and not lift, and extra arms each require the same traffic again. It does not disclose what starting the experiment does to existing traffic on the control widget or whether it is reversible.

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

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

Front-loaded with purpose, then prerequisites, then split semantics — a sensible ordering. It is a single dense block of prose that could be broken up for scanability, but nearly every clause 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 prerequisites, split math and result-reading follow-up for a destructive, open-world mutation. The main gap is the return value: with no output schema, the description never says whether the call returns an experiment id needed by read_experiment_results or stop_experiment.

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

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

Schema coverage is only 20%, but the description carries the load for every functional parameter: widgetId as the control, variantWidgetIds as 1-3 ordered live variants, trafficPcts as whole-number percentages with the control first and ordering tied to the variant list, and holdoutPct's range, default and complement-to-100 relationship. Only `project` is left to the schema, which documents 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 precise verb and resource: 'Split traffic between a control widget and 1 to 3 variants.' An agent can distinguish it immediately from read_experiment_results and stop_experiment 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?

States hard preconditions — variants must already exist as live widgets of the same kind and project, created with create_widget and published with request_widget_publish — and routes to read_experiment_results for outcomes. It also flags a practical constraint ('on a small site one variant at a time'). It stops short of explicit when-not-to-use conditions or naming stop_experiment.

Agents often have multiple tools that could apply. Explicit usage 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, so the mutation profile is covered. The description adds genuinely non-obvious behavior beyond that: counts halt with the stop and a subsequent experiment on the same widgets starts fresh rather than resuming. It doesn't say whether historical results remain readable afterward.

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

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

Two compact sentences, the core action first and the non-obvious consequence second. Nothing extraneous.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, open-world mutation with no output schema, the description covers the semantic effect but omits what happens to the experiment's collected results and whether anything is returned. Adequate but with a 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 coverage is 50%: the project parameter is documented in the schema, but widgetId has no description anywhere. The description mentions neither parameter, so it fails to compensate for the undocumented required widgetId.

Input schemas describe structure but not intent. Descriptions should explain 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: 'End a running experiment.' An agent can tell this apart from start_experiment, though the description never names that sibling explicitly, leaving the pairing implicit.

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

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

Usage is only implied — 'End a running experiment' suggests it applies to active experiments, and the note about starting a new one hints at the start_experiment counterpart. No explicit when-to-use/when-not or prerequisites are given.

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

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

Adds genuinely useful, non-annotation context: partial-update semantics ('Only the fields sent are changed') and account-wide scope shared across websites. However, annotations flag destructiveHint=true and the description never warns what is destroyed — e.g., whether array fields like testimonials or pricingTiers are replaced wholesale — nor does it mention permissions or return 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 behavioral constraints are front-loaded, but the second sentence is promotional filler ('highest-leverage thing you can write here... tedious for a person') that consumes space without helping the agent call the tool. Tightening it would leave room to describe the actual fields.

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

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

A destructive, zero-required-parameter mutation with six fields, low schema coverage, and no output schema needs far more than this. An agent still cannot tell how to phrase valueProps vs about, what ids are needed for testimonials, or what the call overwrites.

Complex tools with many parameters or behaviors need more documentation. 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 only 17% and the description compensates barely at all: it never mentions about, valueProps, designDirection, or the required id/name/price/quote structure of the nested arrays. The one hint ('testimonials and prices come from the owner') gives content provenance but no format guidance, so most of the six parameters remain undocumented.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Change the AI context') and hints at the resource's role ('improves every generation'), which lets an agent distinguish it from read_ai_context. It never defines what an AI context actually contains or how it relates to brand/project data, so the purpose is clear but under-specified.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 real prerequisite ('cannot be changed from a connection limited to one website'), which is useful routing information, but the rest is advocacy ('highest-leverage thing you can write') rather than when-to-use vs when-not. No alternatives to update_brand or plan_site_strategy are named.

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

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

Adds substantial context beyond the annotations: explicit partial-update semantics ('only the fields sent are changed'), the inheritance model (account defaults propagate to every website), and the downstream effect that the accent colour is interpolated into a stylesheet rendering on customers' sites. These are real behavioural traits an agent could not infer from destructiveHint/openWorldHint alone.

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

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

Four tight sentences: purpose, mutation semantics, scope behaviour, then the risk warning. Front-loaded and every clause earns its place, with the most consequential warning last but still compact.

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

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

For a 9-parameter mutation with no output schema and only annotations for safety signalling, the description covers the two things an agent cannot guess: partial-update behaviour and scope inheritance. Remaining gaps (format expectations for URLs, whether an empty string clears a field, return shape) are minor given the self-descriptive parameter names.

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

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

Schema coverage is only 11% — just 'project' is documented — so the description must carry the load. It explains the project parameter's scoping effect and adds meaningful context on accentColor (hex value, injection into a stylesheet), but says nothing about the other seven string fields (logoUrl, senderName, legalName, privacyUrl, termsUrl, mailingAddress, siteName) beyond what their names imply.

Input schemas describe structure but not intent. Descriptions should explain 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 clear verb+resource ('Change brand settings') and immediately clarifies the two scopes it can operate on, which lets an agent separate it from read_brand. It stops short of naming the sibling or stating that it mutates account-level defaults vs. per-project overrides as a headline distinction.

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

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

The description gives concrete guidance on the decision that matters most — pass a project to set a website-specific override, omit it to change the shared account default — and spells out the blast radius of each choice. It does not mention any alternative tool (e.g. read_brand to inspect current values first) or prerequisites.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds the one behavioral fact annotations cannot express: a hard precondition on campaign state and the reason (the ledger reflects what was actually sent). It does not say whether unsent fields are merged or replaced, or what error surfaces when the precondition fails.

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

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

Two sentences, front-loaded with the action and followed by the constraint. The second sentence is longer than strictly necessary in its rationale, but it justifies a restriction the agent would otherwise discover only through an error.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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 six-parameter mutation with 17% schema coverage and no output schema, the description covers neither which fields are editable nor what the call returns or how it fails. An agent knows it may change a draft but not what it can change or what happens to fields it omits.

Complex tools with many parameters or behaviors need more documentation. 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 17% — only the 'project' parameter is documented in the schema — and the description names none of the six parameters. Editable fields (name, subject, body, recipientScope) and the meaning of campaignId are left entirely unstated, so the description does not compensate for the coverage gap.

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

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

"Change a draft campaign" supplies a specific verb (change) and resource (campaign) plus a scoping qualifier (draft) that separates it from draft_campaign and list_campaigns. It stops short of explicitly naming the sibling an agent should reach for when the campaign is not a draft.

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

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

The description gives a clear eligibility rule — only draft campaigns can be changed, sent campaigns cannot be edited — which tells the agent the precondition for calling it. It does not name an alternative for the sent case (e.g. duplicate or re-draft), leaving the fallback path to inference.

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

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

Beyond the destructiveHint annotation, the description discloses important mutation semantics: only sent fields change, but sending steps or branch replaces the whole part. It also explains the DRAFT-only constraint and that existing enrolments keep their original plan.

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

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

The description is front-loaded with the core action and is only four tight sentences. Each sentence adds operational value: scope, partial-update rule, activation constraint, and enrolment behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. 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, nested update tool with no output schema, the description supplies the key constraints an agent needs to invoke it correctly. The only notable gap is that widgetId remains opaque, but this does not undermine the main mutation semantics.

Complex tools with many parameters or behaviors need more documentation. 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 only 17%, so the description carries much of the parameter meaning. It clearly explains the high-risk replacement behavior for steps and branch and partial-update semantics for omitted fields, though widgetId and name remain unaddressed.

Input schemas describe structure but not intent. Descriptions should explain 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 ('Change a DRAFT sequence') and immediately scopes it to DRAFT sequences rather than active ones. It also distinguishes the tool from activation and pausing siblings by naming pause_sequence and activate_sequence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb 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 the tool cannot edit an active sequence and provides the alternative workflow: pause with pause_sequence, edit, then start again with activate_sequence. This gives clear when-to-use and when-not-to-use guidance relative to named 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 readOnly=false and destructive=true, so the description earns credit for adding real signal: partial-field semantics, that built-in starters are editable but not deletable (softening the destructive hint), and that the change affects future sends without triggering one. It still says nothing about permissions, whether a rewrite is reversible, or what the response contains.

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

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

Three short sentences, front-loaded with the mutation scope, then the built-in exception, then the non-send clarification. No filler and no repetition of the title or annotations.

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

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

For a 6-parameter mutation tool with no output schema, the description covers the semantics of the optional fields well but omits the required templateId and the project override, and does not describe the return value or confirmation. Adequate but with a clear gap on the one field every call must supply.

Complex tools with many parameters or behaviors need more documentation. 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 only 17% (just the `project` field), so the description does real work by naming four of the six fields and explaining the only-fields-sent behavior. However, the required `templateId` and the `project` scoping parameter are not mentioned at all, leaving gaps the schema doesn't fill either.

Input schemas describe structure but not intent. Descriptions should explain 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 and enumerates the mutable fields (name, category, subject, body), which instantly separates it from create_template and update_widget-style siblings. The added note that built-in starters can be rewritten is a concrete scope statement, not a restatement of the title.

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

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

"only the fields sent" makes clear this is a partial-update tool, so an agent knows it need not read-then-write the full object. It also implicitly distinguishes update from create and from send-time behavior ("sends nothing"), but it never names list_templates as the prerequisite for obtaining a templateId, nor states any when-not condition.

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

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

The description discloses critical update behavior beyond the annotations: only sent fields are changed, except that sending questions, quizQuestions, quizTiers, or calcInputs replaces all four as a complete set. It also explains that publishing is separate, views/completions are traffic-derived, and the result includes an `issues` list. These details are highly valuable for a destructive/update tool.

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

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

The most important rule—partial update plus the four-array replacement exception—is front-loaded. However, the remaining content is a dense block of text without structural grouping, and for a 59-parameter tool the lack of headings or bullets makes it 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 59-parameter update tool with almost no schema descriptions, the description covers the main widget kinds and critical mutation behavior well. It is not fully complete: many optional parameters are absent, and while it mentions the `issues` result, there is no output schema to clarify return structure.

Complex tools with many parameters or behaviors need more documentation. 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 only 2% across 59 parameters, so the description must carry most parameter meaning. It does this well for the core and kind-specific fields, including trigger/triggers semantics, quiz tier coverage, calculator formula positional references, and URL show/hide behavior. It still leaves many optional parameters (e.g., layout, article, reward fields, routing fields) unexplained.

Input schemas describe structure but not intent. Descriptions should explain 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 begins with a specific verb and resource: "Change a widget." It also clarifies important boundaries, such as publishing being a separate action and views/completions being read-only, which helps distinguish it from sibling actions. However, it does not explicitly contrast itself with create_widget or read_widget.

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

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

The description gives substantial per-kind guidance for what fields each widget type needs and says to send only name and kind to rely on defaults. It also notes that publishing is separate and views/completions cannot be set. It stops short of explicitly saying when to use update_widget versus create_widget/read_widget/request_widget_publish.

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