Persona MCP by usefulapi

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

Annotations only supply destructiveHint=true; the description goes further by declaring WRITE/mutates state, specifying the exact request body shape sent to the API, and naming the REST endpoint. It does not cover idempotency (what happens when the tag already exists), permission/auth requirements, or whether the tag is additive versus replacing existing tags, which keeps it short of a 5 for a destructive mutation.

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

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

Front-loaded with the operation class ("WRITE:") followed by behavior, wire format, and endpoint in four tight sentences. Every sentence carries information, though the endpoint/REST detail is marginally redundant for an agent that only needs invocation semantics.

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, fully documented, no-output-schema write tool, the description covers purpose, mutation semantics, request body, and endpoint. It stops short of describing tag-existence behavior or required permissions, which are the remaining gaps an agent might care about for a destructiveHint=true call.

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

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

Schema description coverage is 100%, so both parameters are already documented and the baseline is 3. The description earns extra credit by revealing the wire-format mapping that the schema does not: tag_name is transmitted as meta."tag-name", and account_id is path-substituted into POST /accounts/{account_id}/add-tag.

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 opens with a specific verb+resource ("adds a tag to an account") and immediately classifies it as a WRITE that mutates state. That clearly separates it from the sibling set, which is entirely persona_get_* / persona_list_* read operations, so an agent can route correctly without opening any schema.

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

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

"Tags label/segment accounts for review and automation" gives implied usage context, but there is no explicit when-to-use, when-not-to-use, or named alternative. Since the siblings are all read tools, there is arguably no competing tag-write tool, so the omission is tolerable but leaves the agent to infer intent.

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

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

readOnlyHint=true already declares the safe-read profile, so the bar is lower. The description still adds real value by disclosing the response shape (JSON:API { data }) and that it contains PII, plus the underlying REST endpoint, which signals sensitivity handling. It does not cover auth, rate limits, or not-found behavior.

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

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

One front-loaded sentence plus a compact return/endpoint clause; every element (scope, payload, PII flag, REST mapping) earns its place with no filler.

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

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

For a one-parameter read tool with no output schema, the description supplies purpose, return envelope, sensitivity (PII), and the REST analog. Only error/not-found and auth expectations are absent, which is a minor gap.

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

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

Schema coverage is 100% and the single account_id parameter is fully documented with an act_... example in the schema itself. The description adds only 'by id' with no format or validation detail 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 ('Get') and resource ('a single account by id') and clarifies the entity is the persistent identity record for an end user. 'Single' implicitly separates it from the list_accounts sibling, but the sibling is never named explicitly, so differentiation is inferred rather than stated.

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?

Context is implied by 'single account by id' versus the list_* siblings, but there is no explicit when-to-use/when-not guidance, no prerequisite or permission note, and no mention of what to do if the id is unknown. Adequate but leaves routing to inference.

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 covering the safety profile, the description adds real value: it discloses that the response is JSON:API '{ data }' and that it contains PII, plus the underlying REST endpoint. It omits auth/permission requirements, but the PII disclosure is the meaningful behavioral signal here.

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 that front-loads the verb+resource, then appends return shape and endpoint reference with no filler. 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, so the description appropriately carries part of that burden by naming the JSON:API '{ data }' envelope and flagging PII. For a one-parameter read tool this is nearly complete, 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 description coverage is 100% and the single case_id parameter is documented in the schema itself (including the case_... example). The description only restates 'by id' and adds no format or constraint detail 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 and resource ('Get a single case by id') and adds scope clarification ('a manual-review workflow item'), which distinguishes it from the sibling persona_list_cases. An agent can tell single-fetch from list 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?

The 'by id' phrasing implies the retrieval-by-identifier use case, but there is no explicit when-to-use vs persona_list_cases guidance and no stated prerequisites or exclusions. Usage is inferable rather than directed.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral context beyond that: the JSON:API { data } envelope and the warning that payloads may reference PII, which is meaningful for a read tool.

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, front-loaded sentences with no filler; the resource and identity constraint come first. The REST path is a useful orientation detail rather than padding.

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 compensates by naming the response envelope ({ data }) and flagging PII in payloads. For a one-parameter read tool with readOnlyHint annotations, this is nearly complete.

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

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

