Robly MCP by usefulapi

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

Goes beyond the annotations by disclosing a real side effect: include_autoresponder triggers autoresponders that EMAIL the contact, which is a non-obvious external consequence. Also surfaces idempotency-adjacent risk implicitly ('existing contact'), though it never says what happens when the contact is already on the list.

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 class front-loaded, and the endpoint appended for traceability. Nothing wasted, though the raw POST path contributes little to tool selection.

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 full schema coverage and a destructive annotation already flagging risk, the definition is nearly complete. The remaining gap is behavior when the contact is already listed or when the email matches no existing member.

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 email/member_id alternation and sub_list_id sourcing are already documented. The description only re-emphasizes the autoresponder email behavior, adding little beyond the schema's own wording.

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 ('put an existing contact on a list') and prefixes 'WRITE:' so the mutation class is immediate. The word 'existing' implicitly separates it from robly_subscribe_contact, though that sibling is never named.

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?

'Existing contact' implies the prerequisite that the contact already be in the account, and the alternative for new contacts (subscribe_contact) is inferable but not stated. No explicit when-not or exclusion guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description's mention of "GET /api/v1/contacts/exists_in_sub_list" largely restates that it is a read. It adds the useful constraint that the check is scoped to exactly one contact and one list, but says nothing about the response shape or whether a miss is an error versus a false answer.

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

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

Two short sentences with the predicate front-loaded and zero padding. The trailing API path is mild filler but does confirm the underlying read semantics without obscuring the main clause.

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 three parameters and no output schema, the description should tell the agent what it gets back (a boolean or membership record) and how a non-member is represented. That return-value gap is the main missing piece; the input side is fully covered by the schema.

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

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

Schema coverage is 100% and each parameter already documents itself, including the email-or-member_id exclusivity. The description's "by email or member id" merely echoes the schema, adding no format or precedence guidance beyond 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?

States a precise predicate and resource: whether one contact, identified by email or member id, belongs to one list. This is unmistakably distinct from the sibling mutation tools (add/remove/subscribe) that share the same list vocabulary.

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 single-contact, single-list scope implies when to use it, but there is no explicit statement of when to prefer this over robly_find_contact or robly_list_contacts, nor any prerequisite such as needing a sub_list_id from robly_list_sub_lists.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false; the description adds the concrete reason — that duplicate names are not detected server-side, so repeat calls can silently create duplicates. It also notes the new list is empty. It doesn't describe what is returned (e.g., new list ID), which limits follow-up use.

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, with the WRITE marker and the core action front-loaded. Every sentence carries information: action, duplicate caveat, remediation step, endpoint.

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

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

For a single-parameter mutation with rich annotations, the description covers the main risk (duplicates) and the pre-check. The only omission is the return value, which matters since there is no output schema and the agent may need the new list's identifier.

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 only one parameter (name) exists, with its own description and length bounds. The description adds nothing beyond confirming the list is created empty; 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 ("create a new, empty sub list") and prefixes it with WRITE, making the mutation nature unmistakable. It is clearly distinguishable from siblings robly_list_sub_lists and robly_rename_sub_list.

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 instructs the agent to check robly_list_sub_lists first, because Robly won't report duplicates. That is real routing guidance to a named sibling, though it covers only the duplicate pre-check rather than broader when-not-to-use conditions.

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, non-destructive, open-world profile, and the description adds real behavior beyond them: the not-found case is spelled out ('Returns found: false when Robly has no such contact') and the underlying endpoint is disclosed. It stops short of describing error/auth behavior or pagination, which keeps it from a 5.

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

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

