memberful

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

DestructiveHint=true is present, and the description reinforces mutation with 'MUTATES' and adds the key behavioral consequence that access can be shortened, not just extended. It also grounds the behavior in the specific Memberful GraphQL mutation, going beyond the annotation.

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 tight, well-structured description with no filler. The mutation warning and purpose are front-loaded, and the GraphQL signature adds useful precision in very few words.

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 complete schema coverage and a destructive annotation, this is complete: it identifies the target, parameters, units, consequence, and underlying operation. No output schema exists, but the description does not need to explain return values for this simple mutation.

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

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

Schema coverage is 100% and both parameters are already described in the schema, so the description does not need to compensate. It reinforces 'expiresAt in SECONDS' and maps params to the GraphQL mutation, which is mildly useful but largely redundant with 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 action ('change WHEN a subscription expires'), marks it as a mutation, and clarifies it can extend or shorten access. This distinguishes it from read-only sibling tools like get_subscription and 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?

The intended trigger is clear: use this when you need to alter a subscription's expiration date. It does not explicitly name sibling alternatives or exclusions, but no other sibling is a direct alternative for this mutation.

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 description explicitly opens with 'MUTATES Memberful data', which aligns with and reinforces the destructiveHint annotation. It also reveals the underlying GraphQL operation, adding useful behavioral context beyond the annotation.

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 concise sentences with no wasted words. The safety-relevant 'MUTATES' signal is front-loaded, and the required inputs and GraphQL mapping are stated efficiently.

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

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

For a simple mutation tool with fully documented parameters and a destructiveHint annotation, the description gives enough to invoke it correctly. It could mention return values or error behavior, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds a small amount of relational context by naming the GraphQL mapping, but does not significantly increase semantic clarity 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 clearly states a specific action: create one or more coupon codes for a discount, with the required inputs. It is distinct from sibling tools, none of which specifically create coupons.

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 clear context: use this when creating coupon codes, and provides the necessary inputs (discountId and codes). It does not explicitly name alternatives or exclusions, but the 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 signal destructiveHin=true, and the description adds 'MUTATES' plus the underlying GraphQL mutation name. However, it does not disclose side effects, authorization requirements, duplicate handling, or what happens on successful creation, so extra behavioral context is limited.

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 concise sentences with no filler. The mutation warning is front-loaded, and the second sentence gives implementation-specific context that helps an agent understand the backend call without clutter.

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 2-parameter mutation with no output schema, the description provides enough to invoke the tool correctly: it names the operation, the resource, the required email, and the optional fullName. It could briefly mention expected return behavior or duplicate handling, but those are not essential for 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%, so the schema already documents email and fullName. The description adds only the GraphQL argument mapping (memberCreate(email, fullName)), which is useful but does not substantially deepen parameter meaning 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 uses a specific verb, 'create', and identifies the resource, 'a new member', while also noting the mutation nature and the required/optional fields. This clearly distinguishes create_member from sibling tools like update_member, get_member, and 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?

Usage is implied rather than explicit: the agent can infer this tool is for creating new members, but the description does not state when to use it over alternatives such as update_member or memberful_graphql, nor does it mention exclusions.

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 meaningful behavioral detail by listing the returned fields: profile, Stripe customer id, unrestricted-access flag, total spend, metadata, address, and subscriptions. It also notes the underlying GraphQL structure, providing useful context beyond 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?

The description is a single dense sentence that front-loads the core action before enumerating what is returned. Every clause adds useful information, and the GraphQL note is a concise implementation anchor with no wasted words.

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, the description is complete: it states the operation, identifies the input, and enumerates the output fields despite there being no output schema. Combined with the readOnlyHint annotation, an agent has everything needed to select and invoke this 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?

The input schema already fully documents the single id parameter with 'The member id.' The description says 'by id' but adds no additional semantic detail about id format, required permissions, or related identifiers. Since schema coverage is 100%, 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 starts with a specific verb and resource: 'Fetch one Memberful member by id,' which clearly distinguishes this from sibling tools like list_members or get_subscription. It also enumerates exactly what data is returned, making the tool's purpose 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?

The phrase 'Fetch one Memberful member by id' makes the primary use case clear: retrieve a single member record when the id is known. It does not explicitly name alternatives or state when not to use it, but the contrast with list_members and get_subscription is strongly 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?

The readOnlyHint annotation already communicates safety, so the description adds value by specifying precisely what data is returned: status, timestamps, plan, member, orders, and coupon. It also names the underlying GraphQL query (subscription(id)), which gives the agent extra confidence about the operation's nature.

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

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

