Memberful MCP by usefulapi

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

The destructiveHint=true annotation already carries the risk profile, and the description reinforces it with 'MUTATES Memberful data'. Beyond that it adds the underlying GraphQL mutation name (subscriptionChangeExpirationTime), which helps debugging, but it does not say whether the change is reversible, what happens to access immediately upon shortening, or what the response contains.

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 mutation warning, and every clause carries information: mutation class, effect, unit/type, and the API mapping. Nothing to cut.

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

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

For a two-parameter mutation with full schema coverage and no output schema, the description covers what an agent needs to invoke it correctly. It omits any note on return value or error behavior, which is a minor gap given the destructive nature of the call.

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

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

Schema coverage is 100%, so both id and expiresAt are already documented, including the 'Unix timestamp in SECONDS' note that the description repeats verbatim. The only added value is the GraphQL call signature mapping, which is marginal — baseline 3 is correct.

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 (change) and resource (subscription expiration) and immediately clarifies the semantics: it moves WHEN a subscription expires, extend or shorten. The 'MUTATES Memberful data' prefix cleanly separates it from the read-oriented siblings like memberful_get_subscription and memberful_list_subscriptions.

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?

'Extend or shorten access' gives clear context for the two directions of use and the mutation framing signals this is not a read path. However, it never names an alternative (e.g. memberful_graphql for unsupported expiry mutations) or states any precondition such as requiring an existing subscription 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 destructiveHint=true, and the leading 'MUTATES Memberful data' reinforces rather than adds. The genuinely new context is batching — one or more codes in a single call — but nothing about duplicate-code behavior, partial-success semantics, or reversibility is disclosed.

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

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

Three tight sentences with the mutation warning front-loaded, so the reader gets the risk signal first. The trailing GraphQL signature line is slightly redundant but helps an agent map to the underlying API.

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

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

For a destructive, batched mutation with no output schema, the description is silent on what comes back — created coupon objects, ids, or per-code error results — which matters when submitting multiple codes that may partially fail.

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

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

Schema coverage is 100%, so the schema already documents both parameters; the description only restates discountId and 'coupon code strings' and maps them onto the GraphQL argument names. That mapping is mildly useful but adds no format, constraint, or validation detail beyond the schema.

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

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

States a specific verb and resource — 'create one or more coupon codes for a discount' — and names the exact GraphQL mutation createCoupons(discountId, coupons). No sibling tool deals with coupons, so the agent can distinguish it immediately.

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 implies the call shape (must supply discountId and code strings) but never states when to use this versus the generic memberful_graphql/memberful_query siblings, nor any precondition such as the discount already existing. Usage is inferable but not guided.

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

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

The destructiveHint annotation already signals mutation risk, and the description adds that this maps to the GraphQL memberCreate mutation. However, it does not disclose important behavior such as duplicate-email handling, authentication requirements, side effects like welcome emails, or what happens on failure.

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

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

Two sentences are enough to identify the mutation, its required input, and the underlying GraphQL operation. The mutation warning is front-loaded and there is 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?

For a simple two-parameter create tool with full schema coverage and a destructive annotation, the description is mostly complete. The main remaining gap is that it does not say what the create operation returns, which matters somewhat because there is no output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description only restates that email is required and fullName is optional, adding no semantics beyond the schema such as email uniqueness or format constraints.

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

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

The description states a specific verb and resource: create a new member, with required email and optional full name. It clearly distinguishes this from sibling operations like memberful_update_member, memberful_get_member, and memberful_list_members.

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

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

The description implies usage by saying this creates a new member, but it does not explicitly state when to use this versus memberful_update_member for existing members or memberful_graphql for custom mutations. No exclusions or prerequisites are provided.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully discloses the payload shape (profile, Stripe customer id, spend, metadata, subscriptions with plan), but says nothing about behavior for an unknown id, error cases, or whether subscriptions are paginated.

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

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

A single front-loaded sentence that names the verb, the keying parameter, and the returned fields with no filler. The trailing GraphQL mapping is a compact, useful hint rather than padding.

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

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

With no output schema, the description takes on the job of describing return contents and does so explicitly, which is the main thing an agent needs for a single-record getter. Only the not-found/error behavior is left 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 required parameter with 100% schema description coverage, so the schema fully documents it; the description adds only the 'by id' framing. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 (Fetch) and a specific resource (one Memberful member by id), and enumerates what the record contains. This clearly separates it from sibling memberful_list_members, which returns many members.

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

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

The phrase 'by id' implies the precondition (you already have a member id) and 'one' implies it is not the listing tool, but no sibling is named and there is no explicit when-not guidance. Usage is inferable rather than stated.

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It does add the return-field enumeration (status, timestamps, plan, member, orders, coupon), but says nothing about behavior when the id is unknown or about auth errors.

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 with the core action front-loaded and no filler. The GraphQL mapping is compact and useful rather than padding.

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

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

