Buttondown MCP by usefulapi

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

Goes well beyond the annotations: it discloses double opt-in and the unactivated state, that Buttondown e-mails the one address, that opt-in and the firewall are never bypassed, that tags/creation can trigger newsletter automations, that nonexistent tags are created (needing a tag-capable plan), and a 100-subscribers-per-day rate limit. This is exactly the kind of behavioral context annotations cannot carry.

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

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

Front-loads the WRITE marker and the core action, then packs in behavior. Sentences are long and parenthetical but each carries distinct information; only mild density issues, no wasted filler.

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

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

For a mutation tool with no output schema, the description covers opt-in behavior, error cases, side effects, and rate limits thoroughly. The remaining gap is the UTM/referrer parameters, which are neither documented in the schema nor clarified here.

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 63% schema coverage across 8 params, the description adds meaning where the schema is thin: tags (auto-created, plan-gated), a private note, and metadata. It leaves utm_medium/utm_source/utm_campaign and referrer_url unaddressed, so the coverage gap is only partly compensated.

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 'WRITE: add ONE subscriber by e-mail address', a specific verb+resource+scope. The singular 'ONE' and the WRITE marker distinguish it cleanly from list_subscribers and update_subscriber, and the endpoint (POST /subscribers) confirms the 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?

Gives a real usage constraint ('Only add people who asked to subscribe') and states what happens to a pre-existing address (error, no overwrite), which implicitly steers the agent elsewhere for existing subscribers. It stops short of naming update_subscriber as the alternative for modifying an existing record.

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 rich context beyond annotations: confirms nothing is sent or scheduled, no subscriber is e-mailed, the status is always draft, and this server has no send tool. This goes well beyond the structured safety hints (readOnlyHint=false, destructiveHint=false).

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

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

Front-loads 'WRITE' and 'DRAFT' and is generally efficient, though the statement about no send tool slightly repeats the earlier manual-send instruction. Minor redundancy but not bloated.

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

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

For a simple create tool with no output schema and full schema coverage, the description covers purpose, constraints, non-actions, and body format. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented. The description mentions body format (Markdown/HTML), but that duplicates the schema only; no additional parameter meaning is provided.

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

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

States a specific verb and resource ('create a DRAFT email'), clarifies the resulting status ('always draft'), and distinguishes the operation from sending or scheduling. An agent can tell this apart from sibling tools like update_email_draft without opening the schema.

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

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

Explicitly explains when not to expect sending or scheduling and directs the user to Buttondown for that action. However, it does not name the sibling update_email_draft for modifying an existing draft, leaving that routing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false; the description reinforces the idempotency point semantically by explaining duplicate names error out rather than mutate. It also adds the plan requirement and the POST endpoint, real context beyond the structured hints, though it doesn't cover auth scope or what success returns.

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

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

Three terse clauses with the operation class front-loaded via 'WRITE:' and no filler. Every sentence earns its place by conveying purpose, prerequisite, or error 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 5-parameter write tool with a fully covered schema and no output schema, the description adequately covers purpose, prerequisite, and the notable error path. The only gap is the shape of a successful response, which is a minor omission given no output schema exists to reference.

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

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