Schema coverage is 100% with a single documented event_id parameter (format evt_...). The description only restates 'by id', adding nothing 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 and resource ('Get a single audit-trail event by id') and names the returned fields (name, payload). The word 'single' implicitly distinguishes it from the persona_list_events sibling, though it does not name 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?

Usage is implied by 'single ... by id' versus the list variant, but there is no explicit statement of when to use this tool instead of persona_list_events. 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description goes further by disclosing the response envelope (JSON:API { data }) and, importantly, that the payload contains PII, which is meaningful context for handling an identity-verification record. It stops short of noting auth scope or error behavior.

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

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

Two tight sentences: the resource identification and returned contents come first, followed by the response envelope and the underlying REST endpoint. No filler, and the key information is front-loaded.

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

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

With no output schema, the description carries the return-value burden and does reasonably well, naming the {{ data }} envelope and key fields. A get-by-id tool with one documented param is nearly fully specified, though error/empty-case behavior is 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 coverage is 100% and the single inquiry_id parameter is documented in the schema with an example. The description's 'by id' adds nothing beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('a single identity-verification inquiry by id') and enumerates the returned contents (status, template, relationships). The word 'single' clearly distinguishes it from the sibling persona_list_inquiries 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?

Usage is implied by 'by id' – it is the fetch-one counterpart to the list tools – but there is no explicit when-to-use, when-not-to-use, or named alternative. No prerequisites or selection criteria 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?

Annotations already declare readOnlyHint=true, but the description adds real value beyond them: it discloses the return envelope (JSON:API { data }) and, importantly, that the payload contains PII, which affects how the agent should handle and surface results. No auth or rate-limit notes, hence not 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 tight sentence with the action front-loaded, followed by a brief clarifier on the resource type and a return/endpoint note. Every clause earns its place and there is no filler.

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

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

For a one-parameter read with readOnlyHint already set, the description covers purpose, resource semantics, return envelope, and the PII sensitivity — enough to call it correctly. Only minor gaps (no error/not-found behavior) keep it from a 5.

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?

With a single parameter at 100% schema description coverage (including the 'report_...' format hint), the schema carries the semantics. The description adds only 'by id', so the baseline of 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 (get) and resource (a single report by id), and clarifies what a report actually is — a screening/monitoring result covering watchlist, adverse-media, and business lookup. The word 'single' implicitly distinguishes it from the sibling persona_list_reports.

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: call it when you already have a report_id and want one report. There is no explicit when-to-use/when-not guidance and no named alternative (e.g. persona_list_reports for discovery), so the agent must infer the boundary itself.

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, and the description builds on that by disclosing the return envelope (JSON:API { data }) and, importantly, that the response contains PII, plus the underlying REST route. That PII warning is meaningful context an agent would not get from the annotation alone.

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 clauses, front-loaded with the core action and free of filler. The trailing REST route restates the operation already evident from the name and schema, so it is mildly redundant 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?

With no output schema, the description carries the return-value burden and does so — it names the envelope and flags PII. For a one-parameter read tool whose annotations already cover safety, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% with a single required parameter documented with an example (txn_...), so the baseline is 3. The description adds only the REST path shape GET /transactions/{transaction_id}, which reinforces but does not meaningfully extend 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 ('Get a single transaction by id'), defines what a transaction is ('a record submitted for transaction fraud/monitoring analysis'), and the word 'single' plus 'by id' distinguishes it from the sibling persona_list_transactions. An agent can pick this over the other get_*/list_* siblings by resource alone.

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 — retrieve one transaction when you have its id, versus listing many — but the description never names an alternative or an explicit when-not condition. It leaves the list-vs-get routing to inference rather than stating it.

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, but the description adds real value beyond annotations: it discloses that the response contains check results and PII (a sensitivity warning an agent should have), gives the response envelope (JSON:API { data }), and maps to the underlying REST endpoint GET /verifications/{verification_id}. It stops short of any error, auth, or rate-limit behavior.

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

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

Two tight sentences: the first front-loads what is fetched and what the entity means, the second states the return shape and REST mapping. No filler words and nothing redundant.

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

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

