Laposta MCP by usefulapi

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

Annotations only say destructiveHint=true and openWorldHint=true; the description goes well beyond that by disclosing that upsert overwrites an existing active member's fields, that an unsubscribed member is re-activated unless suppress_reactivation is set, and that a confirmation email is sent on double opt-in lists. That is exactly the consequence-level detail an agent needs before calling a mutation.

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

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

Four short sentences, front-loaded with the WRITE marker and the core action, then layering opt-in, consent and upsert semantics. No filler and no restatement of the title.

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

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

For an 8-parameter destructive mutation with no output schema, it covers the consent precondition, confirmation-email behavior and the upsert/reactivation consequences. It is a bit thin on the required ip/source_url provenance fields and on failure modes beyond the default upsert error.

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 88%, so baseline is 3, but the description adds relational meaning the schema cannot: the interaction between upsert and suppress_reactivation and the overwrite consequence. It still says nothing about ip, source_url or custom_fields, which the schema carries 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?

Opens with 'WRITE: add one email address to a mailing list (subscribe)' — a specific verb, resource and cardinality ('one email address'). That framing separates it cleanly from laposta_update_member and laposta_list_members without needing to name them.

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

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

Gives real conditions for use: double opt-in lists trigger a confirmation email, and 'the address must have given consent' sets a precondition. It also explains when upsert applies, though it never explicitly names laposta_update_member as the alternative for editing an existing member.

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 write/non-idempotent/open-world, and the description adds genuinely new context: the created object is an inert draft and from_email must be a pre-approved sender, which is a real precondition that causes failures. It does not cover error behavior (e.g. duplicate name on a non-idempotent create) or what the response returns, so it stops short of a 5.

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

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

Three short sentences with zero waste, front-loaded with the WRITE prefix and the draft-state qualifier before the follow-up workflow. Every sentence carries distinct 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 an 8-parameter write tool with rich annotations and no output schema, the description covers lifecycle and the key precondition well. The one notable gap is that it never hints that the response yields the campaign id required by laposta_set_campaign_content, which an agent must chain.

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 8 parameters including the approved-sender constraint on from_email are already documented in the schema. The description reiterates the from_email prerequisite but adds no syntax or format detail 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?

States a specific verb and resource ('create a new regular campaign') and immediately narrows the scope with 'a draft: it is NOT filled, scheduled or sent'. An agent can distinguish this from the read/update 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?

Names the exact follow-up tools (laposta_set_campaign_content, laposta_send_test_email) and states that sending happens in the Laposta app, which also tells the agent there is no send tool to look for. The 'NOT filled, scheduled or sent' clause defines the boundary of the operation explicitly.

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 openWorldHint=true, so the safety profile is covered. The description adds genuine value by enumerating what a successful response contains (name, subject, preview text, sender, reply-to, recipients, delivery moments, web version URL) in the absence of an output schema; it does not cover error behavior (e.g. unknown campaign_id) or 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?

One front-loaded sentence with the verb and resource first, then the field list. The enumeration is long but earns its place since no output schema exists; 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?

For a single-parameter read tool with annotations covering safety and no output schema, describing the returned fields is the key missing piece and it is present. Minor gaps remain around error cases and how to obtain a valid campaign_id, but the description is sufficient to call the tool correctly.

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

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

Schema coverage is 100% and the single parameter already documents its source (laposta_list_campaigns), so the description adds nothing beyond the schema. 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?

States a specific verb and resource ('Get one campaign') and enumerates the fields returned, which implicitly separates it from laposta_get_campaign_content and laposta_get_campaign_history (which cover body content and history respectively). Siblings are not named explicitly, 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?

Usage is only implied: an agent infers it should call this when it needs campaign metadata, and the schema's parameter description ('from laposta_list_campaigns') hints at the discovery path. There is no explicit when-to-use versus get_campaign_content/get_campaign_history guidance or exclusion.

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

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