Schema description coverage is 100%, so all five parameters including name, color, and the two description fields are already documented. The description adds no parameter-level meaning (e.g., how name uniqueness interacts with the error case beyond what's stated), so this sits at the baseline for a fully covered schema.

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

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

The description states a specific verb and resource ('create a subscriber tag') and prefixes it with 'WRITE:' to signal the operation class. It is immediately distinguishable from the read-oriented sibling 'buttondown_list_tags' without opening any schema.

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

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

It gives a concrete prerequisite ('needs a Buttondown plan with tags') and a clear failure condition (an existing tag with the same name is returned as an error and not changed). It stops short of naming alternative tools for other cases, so it is clear context without full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scope detail that results are tied to the calling API key, but says nothing about rate limits, auth failure behavior, or response shape beyond two field names.

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

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

One compact sentence stating scope and return fields, plus the raw endpoint for reference. Nothing is padded and the most important information (which account) comes first.

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 carry the burden of describing the return value, and it names the two returned fields (username, e-mail address). Since there are no parameters and annotations cover safety, the definition is nearly complete; only the exact response envelope or error behavior is unstated.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to clarify beyond that. It correctly implies no inputs are needed and that the account is inferred from the API key rather than passed in.

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

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

The description names a specific verb and resource ('Get account') and defines the scope precisely: the account the API key belongs to, returning username and e-mail address. It is distinguishable from sibling getters (get_subscriber, get_email, get_newsletter) because no other tool targets the account itself.

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 this is used to identify the authenticated account, but the description never states when to reach for it or what conditions make it relevant (e.g. verifying credentials, resolving 'me' before other calls). No alternatives are named, though none are apparent among siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully discloses the shape of the returned object (trigger, actions, filters), which annotations cannot express, but says nothing about error behavior for a missing/invalid id.

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, both front-loaded: the payload content first, then the underlying endpoint. Nothing is padding.

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

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

With no output schema, the description compensates by sketching the return contents, and annotations carry the safety profile. It omits any note about missing-id errors or auth, but for a simple read-by-id tool it is largely complete.

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

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

Schema description coverage is 100% and the single automation_id parameter is fully documented in the schema (UUID or prefixed id such as em_...). The description adds only 'by id', no format or edge-case detail beyond the schema.

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

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

States a specific verb+resource ('One automation by id') and even names the returned sub-structures (trigger, actions, filters). It implicitly contrasts with buttondown_list_automations, but never names that sibling, so an agent must infer the 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?

No when-to-use guidance: it does not say to call this when the automation id is already known, nor does it point to buttondown_list_automations for discovery or buttondown_get_automation_analytics for metrics. Usage is only faintly implied by 'by id'.

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=true, so safety is covered. The description adds nothing beyond the annotations - no mention of what metrics are returned, time window, or aggregation behavior, which is the value a description should supply.

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, front-loaded sentences with no wasted words. It could be slightly more informative, but it is efficient and readable.

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

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

For an analytics tool with no output schema and no annotations covering the return shape, the description omits the metrics, time range, and response format entirely. An agent cannot anticipate what 'performance numbers' means or how to interpret the result.

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

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

Schema coverage is 100% and the sole parameter (automation_id) is fully documented with format examples in the schema. The description adds no syntax or format detail beyond what the schema already states, so baseline 3 applies.

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

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

States a specific verb (Get) and resource (automation analytics) scoped to one automation. It fails to distinguish itself from sibling buttondown_get_automation (config vs performance) or buttondown_get_tag_analytics (tag vs automation scope), so an agent gets no help differentiating related siblings.

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

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

The phrases 'for one automation' and 'Performance numbers' imply a read-only per-automation use case, but no explicit when-to-use, prerequisites, or alternative routing (e.g., get_automation for configuration) is provided.

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=true, so the safety profile is covered without description help. The description adds the useful fact that the response includes the full body and an analytics summary, but says nothing about auth needs, rate limits, or whether the body is HTML vs plain text.

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 fragments with the payload contents front-loaded and zero filler. The trailing "GET /emails/{id}" restates what the name and schema already convey, which is mildly redundant but not harmful.

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 sensibly compensates by enumerating the returned fields, which is the main thing an agent needs for a simple read. The remaining gap - response format details - is minor for a one-parameter, read-only fetch tool.

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

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

Schema description coverage is 100% on a single required parameter, so the schema already explains the UUID/prefixed-id format. The description's "by id" merely confirms the role without adding format or constraint detail, which lands at the baseline 3.

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

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

Names a specific verb and resource ("One email by id") and enumerates the payload returned (body, subject, status, publish date, slug, archive settings, analytics summary). It is clearly distinguishable from list_emails, though it never explicitly contrasts with get_email_analytics even though it overlaps that sibling's territory.

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 by "by id" - the agent can infer this is the single-record fetch when the id is known. There is no explicit when-to-use statement, no guidance versus get_email_analytics or list_emails, and no prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint path and the metric set, which is useful, but it says nothing about auth requirements, latency, or whether metrics are computed live vs. cached. With annotations carrying the safety burden, a 3 is appropriate.

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

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

Two compact sentences: the outcome and metric list come first, the endpoint path last. Every token earns its place and nothing is padded.

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

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

For a simple read-only, single-parameter tool with no output schema, the metric enumeration effectively previews the response shape, so the agent knows what it will get back. The mild gap is that it doesn't clarify behavior for ids belonging to drafts or unsent emails, but for a read it 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 description coverage is 100% and the single parameter email_id is fully documented in the schema, including its prefixed-id format. The description adds only the implicit constraint that the id must refer to a sent email, which is marginal. Baseline 3 applies.

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

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

States a specific verb+resource ('Delivery and engagement numbers for one sent email') and enumerates the exact metrics returned, which distinguishes it from buttondown_get_email (metadata) and buttondown_get_automation_analytics (automation-scoped). An agent can select it without opening the schema.

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

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

The phrase 'for one sent email' implies the usage scope versus aggregate/sibling analytics tools, but there is no explicit when-to-use guidance, no statement that the email must already be sent, and no named alternative. Usage must be inferred.

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=true, so the safety profile is covered. The description adds genuine behavioral value beyond that by disclosing what the payload deliberately omits (API key, CSS, templates), which prevents false expectations about returned fields. It stops short of stating auth requirements.

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

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

A single compact sentence plus the REST endpoint. The identifying qualifier ('by id') and the payload scope are 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?

With no output schema, the description partially compensates by naming what the response includes and excludes. For a one-parameter read-only fetch this is close to sufficient, though an explicit route-to-sibling note would complete it.

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

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

Schema description coverage is 100% with a single UUID/prefixed-id parameter fully documented in the schema. The description's 'by id' adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get' a single newsletter by id) and scopes it further with 'settings and identity only; no API key, CSS or templates'. An agent can distinguish this retrieval-by-id tool from buttondown_list_newsletters without opening either schema.

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

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