With no output schema, the description compensates by naming the return shape ({ data } with check results and PII), so an agent knows what comes back. Given a single required string param and readOnly annotations, nothing essential is missing — only error/miss behavior is 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?

Only one parameter and schema description coverage is 100%, so the schema already documents verification_id as a string with the ver_... prefix example. The description confirms lookup 'by id' but adds no format, constraint, or validation meaning beyond the schema; 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 (a single verification by id), and goes further by defining what a verification is — 'one identity check within an inquiry' with concrete examples (government-id, selfie, database, document). This clearly separates it from the list_* siblings, though it does not explicitly name any 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 identity check within an inquiry' implies the retrieval happens after an inquiry exists, but there is no explicit when-to-use statement, no when-not-to-use, and no pointer to an alternative among the many persona_get_* 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 only declare readOnlyHint=true, so safety is covered; the description adds real context beyond that: the JSON:API response shape ({data, links}), the fact that returned objects contain PII, and the underlying REST route GET /accounts. It does not cover auth requirements or rate limits, but the PII disclosure is a meaningful behavioral note.

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 with no filler: first the operation identity, then filtering/pagination, then return shape and the REST mapping. Information is front-loaded and each sentence carries payload, though the parenthetical definition of 'account' briefly delays the actionable content.

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 describes the return envelope ({data:[...], links}) and warns about PII, which the structured fields cannot convey. Filtering and pagination are both addressed, leaving only minor gaps like ordering and auth requirements for a read-only 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%, so the schema already documents all four parameters including the page_after/page_before cursors and reference_id. The description restates the cursor mechanics (links.next/links.prev) but adds no syntax or format detail beyond the schema, 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+resource ('List accounts') and goes further by defining what an account is (persistent identity record linking inquiries/verifications), which helps distinguish it from persona_list_inquiries or persona_list_verifications. It does not explicitly name the sibling to use for a single record (persona_get_account), so it stops short of full differentiation.

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

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

Provides implied usage context by noting the optional reference_id filter and cursor pagination, but never states when to choose this over persona_get_account or the other list_* siblings. An agent must infer that this is the collection-level counterpart to get_account.

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 cover readOnlyHint, so the description carries the rest of the burden and does well: it discloses the response envelope (JSON:API { data, links }), warns that returned objects contain PII, and explains the cursor pagination mechanism. It stops short of stating rate limits, default page size, or result caps.

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 definition of a case and ending with the underlying REST endpoint. Slightly dense with the filter enumeration, but no sentence is wasted.

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 describing the return envelope, the PII sensitivity, and the cursor semantics, plus the REST path. For a 9-param filtering list tool this is nearly complete; only pagination defaults and result limits are 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 nine parameters are already documented, giving a baseline of 3. The description's main added value is linking the page_after/page_before params to the response's links.next/links.prev cursors, but the rest of the filter list simply restates 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 cases') and then defines what a case actually is ('manual-review workflow items grouping inquiries/reports for an analyst to adjudicate'), which is the key disambiguator against siblings like persona_list_inquiries and persona_list_reports. An agent can tell what this returns 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?

The description frames the tool as a filtered collection read by enumerating the optional filters, which implies when to use it. However, it never contrasts with alternatives (e.g. persona_get_case for a single case, or the sibling list tools) or states when not to use it, so guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, but the description adds real value beyond that: the log is immutable, pagination is cursor-based via JSON:API links, and payloads 'may reference PII'. It stops short of describing auth/permission requirements or rate limits, but the sensitivity warning and pagination mechanics are substantive.

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

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

Four dense sentences with no filler; the purpose leads, then pagination, then return shape and sensitivity, then the REST endpoint. Tight, though the trailing 'GET /events' line is the least load-bearing element.

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 compensates by describing the JSON:API { data, links } return shape and the PII caveat. With all three optional params covered by the schema, an agent has everything needed to call and paginate this read-only endpoint correctly.

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

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