Two sentences, no filler. The primary purpose is front-loaded and the field list is compact but informative. Every word 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 single-id fetch with one parameter and readOnlyHint set, the description covers the return payload and the underlying operation. It doesn't mention error behavior or what happens if the id doesn't exist, but given the tool's simplicity the definition is sufficiently 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?

The input schema already documents id as 'The subscription id', so the description adds no new semantic detail for the only parameter. With 100% schema coverage, the baseline of 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 verb and resource: 'Fetch one subscription by id', and enumerates the returned fields. This clearly distinguishes it from list_subscriptions, which retrieves many subscriptions, and from memberful_graphql, which is a general-purpose 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?

The description implicitly establishes the primary use case: retrieving a single subscription when its id is known. It doesn't explicitly contrast with sibling tools like list_subscriptions or change_subscription_expiration, but the phrase 'by id' makes the selection criteria apparent.

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 indicate readOnlyHint=true, and the description adds context about the response shape, pagination pattern, and default page size. It doesn't mention ordering or edge cases, but the annotations lower the burden and the added detail is valuable.

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 with no wasted words: output shape, pagination/filter behavior, and the alternative tool. Each sentence earns its place and the most important information is front-loaded.

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 summarizes the return structure and pagination. It also flags the alternative for more advanced filters. Minor details about `last`/`before` behavior are missing, but the schema describes them, making this sufficient for a read-only list.

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 adds meaning by explaining the `first` default and how `after` uses the last edge's cursor, going beyond the schema descriptions.

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 the tool lists members and details the Relay connection edge/node structure, including specific fields. This clearly differentiates it from sibling tools like list_subscriptions and get_member. The resource and verb are 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?

It explicitly explains pagination with `first` + `after` and cursor usage, the `activeOnly` filter, and the `first` default. It also tells the agent when to use memberful_query instead, providing a clear when-not and 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?

readOnlyHint already marks this as safe, and the description adds useful behavior: it lists all passes (no filtering), returns id and name, and identifies the underlying Memberful GraphQL query ('passes'). It does not cover pagination or rate limits, but for a zero-parameter list operation the disclosed behavior is sufficient.

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 deliver the resource definition, return shape, and GraphQL source with no filler. The key action 'List all passes' is front-loaded.

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

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

For a parameterless list tool without an output schema, the description adequately covers the resource semantics and return fields. It is slightly incomplete because it leaves the relationship to the sibling list_plans ambiguous, but nothing essential for making the call is missing.

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

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

The tool has zero parameters, so there is no parameter semantics to document; the schema coverage baseline of 4 applies. The description does not need to add parameter-level detail.

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 verb and resource ('List all passes') and defines what a pass is (Memberful dashboard 'Plans', the access groups a member subscribes to), plus the returned fields id/name. It does not explicitly distinguish itself from the sibling list_plans, so it falls just short of full sibling differentiation.

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

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

The description only states the operation ('List all passes') and gives no guidance on when to choose this tool over siblings like list_plans, list_subscriptions, or memberful_query. No conditions or exclusions 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?

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context beyond that: it specifies that all plans are returned, lists the exact response fields, and identifies the underlying data source as Memberful GraphQL 'plans'. It does not mention pagination or ordering, but for a simple read-only list this is a minor 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?

A single, front-loaded sentence states the action first, then the returned fields and source, with no wasted words. Every clause adds 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 zero-parameter, read-only list tool with no output schema, the description is sufficiently complete: it names the resource, lists the returned data, and identifies the GraphQL source. It could add explicit sibling differentiation or pagination behavior, but these are not critical for invoking this simple 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?

The tool has zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to clarify. The description focuses on what is returned rather than input details, which is appropriate 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?

The description states a specific verb ('List'), a clear resource ('all plans'), and enumerates the return fields (name, interval, price in cents, for-sale flag, plan group), making it easy to distinguish from sibling list tools such as list_members, list_subscriptions, and list_passes. It also anchors the concept to Memberful's dashboard terminology ('Prices').

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 intended use—retrieving all pricing plans—is clearly implied, but the description does not explicitly state when to choose this tool over alternatives or provide exclusions. Sibling names make the choice fairly obvious, yet no direct 'use this instead of X' guidance is 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 mark this as readOnlyHint=true, and the description adds meaningful behavioral context: it is a Relay connection, it returns cursor-bearing edges, and it warns that the top-level subscriptions connection is sourced from the community SDK and should be validated against a live account. This caveat goes beyond the annotation and helps set expectations about reliability.

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 compact and front-loads the core purpose before pagination details and the caveat. The final 'Memberful GraphQL: subscriptions connection' phrase is slightly redundant with the earlier 'subscriptions connection' mention, but the overall structure is efficient and easy to parse.

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

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

