MoonClerk MCP by usefulapi

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

Annotations already cover readOnly/non-destructive/openWorld, so the description adds value by disclosing the negative guarantee that the payer's management link and checkout token are never returned — a real privacy behavior. It stops short of describing error/not-found behavior, keeping it from 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?

Front-loaded with the resource and id, followed by return contents, the privacy exclusion, and the endpoint. It's dense but every clause earns its place; the long parenthetical field list is the only slight readability cost.

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 shoulders the burden of describing return contents and does so (subscription, payment method, discount, amounts, custom fields) plus what is excluded. Only failure modes (invalid/missing id) are unaddressed.

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

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

Schema description coverage is 100% and the single customer_id parameter is already documented in the schema, including its source (moonclerk_list_customers). The description only restates 'by id', 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 (get) and resource (one MoonClerk customer/plan) scoped by id, and enumerates the payload it returns, which cleanly separates it from moonclerk_list_customers. An agent can distinguish it from all 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?

'By id' plus the GET /customers/{id} endpoint makes the retrieval pattern explicit, and read-only tells the agent this is a safe fetch. It doesn't explicitly state when to prefer it over moonclerk_list_customers, though the schema's id hint partially bridges that gap.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by stating the GET endpoint and summarizing returned fields, though it repeats "Read-only" rather than adding new safety details.

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

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

The description is three short fragments with no wasted words, and the core lookup behavior plus returned fields are front-loaded. It is appropriately sized for a simple get-by-id 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?

Given the simple one-parameter schema, rich annotations, and no output schema, the description provides enough context: it states the lookup scope, read-only nature, endpoint, and key returned fields. Nothing essential 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?

Schema description coverage is 100% for the single form_id parameter, and the schema explains that the id comes from moonclerk_list_forms. The description says "by id" but adds no format or validation meaning 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 and resource: retrieve one payment form by id. It also scopes the result to a single form and lists the key returned fields, which clearly distinguishes it from the list_forms sibling.

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

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

The phrase "One payment form by id" implies the tool is for single-record lookup, but it does not explicitly state when to use this versus moonclerk_list_forms or other siblings. The schema mentions getting the id from moonclerk_list_forms, but the description itself provides only 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?

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered; the description still adds real value by disclosing that 'The checkout token is never returned' (a data-omission guarantee an agent cannot derive from annotations) and by specifying that amounts are in cents. It stops short of covering auth needs or error behavior for unknown ids.

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 the endpoint, all front-loaded: identity and scope first, then field inventory, then the negative guarantee. The field list is long but earns its place because there is no output schema.

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 compensates by enumerating the returned fields and noting the excluded checkout token, so an agent can plan on the response shape. It does not describe behavior for a nonexistent or invalid payment_id or any pagination/expansion options, which is 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?

Only one parameter and schema description coverage is 100%, with the schema itself noting the id comes from moonclerk_list_payments. The description adds nothing beyond 'by id', so the baseline 3 is appropriate — the schema does all the semantic work.

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

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

The description names the specific resource and scope ('One MoonClerk payment by id') and makes the retrieval verb explicit with 'GET /payments/{id}', which clearly separates it from the sibling list_payments. It also enumerates the payload fields, so an agent knows exactly what it gets back.

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 singular 'by id' scope signals this is the single-record fetch versus moonclerk_list_payments, but the description never states when to choose it or when not to. There are no explicit alternatives or prerequisites in the description text itself (the sibling pointer lives only in the schema's parameter description).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, and the description reinforces with 'Read-only. GET /customers.' It adds value the annotations cannot: exactly what fields come back and an explicit exclusion ('management link and checkout token are never returned'), which tells the agent what data is unavailable downstream.

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 the identity of the resource and the 'Plans' alias, then filters, then exclusions and HTTP verb. The middle enumeration of returned fields is dense but each element carries information; only the list is slightly long for a single sentence.

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 must carry the return shape, and it does: subscription status, amount and interval, next payment, trial/cancel dates, payment method, coupon, custom fields, and originating form. Pagination semantics live in the schema's offset/next_offset text, so nothing material 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 baseline is 3. The description earns slightly more by restating the status enum inline and by glossing the date filters as sign-up date range and next-payment date range with worked examples, mapping the schema's 'checkout_from/to' naming onto the user-facing concept.

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 and immediately disambiguates the domain vocabulary ('customers, which the MoonClerk web app calls "Plans"'), then enumerates the per-record contents. This makes it clearly distinguishable from the singular moonclerk_get_customer sibling.

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

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

Gives concrete usage scenarios ('past_due plans or renewals due this month') and lists the available filter axes, so an agent knows what contexts this fits. It does not explicitly say when to prefer a sibling such as moonclerk_get_customer for a single payer, so it stops short of full routing guidance.

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

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

The 'Read-only' line just restates readOnlyHint and earns no credit, but because there is no output schema, enumerating the returned fields is genuine behavioral disclosure that the agent could not get from structured data. It still omits page-size defaults in practice (deferred to schema) and any note on total/next_offset presence in the response.

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?

Tight and front-loaded: the resource and return fields come first, then the cross-tool hint. Minor waste in 'Read-only' (already an annotation) and 'GET /forms' (implementation detail), but no sentence is bulk.

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

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

For a two-parameter read-only list with no output schema, the description covers resource, return shape, and downstream id usage, while annotations carry the safety profile and the schema carries pagination. The only remaining gap is response envelope detail (whether a total or next_offset is returned).

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

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

Schema description coverage is 100%, and the schema already explains count range/default and that next_offset from the prior reply drives offset. The description adds nothing about either parameter, 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?

Specific verb + resource ('List the MoonClerk payment forms') plus the exact fields returned (id, title, currency, payment_volume, successful_checkout_count, timestamps). The singular sibling moonclerk_get_form and the other list_* siblings are separable purely on resource/verb, so no ambiguity remains.

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 downstream guidance ('Use the form ids to filter customers (plans) and payments'), which implies when the tool is useful, but never states when to prefer it over moonclerk_get_form or the other list tools, and offers no exclusions or prerequisites.

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 destructiveHint=false, so safety is covered; the description adds useful substance by confirming cents as the unit, naming the underlying endpoint (GET /payments), and disclosing that Stripe fee and refund amounts are returned. 'Read-only' mildly duplicates the annotation rather than extending it.

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

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

Front-loaded with purpose and return fields, then filters, then unit and safety notes. The return-field enumeration is long but pays for itself given there is no output schema; a couple of clauses (safety restatement) are redundant with annotations.

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 return-shape burden and does so thoroughly, including fee/refund units and recurring-only customer id. Pagination behavior is not mentioned in the description, though the offset parameter description covers next_offset chaining.

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 every parameter is already documented, and the description mainly restates the filter dimensions (form, customer, status, charge-date range) without adding format or interaction detail. The 'amounts are in cents' note adds value but pertains to output, not parameters. 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?

States a specific verb and resource ('List MoonClerk payments (charges)') and immediately enumerates the returned fields, which distinguishes it clearly from the singular get_payment sibling. An agent knows this is the enumeration tool, not the single-record lookup.

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?

Supplies concrete filter scenarios ('failed payments this month or refunds for one plan') that map directly onto status/date/form parameters. It does not explicitly say when to prefer get_payment or list_customers instead, so it falls short of full alternative routing.

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