Cluby MCP

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?

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?

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.