Usage is implied by 'by id' — this is the single-record fetch. However, it never explicitly routes the agent away from alternatives (e.g. list_newsletters for enumeration, or update tools for mutation), so guidance is only inferred.

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=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the return payload (field list) and that the key can be either an id or an e-mail address. It does stop short of describing error behavior for a missing/invalid subscriber, which is a minor gap.

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

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

Two short sentences, front-loaded with the scope and returned fields, with zero filler. The trailing 'GET /subscribers/{id_or_email}' restates the resource path already implied by the name and title, making it mildly redundant rather than harmful.

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

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

For a one-parameter read tool with full annotation coverage, the definition does what matters: it names the lookup keys and previews the returned fields in the absence of an output schema. Only the failure mode for an unknown id/e-mail is unaddressed, which is a small omission for this complexity level.

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

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

Schema description coverage is 100% and the sole parameter's description already states 'id or e-mail address', so the description's 'by id or by e-mail address' duplicates rather than extends the schema. Baseline 3 is appropriate — no format, max-length or encoding detail is added.

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 ('Get') and resource ('One subscriber') with explicit scoping to a single record keyed by id or e-mail, and enumerates the returned fields (type, tags, notes, metadata, source, engagement, lifecycle dates). The singular framing plus 'GET /subscribers/{id_or_email}' clearly separates it from buttondown_list_subscribers and buttondown_update_subscriber.

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

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

The description implies the fetch-one-subscriber use case through 'One subscriber by id or by e-mail address', which is enough for an agent to infer when to call it versus a list. However, it never explicitly contrasts with buttondown_list_subscribers or buttondown_update_subscriber, and states no prerequisites. Implied usage only.

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=true, so the safety profile is covered. The description adds the raw endpoint (GET /tags/{id}/analytics) and the metric set, but says nothing about time-window defaults, permissions, or rate limits; with annotations bearing the main burden, this is adequate but thin.

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

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

Two very short sentences, front-loaded with the returned metrics, with the endpoint path appended as supporting detail. No filler, though the first sentence is a verbless fragment rather than a clean statement of purpose.

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

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

With no output schema, the description usefully names the three metrics returned, which is the key thing an agent needs. It omits the reporting period and any pagination/response-shape notes, but for a single-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?

Only one parameter, and its schema description is 100% covered and already points the agent to buttondown_list_tags for id discovery. The description adds no further semantics beyond what the schema states, so the baseline 3 applies.

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

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