Adds real context beyond the readOnlyHint annotation: the HTML payload is large (a cost/size warning), import_url is conditionally present, and plain text is the default. It stops short of describing error behavior for missing campaigns.

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 sentence, front-loaded with the default behavior and ending with the optional flag — every 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?

With no output schema, the description does cover what comes back (plain text, import_url, optional HTML), which is the key thing an agent needs. A note on failure behavior 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 coverage is 100%, so the schema already documents both parameters; the description reinforces include_html's cost ('large') and mentions a return field not in the schema, but adds no new parameter syntax. 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 (get a campaign's plain-text content) and even scope the return (import_url, optional HTML). It is naturally distinct from the metadata-oriented laposta_get_campaign sibling, though it never names an alternative explicitly.

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 only usage cue is 'Set include_html to also get the full HTML (large)', which tells the agent when to opt in but not when to avoid this tool or what to use instead for non-content campaign data.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that results are cursor-paged and ordered newest-first by default, but the cursor mechanics and the large-page character cutoff are already documented in the schema, leaving little genuinely new behavioral disclosure beyond confirming this is a read operation.

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

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

Three short sentences, zero filler. The core purpose is front-loaded, pagination follows, and the alternative-tool pointer is last — the correct order of importance.

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 event kinds a caller will receive and notes cursor paging, which is what an agent needs to plan a loop. It stops short of describing the response envelope (next_cursor field, per-event fields), but the schema's cursor text 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 every parameter (campaign_id, limit, order, cursor, event_date_from, event_date_to) is documented with format, bounds, and inclusivity semantics. The description only restates date-range filtering and default ordering, 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 resource (recipient events of one campaign), enumerates the event types returned (delivered, opened, clicked, bounced, unsubscribed), and specifies default ordering and date-range scoping. It also explicitly contrasts itself with laposta_get_report, which handles totals, so an agent can separate it from the nearest sibling without inspecting schemas.

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

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

Explicitly routes the agent: 'For totals use laposta_get_report.' That is a clear when-to-use-this-instead rule. It does not address related siblings such as laposta_get_campaign, laposta_get_campaign_content, or laposta_get_member_history, so the routing is incomplete but not ambiguous.

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 openWorldHint=true, so the safety profile is covered. The description adds real value by naming the returned content (name, state, notification addresses, member counts), which matters because there is no output schema.

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

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

A single tight sentence with the resource and returned fields front-loaded; 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 one-parameter read tool with full annotation coverage, the description is nearly complete, especially by previewing the returned fields in lieu of an output schema. Only the absence of id-not-found or listing-alternative context keeps it below 5.

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 itself explains that list_id comes from laposta_list_lists. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one mailing list') and enumerates the fields returned, so the agent knows exactly what this retrieves. Unlike laposta_list_lists it is scoped to a single list, though the description never names that sibling to make the contrast 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?

Usage is only implied: 'Get one mailing list' suggests fetching a single known list by id. There is no explicit guidance on when to prefer this over laposta_list_lists or what happens for an unknown 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?

readOnlyHint and openWorldHint already establish that this is a safe, externally-scoped read, so the description only needs to add context. It does add the returned field categories, but says nothing about behavior when the member is not found, whether lookup by email vs id differs in errors, or rate limits.

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

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

A single front-loaded sentence naming the action, the lookup key, and the payload; nothing is redundant or 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 two-parameter read tool with no output schema and full annotation coverage, the description's enumeration of returned fields is the right compensation. Only the not-found/error behavior is left unaddressed, which is a minor gap.

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

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

Schema coverage is 100% and both parameters are documented, including that list_id comes from laposta_list_lists. The description restates the id-or-email alternative without adding format or precedence semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ("Get one member of a list") plus the two accepted lookup keys and the returned field categories (state, signup/confirm dates, custom fields). It is clearly distinguishable from list-type siblings, though it does not explicitly name laposta_get_member_history or laposta_update_member as neighbors.

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 "one member... by member id or email address" implies single-record retrieval versus the listing tool, but there is no explicit when-to-use guidance, no exclusions, and no mention of when to prefer laposta_get_member_history for event data.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond that: default ordering (newest first) and cursor-based pagination. It stops short of explaining page-size limits or what happens when a page is truncated, but those are documented in 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 dense sentences with zero filler, leading with what the tool returns and the default ordering before covering filters and paging. Every clause maps to a real capability.

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 8 parameters fully described in the schema, annotations covering safety, and no output schema, the description covers the essentials an agent needs to call it. Minor gaps remain around pagination edge cases and how to obtain list_id, but nothing blocking.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the key filters (campaign, date range) and the default sort, but adds no format or semantic detail beyond what the parameter descriptions already provide.

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

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

