NewsMAN MCP by usefulapi

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

Annotations already declare write, idempotent, non-destructive behavior, and the description adds that existing tags stay, which is meaningful additive semantics. It does not cover error behavior, permissions, or partial-failure handling.

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 extremely short and front-loaded with 'WRITE:', then states the operation, additive behavior, and endpoint. Every element earns its place.

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

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

For a simple two-parameter mutation with rich annotations and full schema coverage, the description provides enough to call it correctly. It does not describe the response, but no output schema exists and the operation is straightforward.

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?

Both parameters have 100% schema description coverage, so the schema already carries parameter meaning. The description adds no format or constraint details beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource (add tags to a subscriber) and clarifies additive behavior so existing tags are preserved. It is clear, though it does not explicitly distinguish this tool from siblings like update_subscriber or add_subscriber_to_segment.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as update_subscriber (which may replace tags) or add_subscriber_to_segment. The additive note is behavioral context, not usage routing.

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

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

The "WRITE:" prefix and endpoint reinforce the mutation semantics already declared by readOnlyHint=false, and "(static)" flags a real behavioral constraint not expressible in annotations. However, it does not disclose what happens if the subscriber is already in the segment (the idempotentHint=true behavior) or any permission/rate-limit 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?

Two short fragments with no waste, and the write semantics are front-loaded. It is arguably over-terse, but nothing extraneous is present.

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

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

For a simple two-parameter write with full schema coverage and annotations covering the safety profile, the definition is minimally adequate. It omits prerequisite conditions (segment type, subscriber existence) and duplicate-membership behavior that an agent would want before invoking.

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 (segment_id, subscriber_id) are already documented in the schema. The description adds nothing beyond that, which is the baseline expectation when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ("add a subscriber to a (static) segment") and the verb distinguishes it from the sibling newsman_remove_subscriber_from_segment. The "(static)" qualifier adds a meaningful scope distinction, though 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?

There is no explicit when-to-use guidance, no mention of prerequisites (e.g. segment must exist and be static, subscriber must exist), and no routing to alternatives. The "(static)" hint implies a constraint but leaves the agent to infer it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description's real contribution is the scoping qualifier 'active (subscribed)', which tells the agent unsubscribed/inactive contacts are excluded from the count. It says nothing about cost, rate limits, or whether the count is exact or eventual.

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 meaning and followed by the endpoint reference; no filler. Slight deduction only because the first sentence is a noun fragment rather than a stated action, which reads marginally less like an instruction.

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-only counter with full schema coverage and annotations covering the safety profile, the description supplies enough to call it correctly. A return-value note is unnecessary absent an output schema, though a brief hint that the response is a numeric total would have closed the last 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?

There is a single parameter with 100% schema description coverage ('NewsMAN list id.'), so the schema carries the semantics. The description adds nothing further about list_id, e.g. whether a numeric id and string id are interchangeable or what happens for an unknown list — baseline 3 is appropriate.

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

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

The description states a specific resource and metric: the count of active (subscribed) subscribers for a given list, plus the underlying endpoint GET /v2/list/count. The phrase 'of a list' implicitly separates it from newsman_count_segment_subscribers and newsman_list_subscribers, though it never names those 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?

Usage is only implied: 'of a list' suggests using this instead of the segment-level counter when a list-wide total is wanted, and 'active (subscribed)' signals it is not a full roster lookup. There is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful semantics by specifying that only active subscribers are counted, but it does not explain error behavior, authentication needs, or the exact return shape beyond implying a number.

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

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

The description is two short sentences, front-loads the result being returned, and includes the endpoint without unnecessary detail. Every element earns its place.

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

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

For a simple read-only count tool with one fully documented parameter and annotations covering safety, the description is mostly complete. It indicates the return value conceptually, though it does not explicitly state that the result is an integer count or describe edge cases such as an invalid segment_id.

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 already documents that segment_id comes from newsman_list_segments. The description adds no additional parameter semantics, so it meets the baseline for fully covered schemas without exceeding it.

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

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

The description clearly states the resource and the metric: active subscribers within a segment, reinforced by the endpoint. It is distinguishable from list_segment_subscribers by implying a count rather than a listing, though it does not explicitly contrast with the sibling count_list_subscribers.

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

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