Names a specific resource (one tag) and enumerates the exact metrics returned: subscribers created, open rate, click rate. The 'for one tag' scoping implicitly separates it from get_email_analytics and get_automation_analytics, though that differentiation is never made explicit.

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

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

No when-to-use or when-not guidance. The agent gets no statement of prerequisites or of how to choose between this and the sibling analytics tools (email, automation) beyond inferring from the word 'tag'.

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/destructiveHint, so the safety profile is covered; the description nonetheless adds a non-obvious disclosure that listing does not start or change automations, plus a redaction trait (webhook URLs shown by host only) that appears nowhere in structured fields. That is genuine added context beyond annotations.

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

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

Front-loaded with the verb and resource, then the field list and the read-only/redaction caveats. The trailing 'GET /automations' is mildly redundant with the tool name but harmless; overall no wasted sentences.

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

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

With no output schema, the description carries return-value burden and does so by naming the fields returned and noting the webhook-URL redaction. Minor gap: it doesn't say the response is paginated or how to continue, though the page parameter's schema description covers that sufficiently for a 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?

Only one optional parameter (page) at 100% schema coverage, and the schema already explains paging including the 'pass the previous reply's next_page' instruction. The description adds no formatting or range 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+resource ('List automations') and immediately disambiguates the resource by glossing it as 'welcome sequences and other triggered e-mails', separating it from the many other list_* siblings. It also enumerates the returned fields, so an agent knows exactly what this tool surfaces versus buttondown_get_automation.

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 read-only framing and the field list imply the 'browse all automations' use case, but the description never names the alternative (buttondown_get_automation for a single automation, buttondown_get_automation_analytics for metrics) or states when to prefer this tool. 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?

Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. Beyond that, the description adds the default sort ('newest first'), the fact that the body is excluded by default, and the field set returned (subject, status, publish date, slug, archive URL, analytics summary) — meaningful context, especially since no output schema exists.

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

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

Three dense, front-loaded sentences with no filler; the highest-value facts (what is listed, default ordering, body omission) come first. The trailing 'GET /emails' is mildly redundant boilerplate but not disruptive.

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

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

With no output schema, the description correctly carries the return-shape burden by enumerating the fields returned, and it covers filters and defaults for a 9-parameter tool. It stops short of noting that status accepts multiple values or how pagination continues, though the schema's page description partially compensates.

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

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

Schema description coverage is 100% and the schema already documents every parameter including defaults, enum values and date formats. The description restates the filter dimensions (status, subject, date) and include_body without adding syntax, multi-value behavior, or interaction rules, so it sits at the baseline.

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

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

States a specific verb and resource ('List emails') and immediately scopes it to drafts, scheduled and sent items with default ordering, which separates it from sibling list_* tools and from the singular buttondown_get_email. An agent knows exactly what it retrieves without opening the schema.

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

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

The sentence 'Filter by status, subject text or date' implies the intended retrieval scenarios, and 'body is left out unless include_body is set' hints at a lightweight-then-detail workflow. However, it never states when to prefer this over buttondown_get_email or buttondown_get_email_analytics, nor any exclusion conditions, so usage 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the newest-first ordering and the optional scoping, which is useful, but says nothing about pagination behavior or return payload beyond the endpoint hint.

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?

A single tight sentence front-loads the resource, the event types, ordering, and optional scoping. No filler; the GET /events hint is compact and placed last.

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 a fully documented schema and clear annotations, the description covers purpose, scope, and ordering. It could note pagination or that filters combine, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema. The description only restates the email/subscriber filters and adds no format details beyond it, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (delivery events), enumerates the event types, and adds the ordering (newest first). It is clearly distinguishable from sibling list tools like list_emails or list_subscribers.

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?

Implies optional filtering by 'optionally for one email or subscriber' but never states when to use this versus sibling tools like get_email_analytics. No exclusions or explicit alternative routing is provided.

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=true, and destructiveHint=false, so the safety profile is covered. The description usefully adds the endpoint (GET /forms) and the shape of returned fields. It does not discuss pagination behavior beyond the schema, so it adds moderate value on top of annotations.

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

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

A single front-loaded sentence gives the operation and returned fields, followed by a compact endpoint reference. Nothing is wasted.

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

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