States a specific verb+resource ('The event history of one member') and enumerates the event kinds returned, so an agent knows exactly what it gets. It does not explicitly differentiate itself from laposta_get_member or laposta_get_member_history-style siblings, 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: fetch one member's events, optionally scoped to a campaign or date range. There is no explicit when-to-use versus laposta_get_member or when-not guidance, and no prerequisites such as needing list_id from laposta_list_lists (that hint lives only in the schema).

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 openWorldHint=true, so the safety profile is covered. The description adds useful detail about what figures are returned, but it does not disclose prerequisites like whether the campaign must have been sent, nor any pagination or error behavior.

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

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

The description is a single, front-loaded sentence with zero wasted words. It enumerates the key returned metrics efficiently.

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

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

Because there is no output schema, the description must indicate what the report contains, and it does list the core figures and ratios. It stops short of describing the response structure or units, but it is largely complete for a simple read-only report tool.

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

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

Schema description coverage is 100%, and the sole parameter campaign_id is fully documented in the schema, including where to obtain it. The description adds no parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description clearly identifies the resource: result figures for one campaign, including specific metrics. It is understandable in isolation, but it does not explicitly distinguish itself from siblings like laposta_get_campaign, laposta_list_reports, or laposta_get_campaign_history.

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 provides no explicit guidance on when to use this tool versus alternatives such as laposta_list_reports or laposta_get_campaign. The required campaign_id implies a single-campaign scope, but that is not stated as usage guidance.

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

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

readOnlyHint=true and openWorldHint=true already establish that this is a safe, account-wide read, so the description's main added value is enumerating returned fields. It says nothing about default ordering, whether the full account is returned, or result-size behavior, so the incremental disclosure is modest.

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

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

Two short sentences with zero padding, purpose front-loaded and paging noted second. Slight redundancy in restating what the schema already explains about limit/offset keeps it off 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 two-parameter read with no output schema, the description is adequate but thin: it omits ordering, whether pagination terminates, and what next_offset means in practice. Given the annotations already cover safety, this is the minimum viable level rather than 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 coverage is 100%, so the schema already documents defaults, bounds (max 500, min 0) and the next_offset handoff. The description only restates that limit/offset drive paging, adding no format or semantics beyond the structured fields, 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?

A specific verb and resource (list campaigns) plus the fields returned (name, subject, sender, recipient lists, delivery moments), which an agent can oppose to laposta_get_campaign. It stops short of explicitly naming the sibling it is not, leaving the list-vs-single distinction to be inferred from the name.

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

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

Only paging guidance is given ("Use limit/offset to page"), which is implied usage of the parameters rather than when to choose this tool over laposta_get_campaign or laposta_list_reports. No conditions, prerequisites, or exclusions are 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 and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious workflow context — that this is a prerequisite step for member mutations — which is the kind of information annotations cannot convey; only pagination/rate behavior is left unstated.

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

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

Two sentences, zero waste, with the returned-field detail front-loaded and the prerequisite call-out second. Nothing is padded or restated from the title.

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

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

With no output schema, the description responsibly enumerates the returned attributes, and the single required param is fully documented in the schema. A short note on ordering or pagination would make it complete, but an agent has everything needed to call and interpret it.

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

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

There is a single parameter at 100% schema description coverage, and the schema already names its source ('from laposta_list_lists'). The description adds no further meaning about list_id, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('List the custom fields of a mailing list') and enumerates exactly what each field entry contains (name, custom_name, datatype, required, options). This cleanly separates it from siblings like laposta_get_list or laposta_get_member without needing to open a schema.

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

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