There is no explicit guidance on when to use this tool versus list_segment_subscribers or count_list_subscribers. The intended use is inferable from the description, but no alternatives, 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 destructiveHint=false, so the safety profile is covered. The description adds the upstream endpoint (GET /v2/automation/getWorkflow) and the response field inventory, but says nothing about failure behavior (e.g. unknown workflow_id) or the stats/preview-link payload shape.

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

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

Two short sentences, front-loaded with the returned fields. The trailing raw endpoint path is mildly redundant developer detail but harmless and compact.

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

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

With no output schema, the field inventory (name, type, status, version, recurrence, stats, preview links) is genuinely useful and covers what the agent gets back. Missing only error/not-found semantics, which is minor for a read-only single-entity getter.

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 already documents that the id comes from newsman_list_automations, so the schema does the heavy lifting. The description adds no format or constraint detail beyond that, which is the expected baseline.

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

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

States a specific verb implied (retrieve one workflow) plus the exact payload: name, type, status, version, recurrence, stats and preview links. That distinguishes it from bulk siblings in spirit, but it never names newsman_list_automations or newsman_get_automation_stats, so the differentiation is implicit rather than stated.

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

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

The enumerated returned fields imply the 'inspect a single workflow' use case, and the schema note ties the id to newsman_list_automations. However there is no explicit when-to-use or when-not guidance versus newsman_list_automations or newsman_get_automation_stats.

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 read-only, non-destructive behavior. The description adds useful behavioral context beyond annotations: daily granularity, the specific metric set returned, workflow scoping, and the 90-day maximum period.

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

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

Two compact sentences, front-loading the resource and metrics before the optional filters and endpoint. Every sentence earns its place with no repetition or 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?

Given five parameters, full schema documentation, annotations, and no output schema, the description provides enough request context to call the tool correctly. It lists the metrics returned, though it does not describe the exact response shape for daily stats.

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

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

Schema description coverage is 100%, so all five parameters are already well documented in the schema. The description reinforces the period alternatives and workflow filtering but adds little syntax or meaning beyond what the schema provides.

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

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

The description states a specific resource and scope: daily stats for automations of a list, with named metrics. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as newsman_get_automation or newsman_get_newsletter_stats.

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

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

It explains the available period options (last N days or start_date/stop_date with a 90-day cap) and optional workflow filtering. However, it gives no explicit guidance on when to use this tool versus get_automation, list_automations, or newsletter stats.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it lists the status values (new, running, finished, error) and notes that times and the last error are returned.

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

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

The description is a single front-loaded sentence that states the purpose, status values, and returned information, followed by the endpoint. Every part earns its place with no redundant wording.

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

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