For a simple single-parameter read tool, the description plus annotations cover operation, safety, and return fields. The absence of an output schema makes the field enumeration valuable, though pagination guidance lives only in the 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?

Only one parameter exists and schema description coverage is 100%, so the schema fully documents the 'page' argument including the next_page handoff. The description adds no parameter detail, which is the correct baseline when the schema does the heavy lifting.

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

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

States a specific verb ('List') and resource ('sign-up forms') and even enumerates the returned fields (title, slug, status, tags, subscriber counts). This clearly separates it from sibling list tools like list_subscribers or list_tags. It stops short of explicitly routing against alternatives, so 4 rather than 5.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives among the many sibling list_* tools. Usage is only implied by the verb 'List'. No exclusions or context 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely useful context beyond them: which sensitive fields are never returned (API key, custom CSS, e-mail templates) and the underlying GET /newsletters endpoint. It omits pagination/return-envelope behavior, keeping it below a 5.

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

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

Two short sentences, front-loading the returned fields and finishing with the endpoint. The field enumeration is long but each item is informative rather than filler; nothing is redundant.

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

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

With no output schema, the description compensates well by naming both the included fields and the conspicuously excluded ones. The only gap is that paging behavior/response shape is not described, though the schema's next_page hint partially covers it.

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

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

There is one parameter and schema description coverage is 100% – the schema already explains the page number, the default, and the 'pass the previous reply's next_page' instruction. The description adds no parameter detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb (List) and resource (newsletters on the account) and enumerates the fields returned, so an agent knows exactly what it gets back. It does not explicitly distinguish itself from the sibling buttondown_get_newsletter (single newsletter) or the many other list_* tools, so it falls short 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?

Usage is only implied: a plural list endpoint is obviously the 'enumerate newsletters' tool, but the description never says when to use this versus buttondown_get_newsletter or how it relates to other list tools. No exclusions or prerequisites are offered.

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=true, so the safety profile is covered. The description adds the underlying endpoint (GET /segments) and the shape of returned items, which is useful since there is no output schema, but says nothing about pagination behavior or result 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?

Two short sentences, purpose front-loaded with returned fields immediately after. The trailing 'GET /segments' is low-value filler but harmless and brief.

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

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

For a trivial single-parameter read with annotations covering safety and a schema that documents pagination, the description is nearly sufficient: it names the resource and the returned fields, compensating for the absent 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?

Only one optional parameter (page) and schema description coverage is 100%, including the useful 'Pass the previous reply's next_page' hint. The description adds no parameter detail, so baseline 3 applies.

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

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

States a specific verb (List) and resource (saved subscriber segments) and even names the returned fields (name, description, filters). The resource is distinct from the many list_* siblings (tags, subscribers, webhooks), though the description does not explicitly distinguish itself from 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?

No when-to-use guidance, no prerequisites, and no mention of alternatives. The agent must infer from the name alone that this is the read path for segments.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by naming the return fields and exposing the underlying endpoint (GET /snippets), but says nothing about pagination beyond what the schema notes or about result 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?

A single front-loaded sentence plus the endpoint path; no wasted words. The raw endpoint adds little value over the field list but is harmless.

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

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

For a single-parameter, read-only list tool with full schema coverage and annotations covering safety, the description is complete enough. The returned-field summary compensates for the absent output schema.

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

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

Schema coverage is 100%, so the single page parameter is fully documented in the schema, including the next_page chaining hint. The description adds no parameter detail beyond the schema baseline.

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

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

States a specific verb (List) and resource (reusable content snippets) and even enumerates the returned fields (identifier, name, mode, reference count). It's clearly distinguishable from write siblings like buttondown_create_email_draft, though it does not explicitly contrast with the many 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?

The listing intent is implied by the verb and the returned-field summary, but there is no explicit when-to-use guidance, prerequisites, or routing vs. sibling list tools. Adequate but leaves selection largely to inference.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety bar is met. The description adds genuinely new context: default ordering ('newest first by default' / new→old), the endpoint (GET /subscribers), and a short inventory of returned fields. Pagination semantics live only in the schema, not here, which caps it below 5.

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

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