'Call this before adding or updating a member' gives an explicit precondition tied to sibling operations, so the agent knows where this fits in a workflow. It stops short of naming the siblings outright or stating when not to use it, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description usefully adds that each list carries active/unsubscribed/cleaned member counts, which is the return shape an agent needs since there is no output schema. It does not mention pagination or account-size limits, leaving a small 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 with no filler: the first defines the operation and its output, the second gives the follow-up action. Front-loaded with the verb and resource.

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 covers what is returned and how to use the result, which is most of what an agent needs. The only omission is any note on result size or pagination behavior in large accounts.

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

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

The tool takes zero parameters and the description correctly describes none, so there is nothing for it to disambiguate. Baseline for a 0-param tool 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 all mailing lists of the Laposta account') plus the scope of what is returned (member counts). This is plainly distinguishable from laposta_get_list (single list) and laposta_list_members (members of one list) without opening a schema.

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

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

'Use the list_id in the other tools' establishes this as the discovery entry point that feeds the rest of the toolset, which is the key when-to-use signal. It stops short of naming exclusions or pointing at laposta_get_list as the single-list alternative, so it is clear context rather than a full routing rule.

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

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

With readOnlyHint=true already declared, the description still adds real value: it discloses pagination ('one page at a time') and flags that results contain personal data, advising minimal fetching. It stops short of describing rate limits or result shape, but the cursor/limit mechanics are covered in 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 sentences, zero waste: purpose and filter surface first, then the pagination/privacy constraint. 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 an 8-parameter read-only listing tool with full schema coverage and no output schema, the description covers purpose, filtering and the sensitive-data caveat. Only sibling routing and output expectations are thin, and the former is a minor gap given the clear plural/paginated framing.

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

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

Schema description coverage is 100%, so the schema already explains every parameter including cursor continuation and page-size truncation. The description names three of the filters (state, search, label) but adds no syntax or behavioral detail beyond what the schema states; 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 the members (subscribers) of a mailing list' — plus the paginated nature of the call. The plural 'members' and pagination framing implicitly separate it from the singular laposta_get_member, but no sibling is named explicitly.

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 dimensions (state, search, label) and the page-by-page usage are stated, and 'only fetch what the task needs' gives a usage constraint. However, it never says when to prefer this over laposta_get_member or laposta_list_segments when only one member or a segment view is needed.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the returned metric set and paging behavior, but says nothing about ordering, rate limits, or what happens for campaigns with no sends — modest added context beyond structured data.

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 returned data and ending with the paging hint; no filler. The metric list is slightly dense but informative rather than wasteful.

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

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

With no output schema, the description usefully enumerates the figures an agent will receive, which is the key missing context. Remaining gaps (sort order, empty-result behavior) are minor for a simple paginated read.

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

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

Schema coverage is 100% and both parameters already document defaults, maximums, and the next_offset paging idiom. The description's 'Use limit/offset to page' restates the schema rather than adding format or behavior 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 resource and enumerates the metrics returned (sent, accepted, opened, clicked, bounced, unsubscribed, with ratios), which is more than the title's 'List campaign reports'. It does not explicitly distinguish itself from siblings like laposta_get_report or laposta_list_campaigns, so an agent must infer the boundary.

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 only guidance is 'Use limit/offset to page', which covers mechanics but not when to choose this tool over laposta_get_report (single report) or laposta_list_campaigns (campaign metadata). Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the description's only burden is added context. The parenthetical about a segment id being 'a campaign recipient together with its list' is cryptic and does not explain pagination, ordering, or what an empty result means.

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 with the resource front-loaded. The trailing parenthetical is short but muddies rather than earns its place.

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

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

With one parameter and readOnly annotations, little is strictly required, but 'segments' is a domain term the agent cannot resolve and there is no output schema to reveal the return shape. The description leaves the agent guessing what a segment actually is.

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 list_id is documented in the schema with a pointer to laposta_list_lists. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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

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

