MailBluster MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is largely covered. The description adds real value on top: that creation mutates the brand's data model and dispatches nothing, which is a meaningful side-effect disclosure not present in the annotations.

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

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

Four short sentences with the operation type front-loaded and no filler. Each sentence carries distinct information: operation, key semantics, side effect, endpoint.

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

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

For a two-parameter creation tool with no output schema, this covers purpose, key semantics, side effects, and endpoint. It omits error/duplicate behavior (what happens if the merge tag already exists), which matters given idempotentHint=false, but otherwise nothing an agent needs is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the role of the merge tag as the key used in lead `fields` and in email templates. That semantic context is not available from the schema's terse 'Merge tag, e.g. gender.'

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 ('create') and resource ('custom lead field'), prefixed with 'WRITE:' to signal mutation versus the read siblings. It does not explicitly name a sibling like mailbluster_list_fields or mailbluster_update_lead, but the resource is specific enough to distinguish it.

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 explaining what creating a field does (changes the data model, sends nothing), but never states when to reach for this versus mailbluster_update_lead or mailbluster_list_fields. Usage is inferable rather than 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?

Goes well beyond annotations by disclosing that no email is sent, double opt-in is not offered, consent responsibility lies with the user, and that the server never auto-subscribes. Also explains the overwrite replacement behavior and the failure-on-existing-lead condition — none of which the annotations (destructiveHint, idempotentHint) 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?

Well-structured and front-loaded with the WRITE marker and core action, followed by critical behavioral caveats. Every sentence carries distinct information (default, consent, failure mode, overwrite semantics) with no filler.

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

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

For a 9-param write tool with no output schema and nested objects, the description covers the safety-critical behaviors (consent, overwrite destruction, no email sent) that the annotations alone would not fully clarify. 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 78%, so the schema already documents most parameters including subscribed, overwrite_existing, fields, ip_address, and tags. The description reinforces the subscribed default and overwrite semantics but adds little syntax or format detail beyond what the schema provides.

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

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

States a specific verb and resource ('add a lead (contact) to the brand') and clearly contrasts with the sibling mailbluster_update_lead by establishing creation semantics. The WRITE: prefix front-loads the mutation nature.

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

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

Explicitly names when to set subscribed=true vs. false, and gives the overwrite_existing=true condition as the alternative path when the lead already exists. This is explicit when/when-not guidance rather than implied usage.

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

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

Annotations only declare destructive/openWorld/non-idempotent; the description goes well beyond that by disclosing side effects the agent could not infer: the customer email becomes a lead if none exists, the lead's tags are merged, the server never subscribes anyone on its own, and an existing customer's stored subscription state may be replaced. That is exactly the mutation-impact context an agent needs before calling a destructive 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?

Front-loads the write/side-effect warning and the endpoint (POST /orders) is a useful anchor. The consent guidance is spread across roughly three sentences that restate the same subscribed=true rule, which is mild redundancy rather than wasted space given the legal-weight of the point.

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, nested-object mutation with no output schema, the description covers the highest-risk semantics (lead creation, tag merge, subscription overwrite, no payment). It is silent on what the call returns and on what happens if an order_id is reused, which matters given idempotentHint=false.

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 83%, so the baseline is 3, and the description adds genuinely new meaning for `customer.subscribed` — that omitting it would default to true and that it can overwrite stored subscription state, which the schema field text does not state. Other parameters (order_id, currency, total_price, items) 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 ('WRITE: record an order') and immediately scopes it by negating what the name might imply ('it does not take payment, charge a card or send email'). That negation distinguishes it from the sibling create_lead and from any actual payment tool, so an agent can route correctly without opening the schema.

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

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

Gives clear operating context: this is a tracking record, and the `subscribed` flag must be passed explicitly with consent reasoning. It cross-references mailbluster_list_fields for merge tags. It does not, however, explicitly say when to use mailbluster_create_lead or mailbluster_create_product instead, so the sibling routing is left implicit.

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 non-read-only, non-destructive, non-idempotent behavior, the description adds real value beyond them: "Sends nothing to anyone and charges nothing" rules out email and billing side effects, and "POST /products" pins the operation. It stops short of noting duplicate-id behavior, which is the one trait (idempotentHint=false) an agent might still misjudge.

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, zero filler, front-loaded with the "WRITE:" signal and then the side-effect clarification. 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 two-parameter create tool with full schema coverage, no output schema, and complete annotations, the description covers purpose, inputs, side effects, and endpoint. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented. "Your own id plus a name" merely re-emphasizes what the schema says ("Your unique product id."), adding no syntax, format, or uniqueness constraint beyond it. Baseline 3 applies 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?

Specific verb+resource ("register a product record") with the exact inputs named ("your own id plus a name") and the business rationale ("so orders can reference it"). The order-reference framing implicitly separates it from siblings like create_order or create_field, so an agent can place it without opening the schema.

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

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

It gives clear context for when to call it: to register a product that later orders will reference. However, it never states the inverse condition (e.g. use update_product for existing products, or that duplicates are disallowed), so the agent gets positive guidance but no exclusions or 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 declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: the server computes the MD5 id from the email, and the underlying GET /leads/{md5(email)} route is disclosed.

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

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

