Cluby MCP

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

With only destructiveHint=false in annotations, the description carries real weight and delivers: admin-role requirement, one independent copy per venue, immediate member visibility unless `status` is `hidden`, `visibleToStatusCards` scoping, and that `materialsOrder` is 'reported, never stored'. These are substantive traits 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?

Dense but front-loaded: creation scope and permission come first, then image, localization, activation, and materials-order guidance in a logical order. It is long, but most sentences carry non-obvious rules 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?

For an 11-parameter nested create tool with no output schema, the description covers the high-risk semantics (permission, immediacy, per-venue duplication, response shape, localization, activation, materialsOrder). It omits details of `schedules` and `content.offer`, but those are documented in the schema, so the gap is minor.

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?

At 64% schema coverage the description adds genuine meaning: the localized-string shape `{ default: "…", fi: … }`, the required `activation` trio with `validFrom`/`validUntil`/`frequency` semantics, sourcing `venueIds` from `list_venues` and `visibleToStatusCards` from `list_status_cards`, and the `declined`/contact requirement for `materialsOrder`. It leaves `schedules`, `offer`, and `sortOrder` largely 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?

States a specific verb and resource ('Create a benefit (member perk)') and immediately clarifies the fan-out scope: an independent copy in each venue of `venueIds`, with the response listing every copy. This distinguishes it clearly from `update_benefit` and `list_benefits`.

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 pre-conditions and routing: requires the admin role, call `import_image` first for a new photo and pass its `images`, and 'confirm the details with the user before calling this' since the benefit goes live at once. It does not explicitly contrast with `update_benefit`, so it falls short of a full when/when-not map.

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

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

Annotations only assert destructiveHint=false, so the description carries real weight: it discloses the admin-role requirement, the member-facing side effect (members receive the gift around their birthday unless status is hidden), and warns to confirm before calling. This is useful mutation context beyond structured data, though it never states reversibility or rate/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?

Front-loaded with purpose, then prerequisites, then parameter semantics, then the safety warning. Dense but each clause conveys distinct information; slightly long but no obvious filler.

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

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

For a 7-parameter nested mutation tool with no output schema and low schema coverage, the description covers the high-risk and non-obvious fields (venueIds, content localization, image pipeline, options timings, status side effect). The main residual gap is guidance on templateId and orgId omission, which the schema partially covers.

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?

With schema coverage at only 29%, the description compensates well: it explains venueIds sourcing, the localized-string shape for content.name/description, the imageUrl/imageAttribution flow from import_image, and the meaning of options.expirationDays and options.advanceSendDays. It leaves orgId, templateId, and message unaddressed.

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

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