Schema description coverage is 100%, so the baseline would be 3, but the description adds the wiring that the schema lacks: page_after corresponds to links.next and page_before to links.prev, telling the agent how to obtain and use those cursors. That is meaningfully more than the parameter docs alone.

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 audit-trail events') and immediately defines the resource in operational terms ('an immutable log of actions ... inquiry/account/case state changes'), which unambiguously separates it from the sibling persona_get_event (single record) and from the other persona_list_* tools.

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 operational guidance on how to page (follow links.next/links.prev) but never states when to choose this over persona_get_event or another listing tool, nor any prerequisites. Usage is implied by the description rather than spelled out.

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 genuinely useful behavioral context beyond that: the JSON:API return envelope ({ data:[...], links }), the fact that returned objects contain PII, and the mapping of page_after/page_before to links.next/links.prev. It does not mention rate limits or default page size, 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 tightly packed sentences ordered purpose → filters/pagination → return shape and endpoint. Nothing is redundant with the schema and nothing is wasted; the most decision-relevant facts come 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?

With no output schema, the description correctly takes on the burden of describing the return envelope and the PII sensitivity, and it covers filtering and cursor pagination for all 9 optional parameters. An agent has everything needed to construct a correct call.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema — the baseline is 3. The description enumerates the same filter set and adds a modest framing (cursor follows links.next/links.prev), but contributes no syntax, format, or semantics beyond what the schema states.

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 gives a specific verb+resource ('List identity-verification inquiries') and then defines the domain object in plain terms ('an end-user's KYC verification session'), which no sibling name conveys. It also anchors to the underlying REST operation (GET /inquiries), letting an agent distinguish it from persona_get_inquiry and the other list_* 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?

It names the optional filter dimensions and the pagination mechanism, which implies the intended usage pattern, but never states when to choose this tool over alternatives (e.g., persona_list_events or persona_get_inquiry) or any exclusions. Usage is inferred from the filter list 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?

With readOnlyHint already declared, the description adds real value beyond annotations: the JSON:API pagination model (links.next/links.prev), the response envelope shape, and an explicit PII caveat. It omits auth/permission requirements and result-size limits, so it is strong but not exhaustive.

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 purpose before pagination detail and the return-shape/PII note. Every clause carries distinct information with no filler.

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

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

For a read-only list tool with no output schema, the description covers purpose, pagination cursor mechanics, response envelope, and the PII caution, which is nearly everything an agent needs. Auth scope and default page size are not addressed, but the essentials are present.

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 three parameters are already documented in the schema, including the cursor-to-links mapping. The description restates that mapping but adds no new syntax or constraints, so the baseline 3 applies.

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

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

States a specific verb and resource ('List reports') and clarifies the resource with concrete examples (watchlist, adverse-media, business lookups), which meaningfully distinguishes it from persona_get_report. It does not, however, explicitly name a sibling or contrast singular vs. list semantics, so it stops short of full sibling differentiation.

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

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

Usage is implied by the resource description and the pagination note, so an agent can infer this is a browse/paginate operation. There is no explicit when-to-use vs. an alternative (e.g., 'use persona_get_report when you already have an id'), nor any exclusions.

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 establish readOnlyHint=true, so the safety profile is covered; the description adds genuinely non-obvious context beyond that — the return envelope is JSON:API {data:[...], links}, cursors come from links.next/links.prev, and returned objects may contain PII. It does not state rate limits or auth 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?

Three dense, front-loaded sentences: purpose, filtering/pagination, then return shape and sensitivity. Every clause carries information, though the trailing REST endpoint notation is somewhat redundant given the tool name and adds slight clutter.

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 discloses the return envelope, cursor mechanism, and PII exposure, and all five parameters are documented. It stops short of describing error behavior or empty-result semantics, but nothing essential for a correct call is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value by mapping page_after to links.next and page_before to links.prev, telling the agent how to obtain the cursor values rather than just what they mean. It does not elaborate on page_size bounds or filter value formats.

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) plus resource (transactions) and even defines what a transaction record is — 'records submitted for transaction fraud/monitoring analysis'. It also grounds the tool in the Persona REST API (GET /transactions), which clearly separates it from the sibling persona_get_transaction.

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 two optional filter axes (reference_id, transaction_type_id) and how pagination is meant to be driven from JSON:API links. It gives clear operating context but never states when to prefer this over persona_get_transaction or what to do when a filter returns nothing, so no explicit exclusions.

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