Given a simple one-parameter read-only tool with full schema coverage, annotations, and no output schema, the description supplies enough detail: what is looked up, the possible states, and the return components (times and last 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 description coverage is 100%, and the schema already documents the sole import_id parameter. The description mentions 'by import_id' but does not add format or semantic detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Status of a background subscriber import by import_id') and enumerates the possible statuses. It is distinct from all sibling tools, which focus on subscribers, lists, segments, newsletters, and automations rather than imports.

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 context is clear: use this to check the status of a background subscriber import identified by import_id. It does not explicitly name when-not-to-use cases or alternatives, but there is no sibling tool covering import status, so the intended usage 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=true and destructiveHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral disclosure beyond that: the list secret is never returned, which tells the agent a sensitive field is redacted, and it enumerates the readable field set. It does not cover permissions or rate limits, but for a simple getter this is above baseline.

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 of substance plus a compact API path reference; the field enumeration is front-loaded and nothing is wasted. The trailing 'GET /v2/list/getProps' is marginally redundant but functions as a useful mapping to upstream docs.

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 the return shape, and it does so by listing the field categories returned plus the one field deliberately omitted. For a one-parameter read-only getter, an agent has enough to select and call it correctly; only permission/pagination-style concerns are unaddressed.

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

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

Schema description coverage is 100% and the single parameter already documents itself ('NewsMAN list id (from newsman_list_lists)'). The description adds nothing about the id (accepted types, format, where to obtain it), so the baseline 3 applies.

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

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

The description names a specific resource ('properties of one list') and enumerates the concrete fields returned (sender name/email, owner contact, site, link parameters, send rate), which makes it clearly distinguishable from the sibling list-enumeration tool newsman_list_lists. The retrieval verb is implied by 'Properties of' rather than stated, but the scope is unambiguous.

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

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

Usage is implied rather than stated: the reader can infer this is for inspecting a single known list, and the schema points back to newsman_list_lists as the source of the id. However, there is no explicit when-to-use/when-not guidance or comparison against related getters like newsman_get_list_growth or newsman_count_list_subscribers.

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, destructiveHint=false, so the safety profile is covered. The description adds real behavioral context: the 90-day maximum period and the concrete metric set returned, plus the underlying GET endpoint. It stops short of rate limits or auth requirements, but that is a minor gap given 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 tight sentences plus the endpoint: what it returns is front-loaded, parameter selection follows, and nothing is wasted. Appropriately sized for a simple read tool.

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

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

With no output schema, the description usefully enumerates the returned metrics so an agent knows what a call yields. Combined with annotations covering safety and 100% schema coverage, an agent has enough to invoke it correctly; only return shape details (e.g., ordering/field names) are absent.

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

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

Schema coverage is 100%, so all four parameters are already documented with types, ranges and format patterns. The description only restates the days-vs-dates alternative and the 90-day cap that the schema already conveys, adding no syntax or format detail beyond it. 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 ('daily evolution of a list') and enumerates the exact metrics returned (total/eligible subscribers, unsubscribes, spam reports, hard bounces per day). This clearly distinguishes it from snapshot-style siblings like newsman_count_list_subscribers, though 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?

Provides clear mutually-exclusive parameter guidance ('Give days OR start_date/stop_date'), which is a form of usage guidance. However, it never states when to reach for this tool versus alternatives such as count_list_subscribers, nor any exclusions beyond the 90-day cap.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that long HTML is clipped and lists the returned data, which is useful behavioral context beyond annotations, though auth and error behavior are 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?

The definition is front-loaded and compact: one property summary, one clipping caveat, and the endpoint. Every sentence contributes useful information.

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

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

For a simple read-only tool with no output schema, the description enumerates the key return fields and notes HTML clipping, which is enough to call it correctly. It leaves minor gaps around error behavior and exact field types, but those are small.

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 required newsletter_id is fully described in the schema as coming from newsman_list_newsletters. The description adds no further parameter semantics, so baseline 3 applies.

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

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

The description names the resource (one newsletter), enumerates the returned properties, and gives the endpoint. It is clearly a single-item read, though it does not explicitly contrast itself with newsman_list_newsletters.

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 explicit when-to-use guidance or alternatives are stated. The schema notes the id comes from newsman_list_newsletters, but the description itself does not tell an agent when to prefer this over list or stats siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint and the shape of the returned data (click counts, last click time), which is useful context. It says nothing about volume limits, ordering, or whether zero-click links are included.

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

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

Two compact sentences that front-load the returned content and close with the endpoint; there is no filler or restated title content.

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 no output schema, the description covers what is returned and which newsletter it applies to. Minor gaps (ordering, aggregation semantics of 'last click time') remain but nothing blocks correct invocation.

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

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

Schema description coverage is 100% and the single newsletter_id parameter is documented in the schema as the NewsMAN newsletter id, including its type constraints. The description only implies that the id refers to one newsletter and adds no format or lookup detail beyond the schema, so baseline 3 applies.

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

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

The description names a specific resource and scope ('the links clicked in one newsletter') and enumerates what is returned (click counts, last click time), so an agent knows exactly what it retrieves. It does not explicitly contrast itself with the nearby newsman_get_newsletter_stats, which is the main thing keeping it from a 5.

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

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

There is no statement of when to use this tool versus alternatives such as newsman_get_newsletter_stats or newsman_get_newsletter — only a restatement of the output. The usage is inferable from the name and output description, but no guidance or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful behavioral value by enumerating the exact metric set returned and citing the underlying GET endpoint, but says nothing about auth requirements, rate limits, or whether stats are cumulative or per-send.

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

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

Two short sentences, front-loaded with the metric list, with no redundant restatement of the title. Every clause contributes 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?

There is no output schema, and the description compensates well by listing the returned fields (sent, views, clicks, unsubscribes, bounces, spam reports, rates). It is nearly complete for a simple read-only stat lookup; only the shape/units of 'rates' and time-window semantics are left implicit.

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 there is only one parameter (newsletter_id), so the schema already carries the full burden. The description does not elaborate on the id format or what happens with an invalid id, 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 ('stats of one newsletter') and enumerates the metrics returned, so the agent knows exactly what data comes back. It does not explicitly differentiate itself from close siblings like newsman_get_newsletter or newsman_get_newsletter_clicked_links, which keeps it at 4 rather than 5.

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

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

Gives no guidance on when to call this versus newsman_get_newsletter (metadata) or newsman_get_newsletter_clicked_links (per-link detail). The usage is only implied by the resource name; there are no exclusions, prerequisites, or alternative routing.

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

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

Annotations already declare readOnly and non-destructive, so the description is free to add value elsewhere—and it does by enumerating what is returned (status and dates, name, IP, custom properties, segments), which matters since there is no output schema. It does not say what happens when the email is not found in the list, which is the main remaining gap.

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

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

Two short sentences, front-loaded with the resource and lookup key, with the endpoint as a compact trailing reference. The opening fragment ('One subscriber of a list by email address:') is slightly clipped but still efficient.

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

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

With no output schema, the description steps in to list the returned fields, which is the key missing information an agent needs. Only not-found/error behavior is absent, which is a minor gap for a read-only 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%, and both parameters (email, list_id) are documented there. The description only reinforces that the lookup is list-scoped and keyed on email; 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—retrieving one subscriber of a list by email—and even names the underlying endpoint (GET /v2/subscriber/getByEmail). It implicitly differentiates from newsman_get_subscriber_by_id via the 'by email' qualifier, but never names the 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 email-based lookup key is stated, which hints at when this tool applies versus an ID lookup, but there is no explicit guidance on choosing between this and newsman_get_subscriber_by_id or newsman_search_subscribers. Usage must be inferred from the sibling names.

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 value by enumerating the returned fields (status/dates, name, IP, custom properties, segments), which matters because there is no output schema. It gives no detail on what happens for an unknown id or any rate/permission constraints.

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 telegraphic sentence plus the REST endpoint; zero padding and the return-field list is front-loaded. The fragment style ('One subscriber by...') is slightly clipped but nothing is wasted.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, the description carries the essential pieces: identity semantics and the shape of the response. Missing only edge-case behavior (not-found handling) and any differentiation from the similarly named sibling.

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

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

Only one parameter, and the schema fully documents it (100% coverage, 'NewsMAN subscriber id', string or integer). The description restates 'by subscriber_id' without adding format, source, or lookup-failure semantics, 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 ('one subscriber by subscriber_id') and enumerates what comes back (status, dates, name, IP, custom properties, segments), so the agent knows this is a single-record retrieval. It does not distinguish itself from the sibling newsman_get_subscriber or from newsman_search_subscribers, which is the main clarity gap.

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

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

There is no guidance about when to use this versus newsman_get_subscriber, newsman_search_subscribers, or newsman_list_subscribers. The presence of both newsman_get_subscriber and newsman_get_subscriber_by_id in the sibling list makes this omission costly — the agent must guess which lookup key each expects.

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

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

Annotations already cover safety (readOnly=true, destructive=false, openWorld=true), so the description's job is the extra behavior — and it delivers the key constraint: only the last 100 actions, plus the shape of each record. It does not mention ordering guarantees beyond 'last', pagination (there is no cursor param), or what happens to a nonexistent subscriber.

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 that names the cap first, then the event taxonomy, then the metadata fields, plus the endpoint. Nothing is padded.

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

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

With no output schema, the description usefully sketches the return records (event type, date, newsletter/link metadata), which is what the agent needs to decide to call it. It would be complete with a note on ordering and behavior for unknown ids.

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 there is a single required subscriber_id whose schema already documents it as a NewsMAN subscriber id (string or integer). The description adds nothing about the id format or accepted variants, so the baseline 3 applies.

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

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

States a specific verb+resource ('subscriber history') and enumerates the event types it returns, so the agent knows exactly what this returns versus a plain profile fetch. It never names the near-duplicate siblings newsman_get_subscriber / newsman_get_subscriber_by_id, leaving that distinction to be inferred.

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

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

Usage is only implied by the content ('actions... each with a date'), suggesting this is for activity/timeline questions, but there is no explicit when-to-use or when-not-to-use guidance and no reference to the sibling profile endpoints.

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 structurally. The description adds that results carry status/version/stats fields, which is useful, but says nothing about pagination, result limits, or error behavior for an invalid list_id.

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

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

Two compact sentences with the resource, returned fields, filters, and endpoint packed in without filler. Slightly dense rather than front-loaded on purpose, but no wasted text.

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

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

With no output schema, the description compensates by listing the returned fields, the filter surface, and the underlying endpoint. For a read-only list endpoint with fully documented params, that is close to complete; only pagination/ordering behavior is unstated.

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

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

Schema description coverage is 100%, so all six parameters including the status enum values and date format patterns are already documented. The description merely restates the filter names without adding format or edge-case semantics, so baseline 3 applies.

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

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

States a specific verb+resource: lists automation workflows scoped to a single list, and enumerates the returned fields (workflow_id, name, type, status, version, stats). It does not explicitly contrast itself with get_automation, so it misses the highest tier, but the 'of a list' scope makes it distinguishable.

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?

Mentions the available filters (name, status, last-updated range), which implies when the tool is useful, but gives no explicit guidance about when to pick this over get_automation or get_automation_stats, nor any prerequisites for list_id.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds a genuine behavioral fact — results are filtered to what the key can access — but says nothing about pagination, ordering, or handling of accounts with no lists.

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 clauses: what is returned, why it matters, and the endpoint. The call-to-action ('Start here') is front-loaded after the resource statement with no filler sentences.

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

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

There is no output schema, but the description names the key return fields, which compensates well. Remaining gaps are secondary (pagination, empty-result behavior); the essential information for a no-arg discovery call is present.

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

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

Zero parameters, so the baseline of 4 applies; there is no parameter semantics to explain. The description also does not falsely suggest optional filters that would confuse an agent about the empty 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 ('All email lists (and SMS lists)'), the access scope ('this key can access'), and the returned fields (list_id, list_name, list_type). This clearly separates it from single-item sibling newsman_get_list and from newsman_list_segments/newsman_list_subscribers.

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

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

'Start here: most other tools need a list_id' explicitly positions it as the entry point and implies when to call it first. It stops short of naming which siblings require a list_id, so the agent still has to infer the dependency chain, but the guidance is concrete rather than implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: result paging, the default of all statuses, and the exact field set returned. It does not mention auth requirements, rate limits or page-size ceilings, keeping it short of a 5.

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

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

Four compact sentences, front-loaded with the resource and return shape, then filters, then paging and endpoint. Dense but every clause carries information; the trailing 'GET /v2/newsletter/all' is marginal for an agent but small.

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

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

With no output schema, the description compensates by listing the returned fields, and it explains every filter mode for a 7-parameter tool. Nothing essential for a correct invocation is missing, though pagination boundaries and ordering of results are not stated.

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 decodes the status codes (-1 cancelled, 0 new, 1 confirmed, 2 sending, 3 paused, 4 resumed, 5 sent) and shows comma-list syntax, which the schema only expresses as a numeric pattern. It also clarifies that 'days' is an alternative to start_date/stop_date.

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

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

Names a specific verb+resource with scope ('Newsletters (campaigns) of a list') and enumerates the returned fields, which clearly separates it from newsman_get_newsletter (single item) and newsman_list_lists. An agent can identify both what it retrieves and at what granularity directly from the first sentence.

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 explains the three filtering modes (status, creation date range, last N days) and paging, which is usage guidance for parameters rather than tool selection. It never states when to reach for this over newsman_get_newsletter_stats or newsman_get_newsletter, and offers no exclusions — usage is only implied.

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

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

Annotations already cover the read-only, open-world, non-destructive profile, and the description adds genuinely new operational context: a rate limit of 20 calls per minute and the underlying GET /v2/segment/all endpoint. It also decodes the status field values (0 idle … 3 searching), which an agent needs to interpret results, though it says nothing about behavior when the list id is invalid or when segments are mid-import.

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 compact sentences with no padding: return shape first, then rate limit, then endpoint, so the most useful information is front-loaded. The opening fragment is verb-less ('The segments of a list with…'), a minor structural weakness but not wasteful.

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

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

With no output schema, the description appropriately documents the return fields and status enum values, and adds a rate limit the agent must respect. An agent has enough to call the tool correctly; only error/empty-list behavior is unstated.

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

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

There is a single parameter with 100% schema description coverage ('NewsMAN list id'), so the schema carries parameter documentation and 3 is the correct baseline. The description adds no format or validity rules for list_id beyond what the schema already states.

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

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

The description names the resource precisely ('segments of a list') and enumerates the returned fields, so the agent knows exactly what it retrieves. It does not explicitly contrast itself with siblings like newsman_list_segment_subscribers or newsman_count_segment_subscribers, which keeps it from 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?

The description gives no when-to-use / when-not-to-use guidance and never names an alternative among the many segment-related siblings. The scoping to a single list (via list_id) is implied but nothing directs the agent to this tool over newsman_list_segment_subscribers.

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 behavioral context beyond that: pagination semantics (page starts at 0, up to 1000 per page) and the shape of each returned record (subscriber_id and email). It does not discuss rate limits or total-count behavior, but for a read-only listing this is solid.

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

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

Three short fragments with zero filler, and the resource identity is front-loaded before pagination details. It is telegraphic rather than flowing prose, but nothing is wasted.

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

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

There is no output schema, so the description compensates by naming the returned fields (subscriber_id, email), and pagination is explained. Combined with full schema coverage and read-only annotations, an agent has what it needs to call this correctly; only total-count/empty-result behavior is unspecified.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including defaults and min/max bounds. The description restates the pagination rules ('page from 0, up to 1000 per page') without adding new meaning, 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 the specific resource (subscribers of a segment) and enumerates the returned fields (subscriber_id and email), which makes the output distinguishable from newsman_list_subscribers. It does not explicitly name siblings, but the scope 'of a segment' vs. all subscribers is clear from the text plus the required segment_id.

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

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

Usage is only implied: an agent can infer this is the tool for enumerating members of a segment versus counting them (newsman_count_segment_subscribers) or listing all subscribers. There is no explicit when-to-use, when-not, or alternative routing statement.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful paging behavior (page from 0, up to 1000 per page) and, importantly, the shape of each returned item (subscriber_id, email, status date) since there is no output schema. It says nothing about ordering of results 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?

Three tight sentences, front-loaded with the core selection criteria before optional filtering, paging and item shape. The trailing 'GET /v2/list/getSubscribers' is marginal value for an agent but does not bloat the text.

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

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

With no output schema, the description compensates by naming the fields of each returned subscriber, and it covers pagination and the date format semantics. Nothing crucial for correct invocation is missing, though result ordering would have closed the gap entirely.

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

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

Schema coverage is 100%, so all five parameters are already documented, including the status enum and page/limit bounds. The description restates the status values, page origin and 1000-per-page cap, adding no format or behavioral detail beyond the schema—correct baseline 3.

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

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

States a specific verb (list), resource (subscribers of a list), and the discriminating axis (status enum plus optional join date). It implicitly separates itself from siblings like newsman_count_list_subscribers and newsman_list_segment_subscribers, but never names those alternatives 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 description explains the optional 'since' filter (joined on or after a UTC date), which implies when to use it. It gives no explicit guidance on when to pick this tool instead of count_list_subscribers, search_subscribers, or list_segment_subscribers, leaving selection logic to inference.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false; the description earns extra credit by naming the blast radius ('the subscriber stays on the list'), which tells the agent exactly what is and is not destroyed. It does not mention failure modes or return payload, but that is a minor gap given the annotation coverage.

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

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

A single compact sentence, front-loaded with 'WRITE:' so the mutation nature is immediately visible, followed by the clarifying parenthetical and endpoint. Nothing is wasted.

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

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

For a two-parameter write with full schema coverage and no output schema, the description covers purpose, mutation type, and scope caveat adequately. Only the no-output expectation and any permission requirements are left unstated, which is a small gap.

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

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

Schema description coverage is 100% and both parameters are documented as 'NewsMAN subscriber id' and 'NewsMAN segment id'. The description adds no syntax, format, or accepted-value detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('remove a subscriber from a segment') and adds the crucial scope clarification that the subscriber remains on the list, which cleanly separates it from unsubscribe_email and the add_to_segment sibling. The endpoint path reinforces the exact operation.

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 parenthetical '(the subscriber stays on the list)' implies the contrast with unsubscribe_email by clarifying this is a segment-scoped removal, but there is no explicit statement of when to choose this tool versus unsubscribe_email or add_subscriber_to_segment. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context with pagination behavior (page from 0, up to 1000 per page) and the underlying GET endpoint, but says nothing about result ordering or authentication.

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

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

Two compact sentences with zero waste; the filter set is front-loaded and the paging/endpoint detail follows. 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 read-only search tool with full schema coverage and clear annotations, the definition is essentially complete. Return shape is not described, but no output schema exists to lean on, leaving a minor gap.

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

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

Schema description coverage is 100%, so all six parameters, including the status enum and since format, are already documented. The description's mention of paging and the since filter restates what the schema provides, so baseline 3 applies.

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

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

States a specific verb (search) and resource (subscribers of a list) plus the filter dimensions (keywords, status, since). It clearly separates itself from list_subscribers and get_subscriber by being a filtered search, though it doesn't name those siblings 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?

Usage is implied by the filters described and the 'optionally' qualifier, but there is no explicit when-to-use guidance or routing to alternatives like list_subscribers for unfiltered 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=false, destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-redundant behavior: no confirmation email, subscriber active immediately, and the returned subscriber_id. It still omits the key destructive detail for an upsert tool — whether existing props/firstname/lastname are merged or overwritten on an existing subscriber.

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 dense sentences, front-loaded with operation type and resource, then permissions/consent, then side-effect (no confirmation email), then return value and endpoint. Nothing is redundant with the schema or annotations.

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

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

For a 6-param tool with a nested props object and no output schema, the description covers operation type, consent prerequisite, tag convention, immediate activation, and the return field. The remaining gap is merge-vs-replace semantics on the update path, which matters given destructiveHint=true.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema does not: the tag_ key prefix convention in props that turns a custom property into a tag. The example in the schema overlaps with this, but the naming convention as a mechanism is explained only here.

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 ('subscribe an email address to a list') plus the upsert nuance ('or update it if it exists'), which is exactly what separates it from newsman_update_subscriber and newsman_unsubscribe_email. The 'WRITE:' prefix and the concrete endpoint make the operation type unambiguous.

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

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

'Only use for people who gave consent' gives a real gating condition for when to call it, and the upsert wording tells the agent it need not pre-check existence with newsman_get_subscriber. However, no alternative is named for the case where the agent should explicitly update rather than subscribe.

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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds the 'WRITE:' marker, the returned subscriber_id, and the underlying endpoint, but says nothing about whether the subscriber record is retained or whether the unsubscribe can be reversed.

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 compact clauses with the write semantics front-loaded, the effect second, and the return value plus endpoint last. No filler sentences.

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

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

For a 3-parameter tool with no output schema, the description usefully states what is returned (subscriber_id) and the scope of the effect. It falls just short of full completeness by omitting any note on permissions, error conditions, or what happens to the subscriber record after unsubscribing.

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

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

Schema description coverage is 100%, so all three parameters (email, list_id, ip) are documented in the schema itself, including the ip default of 0.0.0.0. The description only implies list_id via 'from a list' and adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('unsubscribe') and resource (an email address) plus the effect scope ('from a list, so it no longer receives campaigns from that list'). It is easily separable from the sibling newsman_subscribe_email, though it never names the sibling 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?

Usage is implied by the stated outcome: call this when a contact should stop receiving campaigns for a given list. There is no explicit when-not guidance, no prerequisites, and no mention of alternatives such as newsman_update_subscriber or newsman_remove_subscriber_from_segment for related operations.

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 and idempotentHint=true, so the safety profile is covered. The description adds partial-update behavior, which is useful, but for a tool flagged destructive it says nothing about the consequences of overwriting an email address (re-verification, opt-in reset) or failure modes for an unknown subscriber_id.

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

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

Two compact sentences plus the endpoint, front-loaded with the WRITE marker and the affected fields. Every sentence carries information; nothing is padding.

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

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

For a 4-parameter partial-update tool with full schema coverage and rich annotations and no output schema, the description covers intent, mutation semantics and endpoint. The remaining gap is the unmentioned required subscriber_id and the lack of any note on downstream effects of an email change.

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

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

Schema description coverage is 100%, so each of the four parameters is already documented in the schema; the description adds nothing beyond echoing the three updatable field names. It never mentions subscriber_id, the one required parameter, and does not clarify that it accepts either a string or an integer id.

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 the email, first name or last name of a subscriber') and prefixes it with 'WRITE', so the mutation intent is unmistakable. The updatable fields are enumerated, which cleanly separates it from read siblings like newsman_get_subscriber and newsman_list_subscribers, though 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?

'Give only the fields to change; the others are left as they are' is real invocation guidance on partial-update semantics, telling the agent not to resend unchanged data. It lacks any when-not-to-use note (e.g., use newsman_subscribe_email for new contacts) and says nothing about what is required beyond the implied id.

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