States a specific verb+resource ('Create a birthday gift') and anchors it to a known mental model ('the same as saving the Partner Hub's birthday gift form'). It is trivially distinguishable from update_birthday_gift and list_birthday_gifts.

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 the key preconditions (admin role on the listed venues, venueIds come from list_venues) and a cross-tool workflow (call import_image first and reuse its originalUrl). It also urges confirming details with the user, but does not explicitly contrast with update_birthday_gift/templateId paths.

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 covers the safety profile, and the description adds genuine behavioral context beyond it: the default all-venue scope, the 30-day trend horizon, and the distinction between rewardsEarned (minted) and rewardsRedeemed (claimed). It doesn't mention rate limits or auth requirements, but for a read-only dashboard this is solid added value.

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 what is returned, followed by scope and then metric definitions. Every sentence carries information the agent needs, and nothing is redundant.

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

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

With no output schema, the description must carry the return-value burden, and it does: it lists the metric families and defines the two ambiguous stamp-derived figures. Combined with the fully documented two-parameter schema, an agent has everything needed to 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 (orgId, venue) are fully documented there, so the baseline is 3. The description's 'unless `venue` is given' and the org-key behavior largely restate what the schema already says, adding no new parameter-level 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 enumerates the exact metrics returned (benefit activations, event entrances, push messages, returning members, page visitors) and the 30-day trend window, so the agent knows precisely what it gets. This clearly separates it from sibling aggregates like member_stats and org_activity.

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 scoping rule ('covers every venue unless `venue` is given'), which implies default usage, but never says when to prefer this tool over member_stats or org_activity, nor any exclusions. Usage is inferable rather than explicit.

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 cover openWorldHint and destructiveHint, so the description carries the important semantics: it returns originalUrl and images, processing is asynchronous (write tools "wait for the processed versions"), and only imported images are accepted downstream. It does not mention auth requirements beyond the orgId note in the schema, or any failure modes for a non-public/dead URL, which keeps it short of a 5.

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

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

Three sentences, front-loaded with the action and storage destination, then the return/pass-through contract, then the acceptance constraint. Every clause carries routing or contract information; 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 supplies the return shape (originalUrl, images) and the exact downstream consumption contract, plus the constraint that other image sources are rejected. For a 3-parameter tool feeding two sibling write tools, nothing an agent needs 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 url, orgId (including the omit-when-single-org rule) and the nested attribution object. The description adds no input-level meaning beyond that; its named fields (images, originalUrl) are return values, not parameters. 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 ("Import a photo ... into the organization's image storage") with an analogy to the Partner Hub UI action, and distinguishes itself from siblings by naming the tools it feeds (create_benefit, update_benefit, birthday gifts). An agent can tell this is the image-sourcing prerequisite step, not a content-writing 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?

Explicitly states when to use it (before benefit writes, since those tools wait for processed versions) and encodes a hard constraint on alternatives: "Only images imported this way (or image sets already on a Cluby benefit) are accepted by the benefit write tools." It also routes the birthday-gift case differently (originalUrl as content.imageUrl), which is genuine conditional guidance.

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

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

readOnlyHint=true already establishes this as a safe read, so the description's burden is lighter, and it does add that stats are "activation counts" computed over the statsFrom–statsTo range. It says nothing about pagination, result size, or what happens when includeStats is set without the full parameter trio beyond what the schema implies.

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, resource statement front-loaded, no filler. The second sentence largely mirrors schema content, but it is brief enough that the overlap is not costly.

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

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

There is no output schema, but the tool takes zero required parameters and the schema fully describes orgId scoping and the stats range, so an agent has enough to invoke it. It lacks pagination or result-shape notes, which is a minor gap for a list endpoint.

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 all four parameters are documented there, including the dependency chain (statsFrom requires statsTo and includeStats). The description adds no syntax, default, or format detail beyond the schema, so the baseline of 3 applies.

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

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

The description names the resource and disambiguates the term with a parenthetical ("Benefits (member perks) of an organization"), which prevents confusion with insurance-style benefits. It is a noun fragment rather than a verb+resource statement, and it never explicitly differentiates itself from list_orgs, list_stamp_cards, or member_stats, so it stops short of a 5.

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

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

There is no statement of when to reach for list_benefits versus sibling tools such as member_stats or list_status_cards. The only conditional given ("With includeStats, add activation counts...") restates the parameter contract rather than guiding tool selection.

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 covered. The description then adds genuine behavioral detail: what includeStats produces (rewardsGiven / rewardsRedeemed, each with total and last-30-days values). It omits pagination/result-size behavior, which is the main remaining gap.

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

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

Three sentences, front-loaded with the resource definition before the stats mechanic. Dense but nothing is padding; each clause adds information an agent would otherwise have to guess.

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

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

With no output schema, the description usefully enumerates the returned gift attributes and stats shape, so an agent knows what comes back. Completeness is strong for a low-complexity two-parameter read tool; only pagination/limits are undocumented.

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 goes beyond it by expanding includeStats into the concrete fields it adds and their time windows. That is meaningfully more than the schema's terse "Include usage statistics for each item", though orgId handling is left entirely 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 names a specific resource (birthday gifts of an organization) and enumerates its facets: applicable venues, message, validity, and delivery timing. It is clearly distinguishable from create_birthday_gift / update_birthday_gift by implication, though it never explicitly frames itself as the read/list counterpart to those write 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?

"Use it to answer how many birthday gifts have been sent or redeemed" gives a concrete use case that ties the tool to a question type, which is real guidance. It stops short of naming alternatives (e.g. member_stats, dashboard_summary) or stating when this tool is the wrong choice.

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 establishes this as a safe read. The description adds that includeStats pulls in sales figures and that publicUrl is environment-scoped, which is genuine context beyond the annotation, but it says nothing about result limits, pagination, or visibility rules for hidden events.

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

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

Three compact sentences, filter semantics front-loaded and readable. The trailing publicUrl sentence is oddly placed because that field has no counterpart in the input schema, adding mild noise.

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 a read-only listing tool, no output schema, and four optional params, the description covers the core filtering model adequately. It leaves the return shape (what an event record contains beyond ticket types) and paging behavior unspecified, which is a minor gap rather than a blocking one.

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 50%: orgId and includeStats are documented in the schema, while timeFilter and statusFilter have no schema description. The description partially compensates by naming time values (yet omits the 'all' enum member) and noting status filtering, but then mentions 'publicUrl', which is not even a parameter – so the added meaning is mixed.

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

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

States the resource clearly ('Events of an organization with ticket types') and enumerates the filter dimensions, so an agent can see it is an events listing distinct from list_benefits/list_venues. It omits an explicit verb and never contrasts itself with sibling list tools, but the resource plus ticket-type annotation is enough to place it.

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: the description says events can be filtered by time and status, which hints at how to narrow results, but never states when to pick this tool over list_orgs, org_activity, or dashboard_summary. No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds meaningful behavioral context beyond the annotations: results are scoped to the API key's access, and the tool is a required first step for other operations. It does not cover pagination or default return order, but the added access and workflow details are 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?

Two tightly constructed sentences with no filler. The resource scope is front-loaded, and the prerequisite instruction follows immediately, making the key routing information highly scannable.

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 discovery tool, the description provides enough context to use it correctly: what it returns, that it is scoped to the API key, and that it must be called first. Pagination behavior for page and perPage is left to the schema, and since no output schema exists, the description does not need to explain return values further.

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 only 33%, with page and perPage undocumented anywhere. The description adds no input parameter semantics at all; it mentions orgId only as an output identifier used by other tools, not as an argument to this tool. It therefore fails to compensate for the low schema coverage.

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 the exact resource (organizations and their venues) and the access scope (this API key), while the tool name and title supply the list verb. It also distinguishes this tool from all siblings by declaring that it must be called first, making its purpose unmistakable.

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 states when to use this tool: 'Call this first.' It further explains why by noting that every other tool takes an organization's id as orgId, effectively defining this as the prerequisite discovery call. No alternative tool exists for this prerequisite, so the guidance is complete.

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 declares the safety profile, but the description goes beyond the annotation by disclosing what the response contains and disambiguating the easily-confused rewardsEarned (minted) versus rewardsRedeemed (claimed) metrics. That is genuine value-added context, though it says nothing about pagination, ordering, or result size.

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 sentence that front-loads the resource and then defines the returned metrics, with zero filler. Slightly awkward parenthetical phrasing but nothing is wasted.

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

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

With no output schema, the description sensibly carries the burden of naming the key returned fields and their meanings. It stops short of describing list behavior (pagination, ordering, filtering) and offers no usage context, which leaves gaps for a list-style read tool.

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

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

With a single parameter and 100% schema description coverage, the schema already explains that orgId is the id from list_orgs and that it can be omitted for single-org keys. The description only echoes the 'of an organization' scope, so no syntax or meaning is added 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 names the resource precisely ('Stamp (loyalty punch) cards of an organization') and defines the per-card metrics returned, so an agent knows this retrieves loyalty card data rather than generic cards. However, it never states that it returns a list, and it does not differentiate itself from the closely-named sibling list_status_cards, so sibling disambiguation is left to inference.

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 guidance, no prerequisites, and no mention of alternatives such as member_stats or list_status_cards. The only usage hint ('of an organization') is implicit, and the actual rule for supplying or omitting orgId lives solely in the schema, not the description.

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 covered structurally. The description adds no behavioral detail beyond that — nothing about whether the full list is returned, ordering, pagination, or how includeStats changes the payload — so it does not meet the bar of adding context beyond 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?

A single tight sentence with the resource front-loaded and no filler. It is efficient, though as a fragment it omits the operation verb rather than being maximally front-loaded for an action 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 a two-parameter, read-only list tool with no output schema and full schema coverage, the definition of what a status card is (tiers with pricing and linked benefits) is sufficient to call the tool correctly. Missing listing/pagination behavior is the only real 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 both parameters (orgId with its list_orgs reference and single-org omission rule, and includeStats) are fully documented in the schema itself. The description mentions no parameters, which is acceptable at this coverage level but adds nothing.

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

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

The description names a specific resource — membership/status cards of an organization — and clarifies what the records contain (tiers, pricing, linked benefits), which distinguishes it from the similarly named sibling list_stamp_cards. However, it is a noun phrase that never states the verb 'list', so the agent infers the listing action from the tool name rather than the description.

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 indication of when to use this tool versus siblings such as list_stamp_cards (stamps vs. membership tiers) or list_benefits, and no prerequisites or exclusions are stated. The agent gets resource semantics but no 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?

readOnlyHint=true already establishes this is a safe read, so the bar is lower, but the description adds almost no behavioral context beyond 'with their public ids'. It says nothing about pagination, result limits, or what happens when the org has no venues.

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 short sentence with the resource and return payload front-loaded; nothing is wasted, though it is arguably under-specified rather than optimally concise.

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, optional-argument read tool with a fully documented schema and no output schema, the definition is minimally adequate. It lacks any mention of result shape or volume, which a listing tool would benefit from.

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

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

Schema description coverage is 100% and the single orgId parameter is documented with the cross-reference to list_orgs and the omit-when-single-org rule. The description adds no parameter detail, 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 resource (venues/locations) and scope (of an organization) plus what is returned (public ids). It is distinguishable from siblings like list_orgs and list_events, though it never uses an explicit verb and offers no contrast with alternatives.

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 prerequisites, and no mention of alternatives among the eight sibling list_* tools. The agent must infer usage purely from the name and resource noun.

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 declare readOnlyHint=true, so safety is covered. The description adds non-obvious behavior beyond that: the 90-day trim, that the count excludes leavers, and the counterintuitive fact that historical points can exceed the current count. It doesn't cover return shape, but that is a read-only stats 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: definition, default scope, and the anomaly caveat. Front-loaded with the core metric and 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 must convey what comes back, and it does: two breakdowns plus a 90-day timeline, and it flags the dip anomaly. The only gap is that no formal return shape is given, which is minor for a descriptive stats endpoint.

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 meaning by stating the effect of omitted `venue` (org-wide) and the semantic distinction between 'currently joined' and 'have not left', which goes beyond the schema's id-reference 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?

States precisely what is counted ('members currently joined... who joined and have not left'), how it is split (by venue, by membership card), and what else is returned (cumulative 90-day timeline). No sibling tool offers member counts, so it is clearly distinguishable.

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

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

Explains default scope ('covers every venue unless venue is given') and the quirky semantics exploration ('timeline can dip when members leave, so a past point can exceed the current count'). It does not route to an alternative tool, but for a standalone stats tool no obvious alternative exists.

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 declares a safe read, so the description's job is to add behavior. It adds newest-first ordering and pagination, which is genuinely useful and not in the annotations. It doesn't state filtering defaults, rate limits, or what an empty result means, so the disclosure is partial.

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, front-loaded with the data domain and followed by ordering/pagination constraints. Zero filler.

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

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

For a read-only, 5-param, no-output-schema list tool, the essentials (what's returned, ordering, pagination) are covered. But with no output schema, the response shape is left implicit, and page/limit semantics go unexplained, leaving gaps an agent must guess at.

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 60%: page and limit have no schema descriptions, and venues/excludeTypes are reasonably documented in the schema already. The description adds no mapping of activity types to excludeTypes values or format of venues, so it fails to compensate for the uncovered page/limit 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?

Clearly states what the tool returns: a list of member activity types (activations, joins, purchases, stamps, check-ins) scoped to an organization. It distinguishes from siblings by being the only activity/feed tool among list_* and stats tools. It does not explicitly name an alternative, but its domain is unambiguous.

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

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

No when-to-use guidance, no exclusions, and no mention of alternatives such as member_stats or dashboard_summary. The ordering and pagination hints are behavioral, not usage-routing guidance. An agent gets no help deciding this tool over a stats tool.

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 declare idempotentHint/destructiveHint but say nothing about mechanics; the description supplies the merge semantics ('content and activation are merged field by field'), the admin-role requirement, the destructive caveat that campaign or product-catalogue fields can be overwritten later, and explicit clearing semantics ('visibleToStatusCards: []', 'activation.schedules: null'). This is rich context beyond structured data.

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

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

Seven sentences, each carrying distinct operational value — identity, merge rule, permission, cross-tool, visibility toggle, clearing syntax, ownership warning — and front-loaded with purpose before caveats. No filler.

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

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

For a 10-param, deeply nested mutation tool with no output schema, the description covers the hard parts: partial update semantics, permissions, cross-tool image flow, clearing values, and ownership conflicts. Gaps remain around venueIds/sortOrder semantics, but the critical behavioral risks are disclosed.

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?

With only 40% schema coverage across 10 params, the description compensates by explaining benefitId provenance, merge behavior for content/activation, status enum meaning, and empty-array-vs-undefined for visibleToStatusCards. It still leaves venueIds, sortOrder, and the precise role of orgId/campaignId thin, so it is strong but not complete.

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

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

States a specific verb+resource ('Edit a benefit') and immediately identifies the identity source ('benefitId is the id from list_benefits'), which cleanly separates it from list_benefits and create_benefit. An agent can pick it without opening the 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 concrete when-to-use guidance: send only keys being edited, use import_image (a named sibling) for photo changes, and set status to hidden/active to control visibility. It does not explicitly contrast with create_benefit or list_benefits, but the partial-update framing makes the intended context 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 only flag idempotentHint and destructiveHint; the description adds substantial context beyond that: patch/merge semantics for `content` and `options`, the admin-role requirement on affected venues, the effect of `status` (hidden stops, active resumes), and a confirmation warning because changes hit members' upcoming gifts. This is exactly the extra behavioral detail the annotations don't carry.

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

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

Four dense sentences, front-loaded with the core edit action, then merge rules, then permissions, then status/confirmation behavior. Every sentence carries information, though the status and confirmation points could be tightened.

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 complex mutation with nested objects and no output schema, the description covers mutation impact, auth, and update semantics, which is what an agent most needs. Return behavior is omitted but no output schema exists to require it, and a couple of unmentioned scalar fields are minor 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?

With only 29% schema description coverage, the description compensates well for the tricky parameters: it defines `giftId`'s source, explains the field-by-field merge of `content`/`options` (how to pass them), and clarifies `venueIds` role requirements. It says nothing about `message` or `orgId`, so it isn't fully compensating for the coverage gap.

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+resource ("Edit a birthday gift") and anchors `giftId` to list_birthday_gifts, so an agent can separate it from create_birthday_gift and list_birthday_gifts. It stops short of an explicit "not for creating" exclusion, which keeps it at 4 rather than 5.

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

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

It states the operative conditions: send only the keys being edited, at least one field is required, and use `status` to stop/resume sending. It also advises confirming with the user first, which is actionable usage guidance. No sibling alternative is named for edge cases, so it falls 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.