Two compact sentences: identity of the tool first, return payload second, edge-case and endpoint last. Every clause carries information and nothing is repeated from 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 read-only lookup with full schema coverage and no output schema, the description covers inputs, the meaningful returned fields, and the not-found case, which is enough to call it confidently. It omits auth/rate-limit expectations and whether only one of email/member_id may be supplied, small residual gaps for an open-world API.

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%, with each parameter already documented including the 'this OR that' constraint for email/member_id, so the description need not carry this dimension. Its phrase 'on request, the lists and data fields' loosely maps to include_sub_lists/include_fields but adds no format or precedence 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 opens with a specific verb and resource ('Look up one contact') and enumerates the returned facts (status, subscription date, sign-up source, lists, data fields). 'One contact' implicitly separates it from the plural robly_list_contacts sibling, so an agent can pick between them 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?

It states the two lookup keys and that lists/data fields come only 'on request', which guides parameter choice, but never says when to prefer this over robly_list_contacts, robly_check_list_membership, or robly_update_contact, and gives no exclusions. Usage is therefore 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 safety profile is covered. The description adds meaningful behavioral context: default visibility is public-only and include_all exposes non-public fields and lists. It does not discuss auth or rate limits, but that is acceptable given 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?

The description is short and front-loads the resource scope and default behavior. The sentence is a fragment and the endpoint path is somewhat redundant, but there is no wasted exposition.

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 one optional boolean parameter and no output schema, the description adequately states what is returned (data fields and sub lists) and the default vs include_all scope. The remaining gap is around response structure, which is minor here.

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

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

Schema coverage is 100%, so the schema already documents include_all as 'Also include non-public fields and lists.' The description restates the default public-only behavior, adding slight clarity but no syntax or usage detail beyond the schema.

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

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

The description identifies a specific resource: the fields and sub lists available through the sign-up API. It lacks an explicit verb but clearly distinguishes the sign-up form context from generic field/list siblings. The endpoint path reinforces purpose.

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 explains that public fields/lists are returned by default and that include_all expands scope. However, it gives no explicit guidance on when to use this tool versus robly_list_fields or robly_list_sub_lists, nor does it mention prerequisites or alternatives.

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

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

Annotations already establish readOnly/non-destructive/openWorld, and the description adds genuinely useful behavior beyond them: newest-first ordering, the hard page cap of 100, the absence of a total count, and the offset-chaining pattern. It does not discuss error behavior or rate limits, keeping it out of the top band.

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 dense paragraph, front-loaded with verb, resource and ordering, then filters, then paging caveats. Every clause carries information an agent needs; nothing is repeated from the schema.

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

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

With no output schema, the description compensates by enumerating returned fields (id, email, flags, dates, source, timestamps) and disclosing the missing total. For a 7-parameter read-only list tool this is sufficient to call 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%, so the baseline is 3, but the description adds real semantics the schema cannot: what the include_* flags yield in the response, how the page chain works across calls, and that no total is available to compute remaining pages. That raises it above baseline.

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

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

States a specific verb and resource ("List contacts (members) of the Robly account") and enumerates the returned fields, so an agent can tell it apart from the single-record robly_find_contact. It stops short of naming sibling tools explicitly, so it falls just short of a 5.

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

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

Gives clear usage context: default newest-first ordering, the three filter axes (status, list, updated_since), optional expansion via include_fields/include_sub_lists, and paging instructions ("pass next_offset from the previous reply"). No explicit when-not-to-use or named alternative is given, but the operating context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description adds the underlying endpoint and the shape of the returned fields, but says nothing about auth, pagination, 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?

One dense sentence that front-loads the verb and resource, then the useful cross-reference to consuming tools. Every clause earns its place, though the parenthetical example list is slightly redundant with the enumerated fields.

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

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

With no output schema, the description usefully tells the agent what fields come back and what the user_tag is for, which is exactly the missing piece. Minor gap: it doesn't clarify when to set include_all, leaving that entirely to the schema.

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

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

Schema coverage is 100% and the single parameter include_all is fully documented in the schema, so the schema does the heavy lifting. The description never mentions include_all or what 'hidden from public sign-up forms' means, so it adds nothing beyond the schema. 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?

Specific verb (List) plus resource (contact data fields), and it enumerates the returned attributes (id, label, type, required flag, user_tag). It also names the sibling tools that consume the user_tag key, making it distinguishable from list/contact tools in the sibling set.

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

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

