Classify member payment status

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

readOnlyHint=true already establishes this as a safe read, yet the description adds real behavioral context: the classification is derived from contracts rather than stored, the set of possible verdicts, and the non-obvious edge case that one-time setup fees do not count as proof of payment. It does not disclose auth requirements or failure behavior for an unknown clientId, so it stops 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?

Two sentences, front-loaded with the derivation and the enumeration of buckets, then the one rule that prevents a misclassification. No filler or restated boilerplate; the edge-case 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?

With no output schema, the description correctly carries the return-value burden by naming all bucket values plus join/churn lifecycle dates, and the read-only annotation covers safety. Gaps remain only around clientId semantics and what happens for a client with no contracts, which is minor given the tool's simplicity.

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

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

Schema description coverage is only 50% — siteId is documented in the schema, but clientId is bare. The description adds no parameter guidance at all (no site scoping note, no clientId format or lookup hint), so it fails to compensate for the undocumented half. Below the baseline 3 that high schema coverage would earn.

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 (buckets a client) plus the resource (payment status derived from contracts), and enumerates the exact output classes (paying | pastDue | onHold | promo | comp | none) with lifecycle dates. The 'Derived tool' framing distinguishes it from siblings like mbo_get_client_contracts, which return raw contracts rather than a classification.

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 'Derived tool' label and the explicit bucket list make the intended use case clear: call this when you want a payment classification rather than raw contract data. The rule that 'paying' requires a recurring NormalAutoPay > 0 tells the agent when the 'paying' verdict applies. However, it never explicitly names an alternative (e.g., mbo_get_client_contracts) or states when not to use it.

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