roi_patterns

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that — the rule that only subjects with a fully elapsed evidence window are listed, so young customers are never flagged, plus the shape of each entry. It does not mention result size limits or ordering, 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?

Front-loads the resource description, then the enum glosses, then the eligibility caveat in three tight sentences with no filler. The inline pattern definitions are dense but every clause carries semantic weight.

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

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

For a one-parameter read with no output schema, the description covers the enum meanings, the eligibility rule, and the per-entry fields (subject plus detail amounts in minor units). Only result limits/pagination are unaddressed, 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 0% and the schema only lists bare enum strings, so the description carries the full semantic load — it defines what each of the four patterns actually detects, which is the single most important fact for selecting the right call. It also clarifies that amounts are in minor units.

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

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

States a specific resource ('Customers or partners matching a named credit-ROI pattern') and then defines every enum value in plain language, so an agent knows exactly what is being retrieved. It does not explicitly contrast with roi_summary or roi_trace, leaving sibling differentiation implicit.

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

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

Usage is only implied: the description explains what each pattern means, which hints at when an agent would pick one, but gives no explicit when-to-use, when-not-to-use, or pointer to alternatives like roi_summary, roi_trace, or list_fraud_cases.

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