Two dense sentences with no filler: purpose and return fields first, then the no-list caveat and the endpoint. Everything is front-loaded and each clause 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?

Even without an output schema, the description enumerates the returned fields (name, custom fields, timezone, subscribed/opt-in status, tags, dates) and discloses the endpoint, so an agent knows both how to call it and what to expect back.

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

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

Schema coverage is 100% and the schema already labels email as preferred and lead_hash as the 32-char MD5 alternative. The description adds the non-obvious semantic that the MD5 is derived from the lowercased email server-side, clarifying how the two parameters relate.

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 lead), plus the lookup key (email address) and the returned fields. It explicitly notes MailBluster has no list-leads endpoint, which separates it from any listing behavior an agent might expect.

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?

Tells the agent this is the way to fetch a single lead and that no list endpoint exists, and identifies email as the preferred identifier over lead_hash. It does not spell out when to prefer this over update_lead for read-back purposes, but the routing context is clear.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description adds the mild nuance that the record must be addressed by the id used at creation and that the read is a simple GET, but nothing about permissions, rate limits, or what a missing id 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?

Two brief sentences, front-loaded with the action and resource and with zero filler; the HTTP endpoint is a compact identifier rather than prose 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 one-parameter read tool with no output schema and annotations that already declare safety, the description covers the essentials. It is nearly complete; only a pointer to when to prefer it over list_orders is missing.

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

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

Schema coverage is 100% for the single order_id parameter, so the schema already documents it. The description adds only the nuance that the id is the one from creation, which is marginal but real value beyond 'Order id.' — baseline 3 applies when the schema does the 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 (Get) and resource (one order record) plus the lookup key, which clearly separates it from the sibling mailbluster_list_orders. It does not explicitly name the alternative, so it falls 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?

Usage is implied rather than stated: fetching a single record by its id, and the phrase 'the id it was created with' hints the id must come from creation. There is no explicit when-to-use, when-not, or routing to siblings such as list_orders or update_order.

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 no behavioral context beyond restating the HTTP verb and path, which duplicates rather than enriches the structured metadata.

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

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

Two short sentences with the purpose front-loaded and no wasted prose. The trailing 'GET /products/{product_id}' is largely redundant with the schema's path knowledge, keeping it just below a 5.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, the description is nearly sufficient; it tells an agent which id to supply. It could note what a product record contains, but that gap is minor for this simple lookup.

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 product_id parameter, so the schema already carries the semantics; baseline of 3 applies. The description adds only marginal meaning ('the id you registered it under') without any format or constraint guidance.

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 product record) and clarifies the singular scope ('one product record by the id'), which implicitly distinguishes it from list_products. It does not, however, name a sibling explicitly, so it stops short of the 5 tier.

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 'by the id you registered it under' implies the usage condition (single-record lookup when you already hold an id), but there is no explicit when-to-use, when-not-to-use, or named alternative such as list_products.

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 return shape (id, label, merge tag), which is valuable given there is no output schema, but it discloses nothing about auth, rate limits, pagination, or empty-brand 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 short sentences, front-loaded with what is listed, then the key usage tip, then the endpoint. No filler; 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?

