momence

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

Annotations only supply destructiveHint=true, so the description carries most of the load: it discloses the membership-selection behavior on waitlist conversion, the useBoughtMembershipIds override condition, and the returned waitlistBookingId. It does not state auth or rate-limit needs, 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 tight sentences, front-loaded with the action and followed by the conditional behavior and return value. The trailing REST endpoint is mildly extraneous but not wasteful.

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 mutation with no output schema, the description covers the action, the conditional membership behavior, and the return value (waitlistBookingId). It is complete enough to call correctly, with only auth/permission context 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 real meaning for useBoughtMembershipIds: without it Momence picks the best matching bought membership, with it those specific memberships are tried. That is behavior the schema's terse 'Bought memberships to try' 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?

States a specific verb and resource ('Put a member on a session's waitlist') that clearly distinguishes it from sibling booking tools like momence_book_member_free and momence_cancel_session_booking.

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

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

It implies when the tool applies by explaining the downstream waitlist-booking flow, but never states when to use this versus booking directly or how it relates to sibling tools. Usage is inferable rather than explicit.

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

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

Annotations supply only destructiveHint=true; the description adds real value beyond that by disclosing the return value (sessionBookingId), the comp/no-charge nature, and the reversal path. It does not disclose auth/permission requirements or explicitly warn that createRecurringBooking will write many bookings at once.

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 core action and consequence, then the return value, then undo. The trailing raw endpoint reference is extra but compact and useful for API-aware agents; 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 correctly states the return field (sessionBookingId), and it covers the recurring side effect and reversal route. Missing only permission/eligibility context that would matter for a write tool flagged destructive.

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 three parameters are documented inline, so the schema does the heavy lifting. The description reinforces the recurring flag's meaning but adds no syntax or constraint detail beyond the schema.

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

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

States a specific verb+resource (add a member to a session) and pins down the distinguishing condition: 'at no charge (a comp booking)'. The optional recurring behavior is also named, so an agent can tell it apart from generic booking or waitlist siblings.

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

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

Names the inverse operation ('Undo with momence_cancel_session_booking'), which is explicit routing to a sibling. It does not state when to prefer this over a paid booking path or what prerequisites (member/session eligibility) apply, so it stops short of full when/when-not guidance.

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

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

Annotations only supply destructiveHint=true; the description carries the real behavioral payload, disclosing the three defaults (no refund, no late-cancel penalty, member notified) and the irreversibility ('Not undoable except by re-booking'). These are exactly the consequence-level details an agent needs before a destructive call.

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

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

Front-loaded with scope, then defaults, then the two opt-in flags, then irreversibility. Every clause is decision-relevant; the trailing API-endpoint note is the only near-filler and is short.

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

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

For a destructive, no-output-schema tool with minimal annotations, the description covers scope, defaults, opt-in side effects, notification behavior, and reversibility. Nothing an agent needs to invoke it safely 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 consequence meaning the schema lacks: refund=true returns payment or credit, isLateCancellation applies the studio policy, and 'the member IS notified' implicitly explains disableNotifications. Modest but genuine value beyond the field docs.

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 ('Cancel a SINGLE session booking') and immediately disambiguates scope by excluding recurring series. An agent can distinguish this from booking/list siblings and from any series-cancellation tool without opening a schema.

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

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

Gives explicit conditions for the two optional toggles: 'Set refund=true only to return the member's payment' and 'isLateCancellation=true applies the studio's late-cancel policy', plus the exclusion of recurring series. It stops short of naming the sibling tool to use for a recurring series, so routing is implied rather than fully closed.

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 carry destructiveHint=true, so the description adds real value by disclosing that the response returns the new memberId and that this maps to POST /api/v2/host/members. It does not mention auth needs, whether email must be unique, or behavior on duplicate submissions, which matters for a create operation.

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 with zero filler, front-loading the action first and the return value and endpoint after. 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 create tool with no output schema, disclosing the returned memberId is a helpful touch, and parameters are fully covered by the schema. However, key mutation context (auth requirements, duplicate-email handling) is absent, and the destructiveHint annotation is unexplained.

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 each of the 5 parameters is already documented in the schema. The description adds no extra syntax, format, or constraint detail beyond what the schema provides, 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 ('Add a new customer to the studio') and clarifies the return value ('Returns the new memberId'). It clearly separates create from read/update siblings like get_member, update_member, and list_members, though it never explicitly names a sibling to disambiguate from add_member_to_waitlist.

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 says what the tool does but gives no guidance on when to use it versus alternatives such as add_member_to_waitlist or update_member, and lists no prerequisites. Usage is only inferable from the verb 'add'.

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 naming the exact return fields and disclosing the underlying endpoint (GET /api/v2/auth/profile), which signals it is a non-mutating identity probe. No rate-limit or error behavior is 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 short sentences with zero filler; the purpose and return payload lead, the usage hint and endpoint follow. Every sentence 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?

With no output schema, the description compensates by naming the returned fields (userId, email, name) and characterizing the call as cheap. An agent has everything needed to invoke and interpret 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline for a 0-param schema applies, and the description correctly avoids redundant parameter talk.

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 ('Return the staff user the API is acting as') and enumerates the returned fields (userId, email, name). This clearly distinguishes it from the member- and session-oriented siblings, none of which describe the acting identity.

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 usage context that an agent can act on. It stops short of stating explicit when-not conditions or naming alternatives, but for a parameterless identity check there are no real competing siblings.

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 safe-read profile is covered. The description adds useful field-level context about what is returned and cites the underlying endpoint, but says nothing about error behavior (e.g., invalid/unknown memberId) or any permission scoping.

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 sentence with zero waste, front-loading the action and resource before the returned fields. The endpoint citation is compact supplementary information rather than 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 simple read-only lookup with one fully documented parameter and readOnlyHint annotations, the description covers purpose and return shape adequately even without an output schema. Only minor gaps remain around error handling and authorization scope.

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's 'by id' merely reinforces that memberId is the identifying key without adding format or constraint details.

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 ('Fetch one customer by id') and enumerates the returned data (contact details, first/last seen, visit counts, custom fields, tags). 'By id' implicitly distinguishes it from the sibling list_members, though no sibling is named 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?

The 'by id' phrasing implies single-record lookup, but there is no explicit guidance on when to use this versus list_members or get_current_user, and no prerequisites or exclusions are stated. Usage is inferable rather than stated.

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

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

readOnlyHint=true already covers the safety profile, so the description's added value is the field-level inventory (times, capacity, booking count, waitlist, teachers, location, stream details, tags). It does not discuss behavior on a missing/invalid sessionId or any permission requirements, 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?

One dense sentence front-loads the purpose and payload, followed by a compact API reference. No filler and nothing buried.

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

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

With no output schema, the description usefully enumerates the returned fields, which compensates for the missing return documentation. For a single-parameter read operation, nothing essential is missing, though error cases are unspecified.

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 a single documented sessionId parameter, so the baseline is 3. The description only echoes the id in the URL template (GET /api/v2/host/sessions/{sessionId}) and adds no format or constraint meaning beyond the schema.

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

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

States a specific verb and resource ('Fetch one session's detail') and enumerates the returned surface area, which cleanly distinguishes it from the plural sibling momence_list_sessions. An agent can pick it without opening the schema.

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

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

Usage is implied by 'one session' versus the list sibling, but there is no explicit when-to-use/when-not guidance and no named alternative. Adequate but leaves routing inference to the agent.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered and the bar is lower. The description adds the result field set and the underlying endpoint, which is useful context, but does not disclose pagination behavior, default sorting, or whether the response is paginated beyond what the schema hints at.

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 with the resource scope front-loaded and the field list and endpoint following compactly. Nothing is redundant and every clause carries information.

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

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

There is no output schema, and the description partially compensates by listing the returned fields, while all 10 parameters are documented in the schema. Read-only annotations cover safety. What is missing is pagination/result-count guidance, which is minor for a list 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 description coverage is 100% across all 10 parameters, so filters like isPaid, includeCancelled, the start/end bounds, and pagination are already fully documented. The description's parenthetical enumerates result fields rather than filter semantics, so it adds little beyond the schema baseline of 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?

The description names a specific verb and resource ('List all appointment reservations across the studio') and enumerates the fields carried in the results, so the agent knows exactly what it returns. It also supplies the underlying API route. It stops short of naming a sibling for contrast, though 'across the studio' implicitly separates it from momence_list_member_appointments.

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?

Scope is implied by 'across the studio,' which suggests this is the studio-wide listing versus a member-scoped one, but there is no explicit when-to-use statement, no indication of when to prefer momence_list_member_appointments, and no mention of prerequisites or pagination strategy.

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 the safety profile, the description adds real behavioral context beyond annotations: the semantic meaning of memberId (converted vs open) and the underlying GET endpoint. It does not describe pagination/result-size behavior, but for a read-only list tool this is solid added context.

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 plus a short endpoint note; the core purpose and conversion rule are front-loaded. The trailing 'Momence: GET /api/v2/host/customer-leads' is low-value for an agent but not disruptive.

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 description covers the key interpretive need (what 'converted' means) and how to obtain valid filter ids. Details like default page size and total counts live in the schema, so the description is largely complete for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds meaning beyond the schema by tying sourceId and stageId to the sibling lookup tools needed to resolve them. It also frames query as search text over name/email/phone, reinforcing rather than merely repeating the schema.

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

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

States a specific verb and resource ('List the studio's sales leads') and narrows scope with 'open and converted'. It also distinguishes the data model by defining that a non-null memberId means converted, so an agent knows exactly what population it is querying.

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 available filter axes (search text, lead source, pipeline stage) and explicitly routes the agent to momence_list_lead_sources and momence_list_lead_stages for id resolution. It gives clear usage context but no explicit when-not-to-use or exclusion against near siblings.

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 HTTP endpoint, which is mildly useful, but does not mention pagination behavior or return shape despite four pagination-related parameters.

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 clauses with zero filler, front-loading the action and resource before the endpoint detail.

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 list tool with a fully documented schema and readOnly annotation, the description supplies enough context. Missing pagination/return notes are minor because the schema covers parameters and the tool is read-only.

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 already documented in the schema. The description adds no parameter meaning beyond that, making the baseline 3 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?

States a specific verb and resource ('List lead sources') and clarifies its role by noting it resolves the sourceId on customer leads. It is clear but does not explicitly distinguish itself from the similar sibling momence_list_lead_stages.

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 sourceId on customer leads' implies when the tool is useful, but there is no explicit when-to-use guidance or statement of 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?

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds the stageId-resolution relationship and the underlying GET endpoint, but says nothing about pagination behavior, result ordering, or whether the list is host-scoped or filtered by default.

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 clauses: purpose first, then the API reference. No filler, nothing repeated from the name or title, and the most important fact (what the stages are for) is front-loaded.

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

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

For a read-only, zero-required-parameter list tool with a fully documented schema and no output schema, the description covers purpose and cross-reference adequately. Only minor gaps remain (result shape conventions, default ordering), which the schema's sort defaults partly imply.

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, query, sortBy, and sortOrder all carry inline descriptions and the two sort params have enums. The description adds no parameter meaning 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 ('lead pipeline stages'), and the parenthetical adds the key semantic hook — that these stages resolve the stageId found on customer leads. That distinguishes it from sibling list tools like momence_list_lead_sources.

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 implies the usage context (resolving a stageId you already have on a lead), which is useful, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative to prefer or avoid. Usage is inferable rather than stated.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds worthwhile context by clarifying that 'appointment reservations' means 1:1 services and mapping to the REST endpoint, but it does not mention that cancelled appointments are excluded by default (includeCancelled exists) or describe pagination behavior. Useful addition, but not rich behavioral disclosure.

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

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

Two short sentences, purpose front-loaded first and the endpoint reference second. No filler, no repetition of the title.

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 paged list tool with full schema coverage and an explicit readOnlyHint, the description gives everything needed to invoke it correctly. Only the default exclusion of cancelled appointments and any indication of the response shape (there is no output schema) are 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% across all 9 parameters, including the date-window filters, sort order, paging and includeCancelled, so the schema carries the semantics. The description adds no syntax, defaults or filter meaning beyond it, making the baseline 3 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?

States a specific verb (List) and resource (appointment reservations / 1:1 services) scoped to one member, and even supplies the underlying endpoint GET /api/v2/host/members/{memberId}/appointments. It is clear what it returns, though it never explicitly contrasts itself with the sibling momence_list_appointments, which an agent could easily confuse it with.

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: 'of one member' signals you need a memberId, but there is no statement of when to prefer this over momence_list_appointments or momence_list_member_session_bookings, and 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?

The readOnlyHint annotation already establishes this as a safe read. The description usefully adds the returned field set and the underlying endpoint, but says nothing about pagination behavior or the fact that frozen memberships are excluded unless includeFrozen is set, despite naming 'freeze state' as a return field.

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, front-loaded sentence naming the resource and its payload, followed by a short endpoint reference. It is efficient, though the raw endpoint string adds little for an agent deciding whether to call it.

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 enumerating the returned fields, and the schema fully covers the four inputs. Remaining gaps are minor: no note that frozen memberships require the includeFrozen flag.

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 four parameters (memberId, page, pageSize, includeFrozen) are already documented with defaults and ranges. The description adds no syntax or format detail beyond that baseline.

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 scoped to one member, and enumerates exactly what is returned (type, dates, credits left, usage limits, freeze state). It is cleanly distinguishable from the bulk sibling momence_list_memberships and from momence_get_member.

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 scope ('one member's active subscriptions'), but there is no explicit when-to-use guidance, no mention of when to prefer momence_list_memberships or momence_get_member, and no exclusions 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 covered. The description adds the endpoint path and the fact that both regular and SOAP note types are returned, which is useful content-level context, but it says nothing about pagination behaviour, result ordering, or what an empty list means. With annotations carrying the safety burden, this is a moderate contribution.

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 the purpose front-loaded and the API endpoint appended as supporting detail. No filler sentences and nothing that would need to be trimmed.

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 paginated read tool with full schema coverage, an existing readOnlyHint annotation, and no output schema, the description supplies the essential purpose and content scope. The remaining gap is minor: it does not hint at return shape or default sort, which an agent might want since no output schema exists.

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, and sortOrder are already fully documented in the schema, and the baseline for this case is 3. The description adds no parameter-level detail (no default ordering, no note-type filter), so it does not exceed the schema baseline.

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 staff notes ... recorded on one member') and even narrows the content type to regular and SOAP notes, so an agent can tell it is a per-member note listing rather than a general member read. It does not explicitly contrast with siblings such as momence_get_member, which could plausibly surface similar data, so it falls just 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 description gives no when-to-use or when-not-to-use guidance and names no alternative. An agent is not told whether to prefer this over momence_get_member when it wants a member's notes, nor that memberId must reference an existing member. Usage is left to inference from the resource name.

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 the operation is a safe read, so the description only needs to add context — which it does by disclosing the shape of the returned data (visit counts, custom fields, tags) and the underlying endpoint. Pagination and rate-limit behavior are not mentioned, but the schema covers paging.

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 purpose and then the two most decision-relevant parameters. The trailing 'Momence: GET /api/v2/host/members' is minor noise that does not help tool selection.

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

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

With no output schema and seven optional parameters, the description usefully summarizes the returned fields and the two filter entry points. It is nearly complete for a read-only list tool, missing only guidance on default ordering and result volume.

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 every parameter is self-documented, so the baseline is 3. The description restates the semantics of `query` and `filterPreset` rather than adding new meaning, and says nothing about sortBy, sortOrder, staticSegmentId or pageSize.

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

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

The description states a specific verb and resource ('List or search the studio's customers (members)') and even names the fields returned (visit counts, custom fields, tags). It is clearly the bulk-listing counterpart to the singular momence_get_member, though it never names that sibling to make the distinction explicit.

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 concrete conditions for two parameters ('Search by name, email or phone with `query`', 'use filterPreset=with-active-membership for current members'), which tells the agent when to reach for them. It stops short of naming alternatives such as momence_get_member for a single record or the segment-based filtering path.

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 need not re-state that. It does add useful behavioral content by disclosing what the response contains (session details and check-in state), which matters since no output schema exists, but it is silent on pagination behavior despite page/pageSize/sortOrder parameters.

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 purpose; the second is just the upstream endpoint reference. Nothing is padded, though the raw API path contributes little for an agent.

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 read tool with no output schema, the description covers the gist of the return but not pagination or result-set behavior. The well-documented schema compensates for the parameter side, leaving the definition adequate but not complete.

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

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

Schema description coverage is 100%, with each parameter (date filters, pagination, includeCancelled, sortOrder) fully documented in the schema, so the baseline of 3 applies. The description adds no parameter-level meaning beyond identifying memberId implicitly.

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

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

The description uses a specific verb ('List') plus resource ('class/session bookings of one member') and explicitly notes the returned content (session details and check-in state). The 'of one member' scoping implicitly separates it from momence_list_session_bookings, but no sibling is named 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?

There is no statement of when to use this tool versus alternatives such as momence_list_session_bookings or momence_list_member_appointments, and no prerequisites or exclusions. Usage can only be inferred from the naming.

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 the safe read profile, the description still adds value by disclosing what the payload contains (pricing, duration, credits, usage limits, trial and intro-offer flags) and by revealing the session/appointment compatibility filter behavior. It omits pagination/return-shape specifics but nothing contradicts the annotations.

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

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

Two tight sentences that front-load the resource and the returned fields before the optional filter, with no filler. The trailing REST endpoint reference is minor low-value clutter but does not hurt readability.

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, so the description usefully enumerates the returned plan attributes, partially compensating for that gap, and it covers the optional narrowing filters. For an 8-parameter read-only list tool it is largely complete, missing only pagination/response-format notes.

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 eight parameters including the enum options and defaults. The description only reinforces the session/appointment compatibility filters, which is baseline-level added value rather than new syntax or 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?

Specific verb (List) plus resource (membership plans the studio sells) and it enumerates the plan subtypes and the fields surfaced (pricing, duration, credits, usage limits, trial/intro flags). This lets an agent distinguish it from momence_list_member_memberships (a member's owned plans) without opening a schema, though it never names that 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?

It states one conditional use case – optionally narrowing to plans usable for a given session or appointment – which maps to the compatibility filters. However there is no explicit when-not guidance or named alternative for retrieving a member's existing memberships versus the studio's catalog.

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 the safe-read profile, so the bar is lower. The description adds the returned field set (booking id, member, check-in state, recurring-booking id), which is genuine extra context, but says nothing about pagination behavior or the default treatment of cancelled bookings.

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 front-loaded sentence plus a compact endpoint reference; no filler. Slight cost is that the second sentence is metadata that some agents never use, but it earns its place for API-aware callers.

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

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

With no output schema, the description usefully names the returned fields, and the schema covers pagination and sorting defaults. What remains thin is the cancelled-bookings default and any indication of result size or ordering guarantees, but nothing essential to calling 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 all six parameters (page, pageSize, sortBy, sortOrder, sessionId, includeCancelled) are already documented with defaults, ranges and enums in the schema. The description adds nothing about parameters beyond what is structured, 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), resource (bookings) and scope (one session) and enumerates the returned fields, so it reads as the class roster rather than a generic bookings list. It doesn't explicitly name the closest sibling (momence_list_member_session_bookings) to draw the contrast, so it stops short of 5.

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

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

Usage is implied by 'the class roster' for one session, but there is no explicit when-to-use guidance or statement of when to prefer momence_list_member_session_bookings / momence_list_sessions instead. The agent must infer the choice from the resource scoping.

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

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

Annotations only declare readOnlyHint=true, so safety is covered, but the description carries the rest of the burden. It usefully discloses the shape of the result (time, teacher, location, capacity, booking count), which matters because there is no output schema, yet it says nothing about pagination defaults, result limits, or whether cancelled sessions are excluded by default.

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 front-load the purpose and the returned fields, then the filter capability. The trailing 'Momence: GET /api/v2/host/sessions' adds provenance but is the one element not strictly earning its place for an agent.

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-only list tool with no output schema, the description covers purpose, filtering, and returned fields adequately, and readOnlyHint covers safety. It could go further on pagination behavior and cancelled-session defaults, but nothing essential 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 all 13 parameters including enums and defaults are already documented in the schema. The description's filter summary ('date window, type, teacher or location') mirrors the schema without adding syntax, defaults, or interaction rules (e.g. includeChildLocations only matters with locationId). 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 studio's scheduled sessions') and even enumerates what a session can be (classes, events, courses) plus the fields returned. It does not differentiate itself from siblings like momence_get_session or momence_list_session_bookings, so an agent must infer the boundary.

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 says what can be filtered ('Filter by date window, type, teacher or location'), which implies when the tool is useful, but gives no explicit when-to-use vs. alternatives and no exclusions (e.g. 'use get_session for a single session'). 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 readOnlyHint=true, so the description's job is light, and it does add the useful fact that this is a studio-scoped read whose output feeds the tag-setting tool. It does not mention pagination behavior (despite paginated params) or what the returned tag objects contain.

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 compact sentence plus the underlying endpoint. No filler, and the most decision-relevant fact (that the ids are consumed by momence_set_member_tag) comes first.

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 list tool with no output schema and fully documented params, the description covers purpose, scope, and downstream use. Adding a note on pagination or the shape of returned tags would close 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 description coverage is 100%, so the three pagination/sort parameters are fully documented in the schema. The description adds no parameter-level detail, which is the expected baseline 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 'customer tags defined for the studio', and parenthetically signals the intended consumer (ids for momence_set_member_tag), which distinguishes it from the tag-writing sibling. It does not explicitly name the sibling it differs from, but the purpose 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?

The clause 'ids for momence_set_member_tag' implies a workflow: fetch tag ids here, then apply them via the setter. That is useful implicit guidance but there is no explicit when-to-use/when-not statement and no mention of other alternatives in the ~22-tool catalog.

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 only destructiveHint=true, so the description carries most of the burden; it does disclose the POST/DELETE endpoint split and that false reverses a prior check-in, which hints at the non-idempotent undo path. It still omits permission/auth requirements, what happens if the booking is already checked in or cancelled, and error behavior for an invalid id.

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 led by the action and its two modes, followed by the id source and underlying endpoints. Every clause earns its place; nothing is repeated 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-parameter mutation tool with no output schema, the description covers the action, parameter mapping, id provenance, and API endpoints, which is enough to invoke it correctly. It falls short only on auth/permission context and failure modes, which an agent would otherwise have to discover at runtime.

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 baseline is 3, but the description adds genuinely new information: the origin of bookingId (momence_list_session_bookings), which the schema does not state. The checkedIn semantics largely restate the schema and add little beyond the boolean mapping.

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

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

Names a precise verb (check in / undo check-in) on a precise resource (session booking) and spells out the boolean-to-action mapping. The operation is unambiguous and clearly distinct from siblings like momence_cancel_session_booking, which the agent can rule out without opening either schema.

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

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

Gives clear routing context by stating that booking ids come from momence_list_session_bookings, which tells the agent which sibling to call first. It does not, however, state when to use this versus cancel_session_booking or note any preconditions (e.g. booking must not already be cancelled).

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?

Adds context beyond annotations by declaring the operation 'fully reversible' and disclosing the underlying POST/DELETE endpoints, which tells the agent the effect differs by direction. The destructiveHint=true annotation is not contradicted, since reversing a tag removal is still a data mutation, but the reversibility note is useful non-obvious context.

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; the assign/remove semantics and the tag-id dependency are front-loaded, and the endpoint note is compact. No wasted text.

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

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

For a 3-required-param toggle with no output schema and full schema coverage, the description covers effect, direction, reversibility, and where tag ids come from. Minor gaps remain around permission requirements and confirmation of the resulting state, but nothing essential 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% and each parameter already documents itself (assigned: 'true to assign the tag, false to remove it'). The description's assigned=true/false explanation duplicates the schema rather than adding syntax or constraint detail, 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 (assign/remove) and resource (customer tag on a member), with the boolean semantics spelled out inline. It is clearly distinguishable from read-only siblings like momence_list_tags and momence_get_member.

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 routes the agent to momence_list_tags for obtaining tag ids, which is real usage guidance. It lacks any when-not or edge-case exclusions, but for a simple toggle this is close to sufficient.

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 further by disclosing that a single invocation fans out into up to three sequential PUTs and that partial application is possible (partial success then stop). It still omits auth requirements and whether failed changes are rolled back.

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 dense sentences: purpose first, then mechanics. No filler, and the fail-fast caveat is placed where it matters.

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-param destructive mutation with no output schema, it covers the critical non-obvious behavior (multi-call, ordered, fail-fast). Missing only reversal semantics and the response shape on partial failure.

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 meaning beyond the schema by mapping each field to its own endpoint and stating the execution order and pairing constraint for name fields.

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') and enumerates the exact fields it can change. An agent can distinguish this update path from momence_create_member and momence_get_member without opening a schema.

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

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

Gives clear operating context: firstName+lastName must be supplied together, and the three fields are independent Momence calls executed in a fixed order that halts on first failure. It stops short of naming when to prefer an alternative tool or when not to use this one.

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