Two dense sentences plus a trailing endpoint token; purpose and default ordering are front-loaded with no filler. The 'GET /subscribers' fragment is slightly redundant but harmless. Efficient overall.

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 steps in by enumerating returned fields (e-mail, type, tags, notes, metadata, source, open/click rates, dates) and the default sort. Pagination is covered by the page parameter in schema, so nothing critical is missing; a note on result-size/cursor behaviour would be the only gap.

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

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

Schema description coverage is 100%, so all nine parameters (tag, page, type, not_type, domain, ordering, created_after/before, email_address) are already fully documented. The description's filter list ('e-mail text, type, tag, signup date or domain') largely mirrors the schema and omits not_type and page, so it adds little beyond the structured fields. Baseline 3.

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

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

States a specific verb pair ('list or search') and resource ('subscribers'), and the surrounding sibling names (get_subscriber, add_subscriber, update_subscriber) make the singular/single-item and mutation variants trivially distinguishable. An agent can tell this is the collection read endpoint without opening the schema.

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

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

The filtering sentence implies the tool's role (enumerate/filter subscribers), but there is no explicit when-to-use vs when-not, and no alternative sibling is named for cases like finding one subscriber (get_subscriber) or mutating (update_subscriber). Usage is inferable but not guided.

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=true, so the safety profile is covered. The description adds only the underlying endpoint ("GET /survey_responses"), which is mild context; it says nothing about pagination behavior, volume, or auth needs beyond what the schema's page parameter already conveys.

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

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

Two tight fragments with the core action front-loaded and the filter dimensions immediately after. Nothing is redundant and there is no filler.

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

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

For a read-only list tool with no output schema, annotations covering safety, and full schema coverage, the description is minimally adequate. It omits any mention of the date-range filters (created_after/created_before) and pagination, which are meaningful capabilities of this endpoint, so it falls short of complete.

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

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

Schema description coverage is 100%, so all six parameters are self-documenting in the schema. The description references three of the filter dimensions (survey, email, subscriber) but adds no syntax, semantics, or defaults beyond 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 survey responses") and clarifies the payload with "(who answered what)", so an agent knows this returns individual answers rather than survey definitions. It doesn't explicitly name the sibling buttondown_list_surveys to differentiate the two, which keeps it short of a 5.

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

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

"optionally for one survey, email or subscriber" implies the filtering contexts in which this tool is useful, but there is no explicit when-to-use, when-not, or named alternative. The usage signal 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description contributes the useful detail that each survey carries question, answers, status, and response count, but says nothing about pagination limits or ordering, which mattered more than repetition of the safe-read profile.

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?

A single tight sentence listing the returned fields, followed by the endpoint. Nothing is padded and the substance is front-loaded.

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

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

With no output schema, the description usefully enumerates the response fields, and the schema carries the pagination cursor. For a two-parameter read filter tool this is close to complete, though ordering and the relationship to survey responses remain unstated.

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

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

Schema description coverage is 100%, so both the page cursor and the status enum are already fully documented in the schema, including the 'pass the previous reply's next_page' instruction. The description adds nothing beyond that baseline.

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

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

States a specific verb (list) and resource (surveys) and enumerates the fields returned, which pins down what the call yields. It stops short of explicitly distinguishing itself from the closely named sibling buttondown_list_survey_responses.

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 when-to-use guidance, no mention of prerequisites, and no routing between this tool and buttondown_list_survey_responses. The only implied usage is the generic 'list' verb, which the agent must infer on its own.

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=true, so the safety profile is covered. The description adds the returned field set and the HTTP verb (GET /tags), which is mildly useful, but says nothing about pagination limits, ordering, or response envelope beyond the schema.

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

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

Two short sentences with no filler, and the field list is front-loaded immediately after the resource. Every clause earns its place.

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

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

For a simple single-parameter read with no output schema, the description usefully enumerates the returned fields, which compensates for the missing return schema. Remaining gaps (pagination behavior, ordering) are minor for this tool's complexity.

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

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

Schema description coverage is 100% and the single `page` parameter is well documented in the schema, including the 'pass the previous reply's next_page' guidance. The description contributes nothing about the parameter, so the baseline 3 for a fully documented schema applies.

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

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