For a parameterless, read-only list tool with no output schema, the description supplies the essential pieces: what is returned and how merge tags are consumed elsewhere. It omits pagination/ordering details, but nothing critical is missing 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly implies no filtering options are available, matching the empty input 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 (List) and resource (the brand's custom lead fields), and even enumerates the returned attributes (id, label, merge tag). The resource is distinct from sibling list tools (mailbluster_list_orders, mailbluster_list_products), so an agent can route without opening schemas.

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

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

It gives concrete downstream guidance: use the returned merge tags as keys of `fields` when creating or updating leads, which implicitly tells the agent to call this before mailbluster_create_lead / mailbluster_update_lead. There is no explicit when-not guidance, but the context for calling it is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them: the fields the records contain, the fact that these are tracking records with no payment involved, and the pagination contract (meta.nextPageNo).

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 resource and returned fields, then the disambiguating note, then the paging contract. The trailing "GET /orders" is mildly redundant but the rest is dense and waste-free.

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 describing returns, and it does enumerate the record fields plus the paging meta field. It stops short of stating list size, default page size, or whether results are filterable, which would be needed for a fully complete picture.

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 page_no and per_page are fully documented in the schema, including the meta.nextPageNo handoff and per-page bounds. The description only echoes the paging behavior without adding format or constraint detail, 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 order records") and enumerates the record fields returned, so the agent knows this is a collection read. It does not explicitly differentiate itself from the sibling get_order (single record) or create/update_order, leaving that inference to the agent.

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 plus the paging instruction, and "no payment is involved" usefully clarifies what these MailBluster-side records are. However, there is no explicit when-to-use or when-not-to-use guidance, and no reference to get_order as the alternative for single-record retrieval.

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 safety is covered structurally. The description adds genuinely new behavior: the response is paged via meta.total and meta.nextPageNo, and nextPageNo is null on the final page. That sentinel detail is useful and not present in the annotations.

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

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

Two sentences, no filler. The scope and returned fields are front-loaded, then paging mechanics, then the endpoint. Every clause carries information an agent can act on.

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

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

With only two optional params, no nested objects, and no output schema, the description carries return-shape responsibility and does so (id, name, dates, meta.total, meta.nextPageNo). Safety is covered by annotations. Only minor gaps remain, such as default page size behavior beyond the schema note and any rate-limit context.

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

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

Schema description coverage is 100%, so both parameters (page_no, per_page) are already fully documented in the schema, including the nextPageNo continuation instruction. The description's mention of meta.total/nextPageNo lightly reinforces the cursor semantics but adds no syntax or constraints beyond the schema, matching 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?

The description states a specific verb and resource ('List product records') and even names the returned fields (id, name, dates) and the backing endpoint (GET /products). It is clearly a bulk-listing operation, which separates it naturally from get_product, but it never explicitly names a sibling tool, so it falls short of full differentiation.

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: the agent can infer 'use this to enumerate products' and the paging hint ('Pass the previous reply's meta.nextPageNo') tells it how to continue. There is no explicit when-to-use versus get_product / create_product guidance and no stated preconditions (e.g. auth or brand context).

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the bar is lower, yet the description still adds real value: partial-update semantics, the default-preservation rule for subscribed, the unsubscribes/re-subscribes consequences of that flag, and the consent liability statement ('this server never subscribes anyone on its own'). It does not, however, discuss tag-removal or unsubscribe irreversibility beyond the consent note.

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 WRITE label and the field list, then progressively narrower rules, ending with the PUT path. Dense but nearly every clause carries information. Minor redundancy in restating the mutable fields already implied by the verb.

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

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

For an 11-param, zero-required, no-output-schema mutation tool, this covers the risky surface (subscription, consent, partial update). Gaps remain around identifier selection (email vs lead_hash) and the add_tags/remove_tags ordering interaction, which are only resolved by opening 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?

With 64% schema coverage, the description adds meaning beyond the schema by explaining the merge-tag keying for `fields`, the send-only-what-changes contract, and the detailed conditional semantics of `subscribed` (false unsubscribes, true re-subscribes, consent required). It does not clarify the email-vs-new_email-vs-lead_hash identity relationship, which the schema only partly covers.

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: change an existing lead's name, custom fields, email, timezone, IP address, subscription flag or tags' — a specific verb plus resource plus the full mutable field set. The 'WRITE' prefix and 'existing lead' scope cleanly separate it from create_lead, get_lead, and the update_order/update_product siblings.

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

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

Gives clear operational context: 'send only what should change' (partial update), 'subscribed is left alone unless you pass it', and the consent precondition for subscribed=true. It also routes to mailbluster_list_fields for merge tags. It never explicitly names a sibling alternative (e.g. create_lead for new leads, get_lead to inspect first), so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered; the description adds genuinely new behavioral context in that `items` REPLACES all previous items and that customer/payment changes are out of scope. It stops short of describing permission requirements or partial-failure 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 dense sentences plus an endpoint, all front-loaded with the WRITE marker. Nothing is repeated and every clause carries actionable 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 5-parameter mutation with no output schema but strong annotations, the description covers scope, replacement semantics, exclusions, and the target endpoint. Minor gaps remain around authorization and how the implicit product-creation side effect for new item ids interacts with the update.

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 80% (baseline 3), and the description adds meaning on top: it names which fields are mutable, clarifies partial-update semantics, and flags the full-replace behavior of `items` — the one parameter whose consequence is not obvious from the schema alone.

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

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

States a specific verb and resource ('change an order record's campaign, currency, total or items') and explicitly marks it as a WRITE, which cleanly separates it from read siblings like mailbluster_get_order and mailbluster_list_orders.

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

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

Gives clear operating context ('send only what should change') and exclusions ('The customer cannot be changed here. No payment or email is involved'), so the agent knows the boundaries of the mutation. It does not name a specific sibling alternative the way a 5 would, but the when-to-use 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 readOnlyHint=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description's 'WRITE' + 'PUT' largely restates that safety profile. It adds no new behavior context such as permission requirements, rate limits, or what happens to the previous name.

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 terse fragments with zero filler and the write nature front-loaded before the endpoint. Efficient and scannable, though the extreme brevity borders on under-specification.

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

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

For a two-parameter mutation with full schema coverage and rich annotations covering the safety profile, the description supplies what an agent needs to route and call it correctly. Only the total absence of situational guidance keeps it from being fully complete.

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

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

Schema description coverage is 100%, so both parameters (name, product_id) are already documented in the schema. The description's 'rename' corroborates that name is the field being written but adds no format, constraint, 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 (rename) and resource (product record), plus the HTTP operation PUT /products/{product_id}. It is distinguishable from create_product and get_product, though the narrow word 'rename' slightly understates that this is the generic product-update tool.

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 at all: nothing about when to update vs. create a product, no prerequisites, and no mention of the sibling update tools. Only the 'WRITE:' prefix hints that this is a mutation.

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