With no output schema, the field enumeration is the key addition and it is present. Only the error/not-found behavior is unaddressed, which is a minor gap for a simple read.

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

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

Only one parameter and the schema documents it at 100% coverage. The description restates 'by id' and the GraphQL form subscription(id) but adds no syntax, format, or sourcing guidance beyond the schema.

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

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

States a specific verb (Fetch) and resource (one subscription by id), then enumerates the returned fields and names the underlying GraphQL query. The 'one subscription' phrasing implicitly distinguishes it from memberful_list_subscriptions, though it never names that sibling.

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 it should call this when it holds a subscription id and needs details. There is no explicit when-to-use, when-not-to-use, or pointer to memberful_list_subscriptions for multi-record needs.

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 provide only destructiveHint=true; the description earns credit by explaining why — it can execute ANY mutation, so effects are unbounded and potentially irreversible. It also names the endpoint hit and the optional-variables surface. It stops short of describing auth requirements, rate limits, or error/partial-failure behavior, which matters for an arbitrary-operation tool.

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

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

Front-loads the critical warning ('MUTATES Memberful data') and ends with the routing directive. The middle sentence is long and slightly clause-stacked, but every element — risk, scope, endpoint, variables, alternative — earns its place.

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

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

For an arbitrary GraphQL passthrough with no output schema (returns are unknowable in advance), the description covers what an agent needs: what it does, the endpoint, the mutation risk, and the safer sibling. Return-shape documentation is impossible here, so the omission is acceptable, though a note on permission requirements would complete it.

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

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

Schema description coverage is 100% with both parameters documented (query and variables), so the schema carries this dimension. The description only echoes 'with optional variables' without adding format guidance or examples, which is the expected baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource: run an arbitrary Memberful GraphQL query or mutation against the account's /api/graphql endpoint with optional variables. It explicitly distinguishes itself from the sibling memberful_query, so an agent can route between the two without opening either schema.

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

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

Gives an explicit alternative and the condition that selects it: 'Prefer memberful_query for read-only calls.' The 'escape hatch' framing implies this is the fallback when no dedicated tool covers the operation, though it never explicitly says which sibling mutations to prefer, leaving some inference to the agent.

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 readOnlyHint=true, so the description carries the rest of the burden and does so well: it discloses the Relay connection shape, the edge/node payload fields, the default page size of 50, and how cursors chain between calls. It omits ordering/sort behavior and any result-size or rate limits, 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?

Front-loaded with purpose and payload, then pagination mechanics, then the alternative — a sensible order with dense, non-repetitive sentences. The trailing 'Memberful GraphQL: members connection.' adds little beyond what the first clause already said, a minor bit of filler.

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

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

With no output schema and minimal annotations, the description compensates by describing the node fields returned and the pagination protocol, which is what an agent needs to call and consume this tool. Missing ordering guarantees and any note on the reverse ('last'/'before') path are the remaining gaps.

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 earns above that by explaining the cursor-chaining relationship between 'after' and an edge's 'cursor' and by stating that 'first' defaults to 50 — a default not present in the schema. It says nothing about 'last'/'before' semantics or the 1–1000 bounds, leaving reverse pagination to the schema.

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

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