States a clear verb and resource: list the segments belonging to a mailing list, with list_id as scope. However, it does not distinguish itself from siblings like laposta_list_members or laposta_list_fields, and 'segments' remains undefined in API terms.

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 indication of when an agent should call this rather than laposta_list_members or laposta_list_lists, and no prerequisites or follow-up steps. Usage is only implied by the tool name.

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

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

Annotations already disclose readOnly=false, destructive=false, idempotent=false, openWorld=true. The description adds real behavioral context the annotations can't: the campaign must have content and must not already be sent, and the write only reaches one address. It doesn't state likely failure modes or error behavior.

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

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

Two sentences with zero waste. The "WRITE:" prefix and the main action are front-loaded, and the negative scope statement follows immediately.

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

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

For a 2-parameter write with no output schema, the description covers preconditions, target, and scope of effect. Only the response/confirmation behavior is unaddressed, which is a minor gap.

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

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

Schema coverage is 100%, so both parameters are already documented, including the campaign_id provenance from laposta_list_campaigns. The description only reinforces the single-recipient constraint ("ONE email address"), so the baseline of 3 applies.

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

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

A specific verb plus resource ("send a test copy of a campaign") with explicit scope ("to ONE email address") and a negative clarifier ("Does not send the campaign to its recipients"). An agent can distinguish this from laposta_create_campaign or laposta_get_campaign 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?

The description establishes the context of use — verifying a campaign that already has content and hasn't been sent — which is a clear eligibility condition. It does not name a competing/alternative tool, so it stops short of full when-to-use guidance.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true; the description adds what is actually destroyed (existing content is overwritten), that nothing is dispatched, and that the response contains a validation report. It does not cover authorization requirements or whether a failed import_url fetch leaves the campaign untouched.

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

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

Two sentences, front-loaded with a 'WRITE:' marker, with no redundant restatement of the title or schema fields. Each clause carries distinct information: mode selection, side-effect boundary, and response contents.

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 summarizes what the reply's report contains (javascript, missing unsubscribe link, missing images). It could say more about failure behavior for a bad import_url or whether content is left intact on validation errors.

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 genuinely new meaning the schema lacks: the precedence rule that html overrides import_url when both are provided. It adds nothing about inline_css beyond the schema text.

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

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

States a specific verb and resource ('replace a campaign's content') and gives the two input modes with a precedence rule. 'Does not send anything' distinguishes it from laposta_send_test_email, and the word 'replace' distinguishes it from the read-only sibling laposta_get_campaign_content.

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 concrete selection rule between the two content sources ('html wins if both are given') and a clear negative boundary ('Does not send anything'). It does not explicitly name sibling tools to use instead for reading or sending, so it stops short of a full when/when-not map.

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 and idempotentHint; the description adds real context beyond them — partial-update semantics ('Only the fields you pass change') and the explicit unsubscribe path that constitutes the destructive case. It does not spell out whether unsubscribing is reversible or what permissions are required, so it falls just short of 5.

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

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

Three short sentences, mutation intent front-loaded, then the field semantics, then the alternative route. No sentence 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?

For a destructive mutation with no output schema, the description covers what changes, partial-update behavior, and the re-subscribe escape hatch. It omits failure modes (e.g. unknown member id) and confirmation/irreversibility details, which an agent handling a destructiveHint tool would benefit from.

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 update semantics the schema cannot express: only supplied fields mutate, and the state enum's purpose (unsubscribed) is framed as an action rather than a bare value. It does not restate custom_fields keying, which the schema already handles well.

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

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

Opens with an explicit 'WRITE:' marker and names the specific resource (member) and the exact operations (custom field values, email address, unsubscribe). An agent can distinguish it from laposta_add_member purely from the text.

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

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

Explicitly states what is NOT offered here (re-subscribing) and routes the agent to the Laposta app or laposta_add_member upsert, with the condition 'only when they asked for it'. That is a rare, genuinely actionable when/when-not boundary.

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