Momence MCP by usefulapi

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

Annotations only supply destructiveHint=true, so the description carries real weight and delivers: it discloses the deferred booking behavior, that Momence auto-selects the best matching bought membership unless useBoughtMembershipIds overrides it, and the returned waitlistBookingId. That partially explains the destructive/mutating nature. It does not mention auth requirements or whether the addition itself can be rejected, keeping 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 short sentences, front-loaded with the core action, then the non-obvious side effect, then the return value and endpoint. Every sentence earns its place and nothing is padded.

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

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

With no output schema, the description compensates by naming the return value (waitlistBookingId) and by explaining the deferred mutation and membership-selection logic. For a 3-parameter mutation tool with full schema coverage, nothing an agent needs in order to invoke it correctly 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema text: it explains that omitting useBoughtMembershipIds makes Momence pick the best matching membership, i.e. the consequence of leaving the parameter out. That is information the schema's one-line description does not convey.

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 ('Put a member on a session's waitlist') and distinguishes itself from siblings like momence_book_member_free and momence_cancel_session_booking, which all operate on session bookings but do something different. An agent can select this tool without opening any 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?

The description implies when this is used (a member wants a session that has no available spot) and explains membership-selection behavior at booking time, but never explicitly states when to prefer it over alternatives such as momence_book_member_free, nor any preconditions (e.g., session must be full). Usage is implied rather than stated.

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

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

Annotations only provide destructiveHint=true, so the description carries most of the burden and does well: it discloses the no-charge side effect, the blast radius of the recurring flag (every future occurrence), and the returned sessionBookingId. It does not cover auth requirements or behavior on duplicate/existing bookings, so not a 5. No contradiction with destructiveHint.

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 short sentences, front-loaded with the core action and its free/recurring qualifiers, followed by return value, undo path, and endpoint. 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 correctly supplies the return value and the undo mechanism, and covers all three parameters. It omits edge-case behavior (already-booked members, capacity failures), which is the only remaining gap for a mutation 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?

Schema coverage is 100%, so the baseline is 3. The description's mention of recurring booking 'for every occurrence of a recurring class' adds a mild constraint hint, but the schema already documents createRecurringBooking with '(recurring sessions only)', so little net new meaning is added.

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 (Add/book), resource (member to a session) and distinguishing scope (at no charge / comp booking), plus the optional recurring variant. An agent can tell this apart from the paid-booking and waitlist siblings 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 clear usage context (comp booking, no charge) and names the reversal path ('Undo with momence_cancel_session_booking'), which routes the agent correctly for undo cases. It does not state explicit when-not conditions (e.g., member already booked, class full), so it stops 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.

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

Annotations only supply destructiveHint=true; the description carries the real weight by disclosing the default refund/penalty/notification behavior, the effect of each flag, and the irreversibility of the operation. That is far beyond what the annotation provides.

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

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

Front-loads the scope limitation, then defaults, then flag semantics, then reversibility and endpoint. Every sentence adds a distinct operational fact with no filler.

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

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

With no output schema, the description still covers scope, defaults, flag semantics, reversibility, and the underlying endpoint. An agent has everything needed to call this destructive operation correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds policy-level meaning: refund returns 'the member's payment or credit' and isLateCancellation applies 'the studio's late-cancel policy.' It does not explain disableNotifications, though the 'member IS notified' default implies it.

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

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

States a specific verb and resource ('Cancel a SINGLE session booking') and immediately scopes out the sibling concept of a recurring series. An agent can distinguish the intent 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?

Explains the default behavior and when to set refund=true or isLateCancellation=true, and notes the action is not undoable except by re-booking. It stops short of naming an explicit alternative tool or an explicit when-not-to-use condition beyond the recurring-series scope.

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 supply destructiveHint=true, so the safety bar is lower, but the description adds no behavioral context beyond the return value: no duplicate/merge behavior, no idempotency, no auth or permission notes. For a create endpoint that the annotations flag as destructive, that silence is meaningful.

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

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

Two short sentences, front-loaded with the action and the return value. The trailing 'Momence: POST /api/v2/host/members.' is cross-reference metadata rather than agent-useful content, a minor use of space.

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 correctly fills that gap by naming the returned memberId. However, for a five-parameter creation tool flagged destructive, it omits duplicate handling and payload expectations, leaving it only minimally sufficient.

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% (all five params documented), so the schema carries the parameter burden and a 3 is the baseline. The description contributes no additional parameter meaning such as format examples or how homeLocationId resolves.

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 ('Add a new customer to the studio') and adds the return value ('Returns the new memberId'), which cleanly separates it from get_member, list_members, and update_member. It does not name a sibling alternative explicitly, 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?

No guidance on when to use this versus alternatives such as momence_update_member or momence_add_member_to_waitlist, and no prerequisites. Nothing tells the agent what to do if the customer already 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?

Annotations only declare readOnlyHint, so the description adds real value: it discloses the response shape (userId, email, name) despite there being no output schema, and flags the call as cheap, which supports using it as a credential preflight. It does not describe failure behavior (e.g. auth errors) or rate limits, keeping 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 short sentences, each earning its place: what it returns, why to call it, and the underlying endpoint. The return fields are front-loaded before the rationale.

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 tool with no output schema, the description covers everything needed: the identity of the resource, the fields returned, and the practical reason to invoke it. Nothing required for correct invocation 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?

Zero parameters, so the schema has nothing to document and by rule the baseline is 4. The description correctly adds no parameter text, and the parenthetical field list describes output, not input.

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

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

Specific verb+resource: returns the authenticated staff user, with the returned fields (userId, email, name) named inline. The 'acting as' framing cleanly separates it from sibling momence_get_member, which fetches an arbitrary member rather than the credential principal.

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?

'A cheap way to confirm the credentials work' gives a concrete use case, so the agent knows when this is the right call. It stops short of naming an alternative or stating when not to use it, but for a zero-arg identity probe the context is clear.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description goes further by naming the returned fields (contact details, first/last seen, visit counts, custom fields, tags) and the underlying endpoint, which is real value given there is no output schema. It still says nothing about auth scoping or error behavior when the id is unknown.

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 sentence plus the endpoint reference, with the payload description front-loaded before the API detail. Nothing is redundant, though the raw endpoint line is of marginal value to an agent that already has the tool.

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

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

For a simple one-parameter read with no output schema, the description supplies enough of the return shape to set expectations. It stops short of describing null/not-found behavior or nesting of custom fields and tags, which is a minor gap.

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

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

Schema description coverage is 100% for the single memberId parameter, so the schema already carries the semantics. The description only restates 'by id' and embeds it in the endpoint template, adding no format, range, or sourcing guidance 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?

States a specific verb (fetch) and resource (one customer, by id) and enumerates the payload it returns. The singular 'one customer by id' implicitly separates it from momence_list_members, but it never names that sibling, so the distinction 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?

Usage is only implied: the 'by id' framing tells the agent a memberId is required and that this is a single-record lookup rather than a search. There is no explicit when-to-use, when-not, or pointer to momence_list_members / momence_get_current_user as alternatives.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing the shape of the payload (capacity/booking counts, waitlist, teachers, tags), which is real added context given there is no output schema.

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: the field enumeration first, then the underlying API endpoint. No filler, and the most decision-relevant content 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 sensibly compensates by listing the returned fields, and the readOnly annotation covers safety. It stops short of noting behavior when the sessionId does not exist or any pagination/expansion options, which would have made it fully complete.

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

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

Schema coverage is 100% and the single sessionId parameter is documented in the schema itself. The description adds no format, constraint, or sourcing guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and singular resource ("Fetch one session's detail") and enumerates exactly what the detail contains (times, capacity, booking count, waitlist, teachers, location, stream details, tags). The singular "one session" contrasts naturally with the sibling momence_list_sessions.

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 by the required sessionId and the singular scope, but the description never states when to prefer this over momence_list_sessions or momence_list_session_bookings. No prerequisites or exclusions are given, so the agent must infer the routing.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds which fields come back and the underlying API path, but says nothing about pagination defaults, rate limits, or result truncation behavior despite 10 parameters and no output schema.

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, front-loaded with the purpose and the returned fields. The trailing 'Momence: GET /api/v2/host/appointments/reservations' line is arguably redundant for an agent caller, but it costs little and identifies the endpoint.

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

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

For a 10-parameter, zero-required list tool with no output schema, the description helpfully names the returned fields but omits pagination behavior and how the many date/paid filters interact. Adequate but with clear gaps for an agent that must page results.

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 every parameter (page, pageSize, isPaid, date bounds, sortOrder, includeCancelled, includeCancelledAttendees) is already documented in the schema. The description adds no filtering syntax or constraints beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List all appointment reservations across the studio') and enumerates the data returned (service, teacher, time, price, paid state, attendees). The scope word 'across the studio' implicitly distinguishes it from the member-scoped sibling momence_list_member_appointments, though the sibling is never named.

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

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

Usage is only implied by the studio-wide scope; there is no explicit when-to-use statement, no exclusion of includeCancelled semantics, and no routing guidance versus momence_list_member_appointments or momence_list_session_bookings. An agent must infer the choice from scope alone.

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, so the description is free to add domain behavior — notably that a non-null memberId signals a converted lead, plus the underlying GET endpoint. It does not discuss pagination behavior or result ordering, but it contributes real semantics 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 tight sentences with the list scope, the conversion signal, and the filter/resolution guidance front-loaded; nothing is redundant and no filler is present.

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 helpfully explains how to interpret the returned memberId, and it covers filtering and id resolution. Minor gaps remain — response shape and pagination/sorting behavior are left to the schema — but nothing essential to a correct 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?

Schema description coverage is 100%, so parameters are already documented and the baseline is 3. The description goes beyond that by explaining that sourceId/stageId are foreign keys to be obtained from sibling list tools, which is meaningful cross-tool context the schema itself omits.

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

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

States a specific verb and resource ('List the studio's sales leads') and adds a scope-defining detail — leads are both open and converted, with a non-null memberId marking conversion. An agent can tell this apart from momence_list_members and the related lead-source/stage listers without opening another 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?

Explicitly says what can be filtered (search text, lead source, pipeline stage) and directs the agent to resolve the source/stage ids via momence_list_lead_sources and momence_list_lead_stages. There is no explicit when-not or exclusion, but the routing guidance is clear and actionable.

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 reinforces this by citing the GET endpoint. It adds the resolution purpose, which is useful context, but says nothing about pagination behavior, total counts, or result ordering beyond what the schema already lists.

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

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

Two compact sentences with zero filler, and the tool's purpose and its relevance to sourceId resolution are both front-loaded. Every clause 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 read-only list tool with full schema coverage and no output schema, the description covers purpose and the underlying endpoint adequately. The only minor gap is that return shape and pagination semantics are left to inference.

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 page, pageSize, query, and sortOrder are all fully documented in the schema itself. The description adds no parameter syntax or filtering semantics beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('lead sources'), and the parenthetical adds real meaning: it resolves the sourceId on customer leads, tying it to the related list_customer_leads tool. It stops short of naming sibling tools explicitly, so an agent still has to infer it from context.

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 explicit when-to-use or when-not-to-use guidance and no named alternatives. However, 'resolves the sourceId on customer leads' implies the usage context (look up source names when dealing with customer leads), which is enough to be considered implied usage rather than none.

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

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

readOnlyHint=true already declares the safety profile, so the burden is lighter. The description adds only the REST endpoint mapping and the stageId-resolution purpose; it says nothing about pagination behavior, result size, or auth requirements, which the schema only partially covers.

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

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

Two short sentences, front-loaded with the resource and purpose. The raw endpoint path is arguably low-value for an agent but costs little; there is no filler or repetition.

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, zero-required-parameter list tool with fully documented params, the definition is adequate for invocation. However, with no output schema, the description does not hint at what a stage record contains (name, order, id), leaving the agent to discover the return shape empirically.

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

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

Schema description coverage is 100% with all five parameters (page, query, sortBy, sortOrder, pageSize) documented in the schema, including enums and bounds. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('List lead pipeline stages') and frames the resource's role by noting it resolves the stageId on customer leads, which links it to the sibling momence_list_customer_leads. It does not explicitly distinguish itself from momence_list_lead_sources, 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?

The parenthetical 'resolves the stageId on customer leads' implies when the tool is useful (when interpreting a lead's stageId), but there is no explicit when-to-use, no mention of the alternative lead-sources listing, and no stated prerequisites. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds useful framing (these are appointment reservations / 1:1 services) plus the underlying API endpoint, but omits behavioral traits such as whether cancelled appointments are excluded by default and pagination/default-page behavior. Modest value 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?

Two tight sentences with the resource and scope front-loaded; the endpoint reference is borderline redundant but compact. No filler or repetition.

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?

A read-only list tool with no output schema, but full schema-description coverage and a clear safety annotation. The description plus structured fields give the agent enough to invoke correctly; a note on default cancelled-exclusion behavior would complete it.

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

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

Schema description coverage is 100%, so the schema itself documents all 9 parameters including the date filters, pagination, sort, and includeCancelled. The description adds nothing parameter-specific, so the baseline 3 for schema-covered params 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 (List), a precise resource (appointment reservations / 1:1 services), and a scope (of one member). The 'of one member' scoping implicitly distinguishes it from the sibling momence_list_appointments, though that sibling is never named. An agent can infer the difference, but explicit differentiation is absent.

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 by the 'of one member' scoping — you reach for this when you want a single member's appointments rather than all appointments. However, no explicit when-to-use, when-not-to-use, or alternatives (momence_list_appointments, momence_list_member_session_bookings) are provided. This is minimum-viable implied 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 readOnlyHint annotation already establishes the safe-read profile, so the description's added value is the disclosure of what is actually returned: active subscriptions and class packs with type, dates, credits left, usage limits, and freeze state. That is genuinely useful given there is no output schema. It doesn't cover pagination behavior, but the schema does.

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

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

One dense sentence front-loads the scope and then the returned fields, followed by the underlying endpoint. No filler, though the field list makes the single sentence fairly heavy.

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

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

With no output schema, the description compensates by naming the returned fields, and the schema fully covers the four parameters. An agent has enough to call it correctly; only explicit sibling routing and pagination semantics are absent, and pagination is covered by the schema.

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

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

Schema description coverage is 100%, so memberId, page, pageSize, and includeFrozen are all documented in the schema. The description only alludes to the scope ('active') and freeze state, adding no format or constraint detail beyond the schema, matching the baseline 3.

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

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

Specific verb (List) plus scoped resource (one member's active subscriptions and class packs), and it enumerates the fields returned (type, dates, credits, usage limits, freeze state). It scopes to a single member, which implicitly separates it from momence_list_memberships, but it never names or contrasts with a sibling explicitly.

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 by 'one member's active...' — you call it when you have a memberId and want that member's current bought memberships. There is no statement of when not to use it, no mention of the sibling momence_list_memberships, and no prerequisites such as required permissions.

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=true annotation already establishes that this is a safe read operation. The description adds useful note-type context (regular and SOAP) but does not disclose pagination behavior, permission requirements, or return structure beyond what the annotation and schema cover.

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: purpose first, endpoint second. No filler or repetition, and the core purpose 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?

A simple list tool with full schema parameter documentation and a read-only annotation. The description identifies the listed resource and note types, but does not discuss pagination or response shape; still adequate for the tool's complexity.

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 all five parameters are already documented in the input schema. The description reinforces member scoping through the endpoint path but adds no sorting, pagination, or filtering semantics beyond the schema.

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

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

States a specific verb ('List'), resource ('staff notes'), and scope ('recorded on one member'), including note subtypes regular and SOAP. It does not explicitly differentiate from sibling list_member_* tools, but the notes resource is distinct enough for an agent to identify the correct 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 gives no when-to-use guidance or alternatives. It only supplies the API endpoint, so the agent must infer that this tool is for retrieving a member's notes rather than any other member-related listing.

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?

With readOnlyHint=true already declaring a safe read, the description adds genuine value by disclosing the response payload (visit counts, custom fields, tags) and the underlying endpoint. It stops short of mentioning pagination/return-size behavior, but the safety profile is covered by annotations and the return-content hint is a useful addition.

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

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

Three short sentences, purpose front-loaded, then the two most useful filters, then the API reference. Tight and skimmable, though the endpoint string is marginally more for traceability than for agent decision-making.

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

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

For a 7-param, zero-required, read-only list tool with no output schema and full schema coverage, the description supplies what the schema cannot: the payload contents and the intent behind the key filters. Nothing an agent needs to invoke it correctly 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 all seven parameters, including the enums. The description restates query and filterPreset semantics without adding syntax or format detail beyond the schema, so the 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 names a specific verb+resource ('List or search the studio's customers (members)') and even lists the returned data (visit counts, custom fields, tags), so an agent immediately knows what this does. It does not explicitly contrast itself with neighbors like momence_get_member or momence_list_customer_leads, so it stops 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?

It gives parameter-level guidance ('Search by name, email or phone with query; use filterPreset=with-active-membership for current members'), which implies when each filter applies. However, it never states when to prefer this tool over alternatives such as momence_get_member (single lookup) or momence_list_customer_leads, so the tool-selection guidance is only 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?

Annotations already declare readOnlyHint=true, so the agent knows this is a non-mutating read. The description adds useful content-level context (results carry session details and check-in state) and the upstream endpoint, but says nothing about pagination behavior, default result ordering, or what happens when includeCancelled is omitted.

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, zero filler, with the core purpose front-loaded before the endpoint reference. Nothing needs to be cut or reordered.

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 9-parameter, single-object, read-only list tool with full schema coverage and no output schema, the description covers what the tool returns at a high level and the safety profile is carried by annotations. It is slightly thin on pagination/filter interaction and on how cancelled bookings appear, but nothing essential to invoking it correctly 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 every one of the 9 parameters is already documented in the schema, including the date filters, page/pageSize, sortOrder enum, and includeCancelled. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (List), a specific resource (class/session bookings), and a scope (of one member), plus what the response contains (session details and check-in state). The 'of one member' qualifier implicitly separates it from the sibling momence_list_session_bookings, which lists bookings without a member scope.

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 explicit when-to-use, when-not-to-use, or alternative-selection guidance. The description never mentions sibling tools such as momence_list_member_appointments or momence_list_session_bookings, nor does it state prerequisites (e.g. a valid memberId). Usage is only faintly implied by the scope phrase.

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 adds the backing endpoint (GET /api/v2/host/memberships) and the set of returned attributes, but says nothing about pagination defaults, disabled-plan handling, or rate limits beyond what the schema already documents.

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

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

Two tight sentences with the core scope front-loaded and filtering mentioned second. The trailing endpoint reference is useful for mapping but slightly bolted-on, keeping it short of a 5.

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 carries the burden of describing returns, and it does so by listing pricing, duration, credits, usage limits, and trial/intro flags. For a read-only list tool with fully documented parameters this is nearly complete; only pagination behavior is left unstated.

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

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

Schema description coverage is 100%, so all eight parameters are self-documenting. The description only restates the session/appointment compatibility filters and omits any guidance on sortBy, sortOrder, includeDisabled, or reasonable pageSize values. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (the membership plans the studio sells), then enumerates the subtypes (subscriptions, class packs, money packs) and the fields surfaced. This is clearly distinguishable from momence_list_member_memberships, which covers a member's plans rather than the studio's catalog.

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 offers one usage condition ('Optionally only plans usable for a given session or appointment'), which maps to the two compatibility filters, but gives no when-not guidance and never names an alternative sibling tool. Usage is implied rather than directed.

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 confirm readOnlyHint=true, so safety is covered; the description adds return-shape disclosure (booking id, member, check-in state, recurring-booking id), which is genuinely useful given there is no output schema. It stops short of describing pagination behavior or how cancelled bookings appear when includeCancelled is set.

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

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

One front-loaded sentence carries the purpose and the return contents, followed by a compact endpoint reference. No filler or restatement of the name.

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 six fully documented parameters and no output schema, the description fills the main gap by naming the fields each booking row contains. Only minor gaps remain — no note on pagination shape or how the cancelled-booking option affects results.

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 page, pageSize, sortBy, sortOrder and includeCancelled are already fully documented in the schema. The description adds only the notion of a single session scope, which the schema's sessionId entry already conveys — 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?

Specific verb (list) plus a tightly scoped resource ('who is booked into one session — the class roster') and an enumeration of the returned fields. The phrase 'one session' implicitly separates it from the sibling momence_list_member_session_bookings, which pivots on the member rather than the session.

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 session-scoped framing implies when the tool applies, but the description never states when to prefer it over momence_list_member_session_bookings or momence_get_session, nor does it mention any prerequisites or exclusions. Usage is inferable rather than stated.

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

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

The readOnlyHint annotation already establishes this as a safe read, so the description adds little on the safety axis. It does disclose what the response contains (time, teacher, location, capacity, booking count), but says nothing about pagination behavior or the default exclusion of cancelled sessions.

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

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

Two tight sentences with the resource and returned fields front-loaded, followed by the filter dimensions. No filler, and the API endpoint is a compact addendum.

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 13-parameter read tool with no output schema, the description helpfully summarizes the returned fields and the filter axes, which is the key missing context. It stops short of covering pagination defaults or the cancelled-session default, but is largely adequate.

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 all 13 parameters including enums and ISO 8601 formats. The description only restates the filter categories generically and adds no format or default details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (scheduled sessions) and enumerates the subtypes it covers (classes, events, courses) plus the returned fields, which clearly separates it from momence_get_session (single session) and momence_list_session_bookings (bookings). An agent can identify 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?

It names the filter dimensions (date window, type, teacher, location), which implies the intended usage, but never states when to prefer this over siblings like momence_list_session_bookings or when to exclude cancelled sessions. Usage is implied 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 tells the agent this is a non-destructive read, so the safety burden is lifted. The description adds the GET endpoint path (minor operational context) but says nothing about pagination behavior or result shape. Adequate but thin 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?

One front-loaded sentence carrying the resource, its purpose, and the endpoint, with zero filler. Nothing to trim.

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 no-required-param list tool with no output schema, the description covers what is listed and what the ids are for. It could mention that results are paginated by default (20/page), but the schema already carries that.

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% – page, pageSize, and sortOrder are all documented in the schema with defaults and bounds. The description adds nothing about parameters, so baseline 3 applies.

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

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

States a specific verb and resource ('List the customer tags defined for the studio') and goes further by naming the sibling consumer of the returned ids (momence_set_member_tag) and the underlying endpoint. An agent can distinguish this from momence_list_members or momence_list_memberships without any further 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?

The parenthetical '(ids for momence_set_member_tag)' gives a clear reason to call this tool: retrieving tag ids needed by the setter. However, it offers no explicit when-not guidance or exclusion relative to other list tools, so it stops short of the top band.

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?

destructiveHint=true already signals a mutating operation, so the description's addition of the POST vs DELETE endpoint mapping and the 'undo the check-in' semantics adds real context beyond the annotation. However, it omits idempotency, permission/auth requirements, and whether the undo is reversible or loses data, which matters for a toggle flagged destructive.

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 action and toggle semantics, followed by the id source and endpoint. Nothing is redundant or padded.

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-required-parameter mutation with no output schema, the description covers action, direction, id provenance, and the underlying endpoints. It stops short of describing the response or error behavior, so it is strong but not exhaustive.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the description largely restates checkedIn=true/false. The only added value is tracing bookingId provenance to momence_list_session_bookings, which is useful but not schema-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?

States a specific verb+resource pair ('mark a session booking as checked in') and explicitly covers both directions of the toggle via checkedIn=true/false. The semantics are distinguishable from siblings such as momence_cancel_session_booking or momence_list_session_bookings 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?

Provides a clear prerequisite/context by naming the upstream tool that supplies booking ids (momence_list_session_bookings). It does not state when NOT to use this (e.g., versus cancelling a booking), but the operational context is unambiguous.

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

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

Annotations only supply destructiveHint=true, so the description adds real value by declaring the operation fully reversible and mapping it to the underlying POST/DELETE endpoints. This tempers the destructive hint usefully rather than contradicting it, though permission requirements are not mentioned.

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 tightly packed sentences front-load the core behavior, then reversibility, then id provenance and API mapping. 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 3-parameter, no-output-schema, no-nested-object tool, the description covers mode selection, id sourcing, reversibility, and endpoint mapping. Nothing an agent needs to call it correctly 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 coverage is 100%, so a 3 is the baseline, and the description earns a point by explaining the boolean's semantics and, more importantly, where tagId values originate (momence_list_tags) — information the schema does not contain.

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 pairing (assign/remove) over a specific resource (customer tag on a member), and immediately disambiguates the two modes via assigned=true/false. No sibling tool does tag management, so the agent can select this unambiguously.

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 condition that selects each mode (assigned=true to add, false to remove) and points to momence_list_tags as the source of valid tag ids. It does not name exclusions or prerequisites, but the operation space is narrow enough that this is sufficient context.

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

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

Annotations only declare destructiveHint=true; the description goes well beyond that by disclosing that each field is a separate API call (with the actual endpoints), that the calls execute in a fixed order (name, email, phone), and that execution stops at the first failure — i.e. the operation is non-atomic and can partially succeed. That is exactly the behavioral context an agent needs before invoking a mutation.

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

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

One dense sentence with the core purpose front-loaded, followed by the parameter interdependency and the failure semantics. No filler, no repetition of the title, and every clause carries information the agent needs.

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 5-parameter mutation with no output schema and thin annotations, the description covers the highest-risk unknown (non-atomic partial failure) and the field-combination rules. It stops short of noting permission requirements or what state the member is left in after a mid-sequence failure, which would be the remaining 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 coverage is 100% and the schema already encodes the firstName/lastName interlock, so the baseline is 3. The description still adds real value by tying each parameter to a distinct endpoint call and an execution order, and by restating the and/or combination semantics (any subset of rename/email/phone).

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: "Correct a customer's contact details", with the concrete fields it touches (name, email, phone) spelled out. It doesn't name a sibling alternative (e.g. vs. momence_create_member), but the operation is unambiguous from the title and first sentence.

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 by "Correct a customer's contact details" and the field-combination rules, but there is no explicit when-to-use/when-not guidance and no routing to alternatives such as momence_create_member or momence_get_member. An agent can infer the context but must supply the exclusions itself.

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