States a specific verb (List) and resource (subscriber tags) and enumerates what each record contains, so the agent knows it is a read of tag metadata rather than subscribers or segments. It does not explicitly contrast itself with the adjacent list_* siblings, 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?

There is no statement of when to reach for this tool versus list_subscribers, list_segments, or get_tag_analytics, and no mention of prerequisites or when listing is preferable to fetching a single tag. Usage is only implied by the standalone verb.

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=true, so safety is covered. The description adds genuinely useful disclosure beyond them: the signing key is never returned and URLs are redacted to host only, which tells the agent what it can and cannot expect in the payload.

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

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

Two compact sentences plus the underlying endpoint reference; the returned-field summary is front-loaded ahead of the redaction caveats. Nothing is padded or repeated.

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 steps in to say what fields are returned and how sensitive values are masked, which is the main thing an agent needs. It does not mention pagination behavior in the response, though the schema's next_page hint partly covers that.

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

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

Schema description coverage is 100% for the single 'page' parameter, including the 'pass next_page' instruction, so the baseline is 3. The description adds no additional meaning about paging semantics or limits.

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 configured webhooks') plus the scoping detail ('with status and subscribed event types'), so the agent immediately knows what comes back. No sibling in the list touches webhooks, so there is no ambiguity to resolve.

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

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

Usage is implied by the verb and resource — call it when you need to inspect configured webhooks — but there is no explicit when-to-use condition, prerequisite, or named alternative. Adequate but with a clear gap.

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 the listed fields are replaced wholesale and 'the previous text is lost unless Buttondown's email history is used', plus that non-draft emails are rejected and status/publish date are untouched. The destructiveHint=true annotation is confirmed and explained rather than merely echoed.

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 'WRITE:' plus a single dense sentence covering action, fields, replace semantics, refusal rule and status guarantee, closed by the endpoint. No filler sentences.

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

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

No output schema and sparse annotations, yet the description supplies the mutation semantics, loss warning, refusal behavior and endpoint needed to call it safely. It doesn't say what the PATCH returns, but nothing critical for a correct invocation is missing.

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

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

Schema description coverage is only 29%, so the description must carry weight, and it does: it maps the editable surface to subject, body, description, slug and preview image (the 'image' parameter). It omits canonical_url and adds no format guidance beyond the schema's Markdown/HTML note, so it is not fully compensating.

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 ('edit'), a specific resource ('email that is still a DRAFT'), and enumerates exactly which fields are editable (subject, body, description, slug, preview image). An agent can distinguish this from buttondown_create_email_draft and the get/list siblings without opening any schema.

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

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

Gives an explicit when-not condition ('Refuses any email that is not a draft') and clarifies what the call will never do ('never changes status or publish date'), which is exactly the boundary an agent needs before choosing this over a publish/schedule path. It does not name an alternative tool for the non-draft case, so it falls short of the 5 bar.

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 (destructiveHint, idempotentHint, openWorldHint) by spelling out merge semantics for tags versus destructive replacement for note/metadata, and by disclosing the indirect side effect that a change can trigger newsletter automations that e-mail the subscriber. This is exactly the kind of behavioral context annotations cannot convey.

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

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

Front-loads the WRITE marker and the core action, then layers constraints and side effects, ending with the endpoint. Dense but every clause carries information; the parenthetical examples add slight length without much 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?

For a single-record partial-update tool with no output schema, the description covers scope, mutation semantics, immutability of type/e-mail, side effects, and the underlying endpoint. An agent has everything needed to invoke it correctly and safely.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value beyond the schema: it clarifies that add_tags/remove_tags are additive-merge (other tags stay) whereas notes/metadata replace the whole field. That merge-vs-replace distinction is not obvious from the schema's terse per-field descriptions alone.

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

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

States a specific verb and resource (change ONE subscriber's tags, private note or metadata) and scopes it against the sibling retrieval/list tools with 'ONE subscriber'. An agent can immediately tell it apart from buttondown_add_subscriber, buttondown_get_subscriber, and buttondown_list_subscribers.

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?

Clearly bounds when this tool applies and when it does not: subscriber type and e-mail address 'cannot be changed here', implying those need another path. It also clarifies the tool 'sends nothing itself' versus the automation side effect. It does not name a specific alternative tool, so it stops short of a full when/when-not routing.

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