Implies its role as a discovery step by stating that robly_subscribe_contact and robly_update_contact use the returned user_tag as the field key. No explicit 'when not to use' or prerequisite ordering is given, but the context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds real value beyond that by disclosing the default visibility scope (public lists only) and the underlying endpoint GET /api/v1/sub_lists/show, but says nothing about pagination or result volume for a potentially unbounded listing.

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, no filler, with the resource definition and default scope front-loaded before the usage hint and endpoint. 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 one-optional-parameter read-only listing with no output schema, the description supplies the missing return shape (id, name, position, timestamps) and the default filtering scope, which are exactly the gaps structured fields leave open.

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 include_all is already documented as 'Also include non-public lists.' The description reinforces this with a default-behavior statement ('Public lists only unless include_all is true'), which clarifies the omission semantics beyond the bare 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 (List) and resource (the account's sub lists), and disambiguates the term by glossing it as 'the lists contacts belong to'. It also enumerates the returned fields (id, name, position, timestamps), which separates it cleanly from siblings like robly_list_contacts, robly_list_fields, and robly_create_sub_list.

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

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

Gives concrete downstream guidance ('Use the ids for list filters and for adding contacts'), which routes the agent to follow-on tools like robly_add_contact_to_list. It does not explicitly state when not to use it or name an alternative for membership checks (robly_check_list_membership), so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, so the safety profile is covered. The description adds real context beyond that: the operation is destructive to list membership only, not to the contact, and it is a POST to a specific endpoint. It does not say what happens if the contact is not on the list, but the added scope clarification is meaningfully more than the annotations provide.

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 clauses, front-loaded with the WRITE marker and the key scope caveat. The endpoint path is somewhat visible-implementation noise but is compact and arguably useful for API-aware agents.

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 mutation with full schema coverage and rich annotations, the description plus structured fields give an agent enough to call it correctly. Only edge-case behavior (contact not on the list, list not found) is undocumented, 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 description coverage is 100%, so email/member_id alternation and the sub_list_id source are already documented in the schema. The description adds no parameter-level detail, which is the expected baseline when the schema does the work.

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

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

States a specific verb and resource (take a contact off one list) and adds the crucial scope note that the contact record itself is kept, which separates it from delete/unsubscribe semantics. It does not name a sibling tool, but the distinction is implied clearly enough to pick between this and robly_unsubscribe_contact.

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 contact itself is kept' implies the appropriate scenario for this tool, but there is no explicit when-to-use or when-not guidance versus robly_unsubscribe_contact or removing a contact entirely. Sibling differentiation is left to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true, so the safety profile is fully covered without the description. The description's "WRITE:" prefix merely restates readOnlyHint=false and the HTTP path adds no agent-usable behavioral context (no note that the prior name is replaced, no auth/permission requirements, no duplicate-name behavior).

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

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

Two short, front-loaded sentences with no filler. The endpoint path is low-value to an agent but costs little; nothing is buried.

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 full schema coverage and complete annotations, this is minimum viable. It omits what happens to existing membership/naming on rename and any failure conditions, which would help an agent call it 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 description coverage is 100% and both parameters are documented in-schema ("The new name.", "Sub list id from robly_list_sub_lists."). The description adds no further parameter 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 a specific verb and resource ("rename a sub list") with a WRITE marker, so the action is unambiguous. It does not, however, distinguish itself from siblings like robly_create_sub_list or robly_list_sub_lists, which an agent must infer from the name alone.

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

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

No when-to-use guidance, no prerequisite (e.g. sub list must already exist, id taken from robly_list_sub_lists), and no mention of alternatives. The agent is left to infer selection purely from 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 only declare the generic write/destructive/openWorld profile; the description adds substantive behavior: confirmation email flow with double_opt_in, immediate welcome email, and autoresponder triggering — all side effects an agent must anticipate. It also discloses the underlying endpoint (POST /api/v1/sign_up/generate).

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

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

Front-loads 'WRITE:' and the core action, then layers the email side effects and the parameter hint. Four tight sentences with no filler; every clause carries operational meaning.

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

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

For a 7-param mutation with no output schema, it covers side effects, consent conditions, input provenance, and the endpoint. The only untouched item is return_contact semantics, which the schema already documents adequately.

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; the description still adds value by explaining that `fields` is keyed by user_tag sourced from robly_list_fields, which ties the parameter to another tool. The email-sending flags are restated from the schema rather than extended.

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 verb+resource and mode ('WRITE: add a new subscribed contact'), and adds the re-submit case. It is clearly differentiated from siblings like robly_add_contact_to_list and robly_update_contact by describing sign-up-form semantics rather than list ops or edits.

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

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

Gives a real consent guardrail ('Only subscribe people who agreed to receive email') and points to robly_list_fields / robly_list_sub_lists as prerequisites for building inputs. It stops short of explicitly saying when to prefer robly_update_contact or robly_add_contact_to_list instead, so routing is inferable rather than stated.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds genuinely new context: the action is irreversible through the API and the contact can only return via a sign-up form. That is precisely the consequence an agent needs before calling a destructive tool.

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

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

Three tight sentences: mutation type and effect first, irreversibility second, use case third. No redundant restatement of the title, and the endpoint is appended where it aids verification.

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

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

Covers the essentials for a destructive, idempotent 2-param write tool with no output schema: what it does, that it cannot be undone, and when to use it. Minor gap is what happens on an already-unsubscribed or nonexistent contact, though idempotentHint partially signals this.

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

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

Schema description coverage is 100%, with the email/member_id XOR rule already documented per-parameter. The description adds no additional semantics (no format, precedence, or behavior when a contact is unknown), 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 ('unsubscribe a contact so Robly stops emailing it') plus the underlying endpoint POST /api/v1/contacts/unsubscribe. The 'WRITE:' prefix and the unsubscribe action cleanly separate it from siblings like robly_subscribe_contact and robly_remove_contact_from_list.

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 it for a contact that asked to stop" gives a clear triggering condition for when to invoke this over alternatives. It does not explicitly name the sibling tools (e.g. robly_subscribe_contact) it is contrasted with, so it stops short of full when/when-not routing.

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

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

Adds real side-effect context beyond the annotations: include_autoresponder is flagged as sending EMAIL to the contact, and remove_from_all_other_lists is described as removing the contact from every list not in add_to_list_ids (with its add_to_list_ids dependency). What's left unsaid is whether omitted `fields` are preserved or cleared by the update_full_contact endpoint — a material ambiguity for a destructiveHint=true 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?

Front-loads the WRITE marker and primary action, then covers each parameter in a single clause with zero filler. Dense but well-ordered, and the endpoint reference sits harmlessly at the end.

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

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

For a 6-parameter destructive mutation with no output schema, the definition covers identifying the contact, formatting fields, list add/remove semantics, and the email-triggering side effect. The remaining gap is update semantics (partial vs full replacement) and any indication of the response, which matters given the update_full_contact endpoint name.

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 already 100%, so the baseline is 3; the description earns above that by stating that `fields` keys are user_tags, that the email address cannot be changed via this tool, and by disclosing the cross-parameter constraint that remove_from_all_other_lists requires add_to_list_ids — a rule not encoded in the schema. It does not clarify merge-vs-replace semantics for `fields`.

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

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

Opens with a specific verb and resource: "WRITE: change an existing contact's data fields and/or list memberships in one call." It scopes exactly what can be changed (data fields and list memberships) and implicitly contrasts with the narrow siblings robly_add_contact_to_list and robly_remove_contact_from_list by combining both operations.

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 to prerequisites: look up member_id with robly_find_contact, get field keys from robly_list_fields, and notes the email cannot be changed here. It never explicitly says when to prefer this over robly_add_contact_to_list / robly_remove_contact_from_list for single-list operations, which keeps it short of a 5.

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