The description states a specific verb and resource ('List members') and immediately characterizes the return payload (cursor + node with profile, Stripe customer id, unrestricted-access flag, total spend, subscriptions). It also names the sibling it is not ('For member-state filters beyond active, use memberful_query'), so an agent can route correctly 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 gives explicit pagination guidance ('first' + 'after', pass the last edge's cursor) and an explicit alternative with its triggering condition (memberful_query for non-active member-state filters). It does not cover the single-member case (memberful_get_member) or when to prefer listing subscriptions instead, so it falls short of fully exhaustive routing 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=true, so safety is covered. The description adds value by disclosing the return fields (id, name) and the backing GraphQL field ('passes'), which helps an agent connect the tool to the underlying API and anticipate output. It does not state whether the list is paginated or complete, but for a zero-parameter read this is strong disclosure.

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 plus a compact parenthetical and API-mapping fragment; every element carries information (resource, dashboard alias, meaning, field list, GraphQL source) with no filler.

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

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

With no output schema, the description appropriately compensates by naming the returned fields, and it explains the passes/Plans naming. The remaining gap is contextual: it does not distinguish this tool from the sibling `memberful_list_plans`, leaving a real ambiguity an agent must resolve.

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

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

The tool takes no parameters, so the baseline is 4. The description instead documents the output fields (id, name), which is the only semantic content available for a parameterless tool.

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

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

Names a specific verb and resource ('List all passes') and, critically, disambiguates the terminology: passes are the dashboard's 'Plans' — the access groups a member subscribes to. That mapping is genuinely clarifying. The unresolved issue is that a sibling `memberful_list_plans` exists and the description never says how it differs from this passes listing.

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

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

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives. Given that `memberful_list_plans` is a sibling and this description explicitly equates passes with 'Plans', an agent has no stated rule for choosing between the two near-identical-looking tools.

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 readOnlyHint annotation already establishes this as a safe read, so the description's job is smaller; it still adds real behavior context by enumerating exactly which fields come back (name, interval, price in cents, for-sale flag, plan group). It does not mention ordering, pagination, or whether archived/legacy plans 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?

A single front-loaded sentence with no filler; the parenthetical field list is dense but every element is informative given the absence of an output schema. Slightly crowded but 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 and no parameters, the description carries the return-value burden and does so by naming the returned fields and the unit of price (cents). It stops short of covering pagination, ordering, or the GraphQL fallback route, which would seal the definition.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a no-param tool is 4, and the description stays out of the way rather than inventing input semantics.

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

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

States a specific verb and resource ('List all plans') and even maps the term to the Memberful dashboard label 'Prices', so an agent can distinguish it from list_passes and list_members. It does not explicitly contrast itself with sibling list tools, 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?

Usage is only implied: with no parameters, it is evidently the 'get everything' option, but the description never says when to prefer it over memberful_query or memberful_graphql for plan data. No exclusions or alternatives are named.

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 mark this as read-only, and the description adds useful behavioral context: it explains the Relay edge/node structure, lists node fields, states the default page size of 50, and warns that the connection is sourced from the community SDK and should be validated against a live account.

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 front-loaded and appropriately sized, with pagination and the SDK caveat stated early. The final “Memberful GraphQL: subscriptions connection” phrase is slightly redundant with earlier context but not harmful.

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

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

With no output schema, the description does the necessary work of describing the return shape as Relay edges with cursor and node fields. Combined with the read-only annotation and pagination guidance, it is complete enough for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description still adds meaning by explaining the `first` + `after` pagination flow and the non-schema detail that `first` defaults to 50.

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 a specific verb/resource: listing subscriptions via a Relay connection. It also names the edge/node shape and pagination model. It does not explicitly differentiate itself from sibling tools such as memberful_get_subscription or memberful_graphql.

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

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

It gives clear pagination guidance using `first` and `after`, including passing the last edge cursor and the default page size. However, it does not say when to use this tool versus alternatives like get_subscription, graphql, or query.

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, so the safety profile is partly covered, but the description adds genuinely useful context beyond them: the endpoint path, the hard rejection of mutations at runtime, and that variables are optional. It stops short of other operational traits such as auth requirements, pagination, or rate limits, so it is strong but not exhaustive.

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 sentences, front-loaded with the 'Escape hatch' framing so the tool's role is immediately clear, and every sentence carries routing or constraint information. The uppercase emphasis on QUERY/REJECTED is slightly shouty but reinforces the single most important rule of the 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?

For an arbitrary-query passthrough with no output schema and only two well-documented parameters, the description covers role, endpoint, constraint, and alternatives. Return shape is implicitly whatever the query selects, which is reasonable, though a note that the caller owns the response shape would make it fully complete.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema ('must be a query, not a mutation' and the variables object). The description echoes this ('with optional variables') without adding syntax, formatting, or example-level detail, 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 ('run an arbitrary Memberful GraphQL QUERY') plus the scope constraint (read-only, against your account's /api/graphql endpoint). It explicitly contrasts itself with the curated read tools and with memberful_graphql, so an agent can pick it apart from siblings 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?

Gives both the when ('fields not covered by the curated read tools, e.g. member-state filters beyond active') and the when-not ('Mutations are REJECTED — use the dedicated write tools or memberful_graphql for those'), naming alternatives explicitly. This is exactly the routing information an agent needs.

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 destructiveHint=true, and the description is consistent by opening with 'MUTATES' and specifying the metadata-only scope. It adds useful constraints on metadata size, though it does not discuss permissions, reversibility, 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?

The description is short and front-loaded: it leads with the mutation warning, then constraints, then the alternative tool, then the underlying GraphQL call. There is little 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?

For a simple two-parameter mutation with rich schema coverage and a destructive annotation, the description gives enough context to invoke it correctly and avoid using it for unsupported fields. It does not explain return values, but the tool is otherwise adequately covered.

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

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

Schema coverage is 100%, so the schema already documents both id and metadata. The description repeats the metadata constraints and names the underlying GraphQL mutation, but adds little parameter 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 verb and resource: it MUTATES Memberful data by updating a member's metadata. It also distinguishes this tool from memberful_graphql by clarifying that only metadata updates are supported here, while other inline member fields belong in the GraphQL tool.

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

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

It explicitly says to use this tool only for member metadata updates and directs the agent to memberful_graphql for other inline member fields. That gives a clear when-to-use and alternative-routing rule.

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