Even without an output schema, the description covers the important return shape (edge/node fields), pagination mechanics, defaults, and a reliability caveat. It could also mention interaction between first/last or before/after, but for a read-only listing tool with annotations and full parameter schema coverage, this is a strong and sufficiently complete description.

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 value beyond parameter docs by explaining the default for first (50) and the concrete way to use after ('pass the last edge's cursor'). This makes successful pagination much more likely without requiring the agent to infer cursor 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?

The description uses a specific verb ('List') and resource ('subscriptions'), and clarifies it is the Relay connection returning edges with cursors and nodes. It clearly differentiates from sibling tools by specifying the top-level subscriptions connection, making it distinct from list_members, list_plans, and get_subscription.

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 clear pagination guidance ('Paginate with first + after') and notes the first default of 50, which is useful context. However, it does not explicitly state when to use this tool versus alternatives such as get_subscription or memberful_query, so the agent must infer selection from the tool name and resource type.

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 description goes beyond the destructiveHint annotation by explicitly warning that the operation may mutate Memberful data and by disclosing that it can run 'any' mutation with no guardrails. It also names the endpoint. This is useful context, though it does not detail authentication, rate limits, or error behavior.

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

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

The description is a single, dense sentence with no filler. It front-loads the mutating risk, states the tool's escape-hatch role, and closes with a clear alternative routing 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 an arbitrary GraphQL escape hatch with a simple two-parameter schema, the description gives enough context to call the tool correctly: what it runs, where it runs, and when to use the sibling instead. Since there is no output schema, the description could note that the response shape depends entirely on the GraphQL operation, but the arbitrary-operation framing implies 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%, so the schema already documents both query and variables parameters. The description adds only the context that variables are optional and that the operation is against a specific endpoint, which does not significantly improve parameter-level understanding 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 clearly identifies a specific action: running an arbitrary Memberful GraphQL operation, including mutations, against the account's /api/graphql endpoint. It also distinguishes itself from memberful_query by noting the read-only sibling is preferred for non-mutating calls.

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 explicitly says to prefer memberful_query for read-only calls, which gives the agent a clear routing rule. The 'escape hatch' framing also communicates that this tool is for cases where a specialized tool does not exist or where arbitrary GraphQL is required.

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 include readOnlyHint=true, and the description reinforces this by saying mutations are rejected and naming the correct alternative for write operations. It adds useful behavioral context beyond the annotation: arbitrary queries are allowed, mutations fail, and the endpoint is explicitly identified.

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

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

Three dense sentences: the first identifies purpose and endpoint, the second states the exclusion and alternatives, and the third gives a concrete use case. There is no filler or redundancy beyond the intentional emphasis on read-only behavior.

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

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

With only two parameters, no output schema, and a read-only annotation, the description covers everything an agent needs to decide and invoke correctly: endpoint, allowed operation, rejected operation, alternative tools, and a motivating use case. The arbitrary return shape cannot be described meaningfully in advance.

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 both query and variables already described in the input schema. The description repeats that variables are optional but does not add deeper parameter semantics. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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 ('run'), a precise resource (arbitrary Memberful GraphQL queries against /api/graphql), and a clear scope (read-only). It also distinguishes itself from the curated read tools by framing it as an escape hatch for uncovered fields, which prevents confusion with 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?

It explicitly says to use this tool when fields are not covered by the curated read tools, gives a concrete example (member-state filters beyond active), and clearly tells the agent to use dedicated write tools or memberful_graphql for mutations. This is strong when-to-use and when-not-to-use guidance.

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

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

The description opens with 'MUTATES Memberful data', directly signaling a write operation, which is consistent with the destructiveHint=true annotation. It adds context beyond the annotation by clarifying that only metadata is affected and by providing the underlying GraphQL mapping. It does not go into irreversible side effects, but the annotation already covers destructiveness.

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

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

Two sentences with no filler. The mutation flag is front-loaded, followed by the precise scope, constraints, and routing to an alternative. 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?

For a two-parameter tool with full schema descriptions and an annotation indicating destructiveness, this description covers the action, scope, constraints, and alternative path. No output schema exists, and the description does not need to explain return values for this simple metadata update. It is complete.

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

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

Schema coverage is 100%, with both id and metadata documented in the schema. The description repeats the metadata constraints (max 50 keys, 40-char keys, 500-char values) but does not add new parameter meaning beyond the schema. It reinforces the scope, but that is more about usage than 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?

The description states a specific verb and resource: 'update a member's metadata'. It also clearly scopes the action to metadata only, distinguishing it from the broader member update capabilities in sibling memberful_graphql. This precision makes it immediately identifiable.

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 when to use this tool versus an alternative: 'Only metadata is supported here; for other inline member fields use memberful_graphql.' It even provides the exact GraphQL mutation name (memberUpdate) for reference, leaving no ambiguity.

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