persona

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

Annotations only declare destructiveHint=true, so the description carries much of the burden; it adds the mutation nature, the exact JSON body shape, and the underlying REST endpoint POST /accounts/{account_id}/add-tag. It does not cover reversibility, auth requirements, or rate limits, which leaves a modest gap for a mutation 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?

Three tight sentences, front-loaded with the WRITE marker, each carrying distinct information (effect, purpose, payload/endpoint). 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?

No output schema exists and none is needed for a tag-add; the description supplies payload format, transport, and mutation semantics. Minor gaps remain around auth and error behavior, but a caller has enough to invoke it 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 coverage is 100%, so baseline is 3; the description adds value beyond the schema by mapping tag_name to the wire key {'tag-name': <tag_name>}, information the schema does not provide.

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 ('adds a tag to an account') plus the state effect ('mutates state'). This is unambiguously distinct from every sibling, which is a read/list operation.

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 what tags are for ('label/segment accounts for review and automation'), which implies when tagging is relevant, but gives no explicit when-to-use, prerequisites (permissions), or when-not-to-tag 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?

readOnlyHint=true already covers the safety profile, so the description's added value is real: it discloses that the payload is JSON:API '{ data }' and that it contains PII, which is behaviorally important for an agent handling the response (e.g. avoiding unnecessary logging). It stops short of covering auth requirements, 404 behavior, or rate limits.

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 sentence plus a short REST mapping, with the purpose front-loaded before the endpoint detail. Efficient; the endpoint hint is marginal but useful for cross-referencing, so not quite a 5.

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 single-parameter read tool with no output schema, the description supplies the essential missing piece — that the response is JSON:API with a data envelope containing PII. Auth/permission requirements and error semantics remain unstated, keeping it below 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?

Schema coverage is 100% with a single, fully documented account_id parameter, so the schema carries the semantics. The description only restates the by-id lookup and adds no format or prefix detail beyond the schema's 'act_...' example — baseline 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?

States a specific verb and resource ('Get a single account by id'), then clarifies the domain meaning ('the persistent identity record for an end user') and names the underlying REST route. This cleanly separates it from persona_list_accounts without the reader needing to open 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?

The phrase 'a single account by id' implies the usage context (retrieve one record when you already have its id), but it never states when to prefer this over persona_list_accounts or what to do if the id is unknown. Implied usage only, 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, but the description adds real value beyond them: it warns the response contains PII and specifies the return envelope (JSON:API { data }). It does not cover behavior when the id is unknown, but the safety and sensitivity profile is well disclosed.

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 compact clauses, front-loaded with the operation, followed by the data-sensitivity note and the underlying REST endpoint. No sentence is redundant and nothing important is 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?

For a single-parameter read tool with readOnlyHint and no output schema, the description covers purpose, return shape, and the PII caveat, which is enough to call it correctly. Only minor gaps remain, such as not-found behavior and routing versus persona_list_cases.

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 case_id already documented with a 'case_...' example, so the schema does the heavy lifting. The description only says 'by id' and adds no format or constraint detail beyond the schema, 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 ('Get a single case by id') and clarifies what a case is ('a manual-review workflow item'). The word 'single' implicitly separates it from the persona_list_cases sibling, so an agent can distinguish the two 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?

Usage is only implied: an agent with a case_id wanting one case can infer this is the tool. There is no explicit when-to-use guidance, no mention of persona_list_cases as the alternative for enumerating cases, and no stated prerequisites or 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 declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the response is JSON:API { data } and payloads may contain PII, plus the underlying REST route for cross-referencing. It stops short of noting auth requirements 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?

Two tight sentences with the core purpose front-loaded and no redundant restatement of the title. The trailing REST path clause is marginal but serves as a useful cross-reference, not 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?

For a single-record read with no output schema, the description does the needed work: it sketches the return shape ({ data }) and flags PII sensitivity. Missing only minor operational details such as error/not-found behavior.

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 the schema already documents it at 100% coverage, including the 'evt_...' example, so the baseline is 3. The description restates the id concept without adding format, validation, or lookup constraints 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 ('Get a single audit-trail event by id') and pins the scope to one record, which implicitly but clearly separates it from the sibling persona_list_events. An agent can tell what it retrieves 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 'single ... by id' and the required event_id, so an agent can infer it is the lookup path vs. persona_list_events for browsing. However, no explicit when-to-use/when-not guidance or named alternative is 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 only declare readOnlyHint, so the description adds real value: it discloses that the response is a JSON:API { data } envelope, that it contains PII, and which relationships are embedded. It does not cover permission scoping or error behavior for a missing/invalid inquiry_id, which keeps 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 operation and scope, then return shape, then the underlying REST endpoint. No filler and nothing repeated from the 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?

For a read-only single-resource fetch with no output schema, the description covers the return payload shape, PII caveat, and included relationships. An agent has everything needed to call it and interpret the result.

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 inquiry_id parameter is documented with its format in the schema, so the description adds nothing beyond restating 'by id'. Baseline 3 applies 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 (Get) and resource (a single identity-verification inquiry) plus the lookup key (by id), which cleanly separates it from the sibling persona_list_inquiries. It also names returned fields (status, template, relationships), so an agent can identify the tool 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 'by id' framing implies direct lookup when the identifier is known, but there is no explicit when-to-use statement, no prerequisites, and no named alternative such as persona_list_inquiries for discovery. The agent must infer routing entirely.

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 goes beyond that by disclosing that the payload contains PII and that responses are JSON:API { data } shaped, plus the underlying REST path. It omits permission requirements and rate-limit behavior, but for a read-only getter 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?

One dense sentence that leads with the action and resource, then layers in the result type, the PII caveat, and the REST mapping. No filler, and the most important 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 does the work of describing the return shape (JSON:API data envelope) and its sensitivity (PII), which is exactly what an agent needs. Auth requirements and error conditions remain unstated, a minor gap for a simple read 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 coverage is 100% for the single report_id parameter, and the description's 'report_...' hint merely echoes the schema's own example. No additional meaning about id provenance or format is provided, so the schema 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?

The description states a specific verb ('Get'), the resource ('a single report by id'), and even defines what a report is ('screening/monitoring result, e.g. watchlist, adverse-media, business lookup'). It implies the single-vs-list split with persona_list_reports but never names that sibling, 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?

Usage is only implied: it presupposes the caller already has a report_id. There is no explicit when-to-use/when-not guidance and no reference to persona_list_reports as the way to discover ids, leaving the agent to infer the routing.

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 adds real value beyond that: it discloses the return envelope (JSON:API { data }), warns the payload contains PII, and maps to the underlying REST verb/path. It does not describe not-found/error behavior, which keeps 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?

Two tight sentences with zero filler: identity and scope first, then return shape, PII warning, and REST mapping. 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?

With no output schema, the description usefully covers the return format and PII content, and the single required param is schema-documented. Only the error/not-found path is unaddressed, a minor gap for a simple read-by-id 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% and the single parameter already documents the 'txn_...' format, so the schema carries the load. The description adds no syntax or constraint detail beyond what the schema provides, making 3 the correct 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 (get), resource (transaction), and scope (single, by id), then clarifies what a transaction record is ('submitted for transaction fraud/monitoring analysis'). The word 'single' implicitly differentiates it from the sibling persona_list_transactions, but it never names that alternative 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 only implied by 'by id' — the agent can infer this is the retrieval-by-identifier path versus the list tool, but no when-to-use, when-not-to-use, or alternative is stated. Adequate minimum, not explicit 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=true, so the safety profile is covered; the description adds real value beyond that by warning the response contains PII and describing the JSON:API { data } envelope plus the underlying REST route. It does not cover error behavior, but for an annotated read tool this is solid 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?

Front-loaded with the core verb/resource/scope, then return shape, then endpoint mapping in a compact span with no filler. The REST route notation is slightly machine-facing but costs little.

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?

No output schema exists, so the description must carry return-value information — and it does, naming the JSON:API shape and the presence of check results and PII. The single parameter is fully documented, leaving only minor gaps such as auth or error semantics.

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 there is only one parameter, so the schema already documents verification_id fully; the description's 'ver_...' hint duplicates the schema example. Baseline 3 is appropriate since nothing new is added.

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 (verification by id), and scopes it precisely as 'one identity check within an inquiry', then enumerates concrete check types (government-id, selfie, database, document). The parent/child relationship to an inquiry implicitly distinguishes it from persona_get_inquiry, 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 description says what it fetches but never states when to call this instead of the sibling getters (persona_get_inquiry, persona_get_report), nor any prerequisite for having a verification id. Usage is only implied by the parameter.

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 non-obvious context: the return envelope is JSON:API { data:[...], links } and the objects contain PII, which is a meaningful handling caution. No rate limits or auth scope details, so 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?

A dense but front-loaded passage: the entity definition comes first, then filtering, pagination, and return shape. No filler sentences. The trailing "Persona REST: GET /accounts" is marginally redundant but useful for endpoint mapping.

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 present, the description steps in to describe the return envelope ({ data, links }) and flags PII exposure. Combined with the entity definition and pagination mechanics, an agent has everything needed to call it 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 coverage is 100%, so the schema already documents all four parameters including the page_after/page_before cursor semantics. The description reinforces the cursor mechanic (follow links.next/links.prev) but adds no syntax beyond the schema. 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+resource ("List accounts") and parenthetically defines what an account is — a persistent identity record linking inquiries/verifications. This distinguishes it from get_account (single fetch) and the other list_* tools by resource. It stops short of explicitly naming a sibling alternative, so it lands at 4 rather than 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?

Gives clear operational context: reference_id is an optional filter, and pagination is driven by the JSON:API links.next/links.prev cursors. It does not state when-not to use it or point to alternative siblings, but the usage context is unambiguous for a list tool.

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 by structured data. The description adds real value beyond that: it discloses the JSON:API envelope shape ({ data, links }), that returned objects contain PII, and that pagination must follow links.next/links.prev into page_after/page_before. It stops short of stating rate limits or result-scoping/permissions.

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, front-loaded with the resource definition before the filter/pagination mechanics. Every clause carries information, though the filter enumeration is a long mid-sentence list that mildly blurs the read.

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, zero-required list tool with no output schema, the description covers return shape, PII risk, and cursor-based pagination — the things an agent most needs. It omits default page_size behavior and whether results are scoped by account/permission context.

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 would be 3. The description rises above it by tying the pagination parameters to the response's links.next/links.prev cursors, explaining how to obtain a cursor rather than just what it does, and by grouping the filter set into a coherent list.

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 (cases), then defines what a case actually is — "manual-review workflow items grouping inquiries/reports for an analyst to adjudicate" — which is domain knowledge an agent cannot derive from the name. That definition also implicitly separates it from the persona_list_inquiries/reports siblings, since cases are the grouping layer over them.

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 enumerates the available filters and cursor parameters, which implies the intended usage (narrow a case set, then page through it). However, it never says when to reach for this tool versus persona_get_case (single case lookup) or the other persona_list_* tools, and states 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?

readOnlyHint=true already signals a safe read, but the description adds real context: the log is immutable, the response is JSON:API shaped, and payloads may reference PII. That PII and immutability detail is the kind of disclosure annotations do not provide. It stops short of noting rate limits or default page sizes.

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 tight sentences front-loaded with purpose, then pagination mechanics, return shape, and the REST equivalent. Nothing is padding; each sentence carries distinct 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?

With no output schema, the description usefully discloses the JSON:API { data, links } return shape and the PII caveat, plus the pagination model. An agent has everything needed to call and consume this 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 coverage is 100%, so the three pagination params are already documented, including the links.next/links.prev relationship. The description reinforces how page_after/page_before map to the response cursor links, which is mildly additive but largely repeats the schema, so the baseline 3 holds.

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 defines the scope with a parenthetical (immutable log of actions — inquiry/account/case state changes). This reads clearly against the singular sibling persona_get_event by implying a collection listing.

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 explains how to paginate but never states when to reach for this list versus persona_get_event or the other list_* siblings. Usage is only implied by the tool's obvious listing nature, leaving no explicit selection criteria.

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 behavior: the response is JSON:API { data, links }, pagination flows through links.next/links.prev cursors, and the returned objects contain PII — none of which the annotations or schema convey.

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 plus an endpoint reference; the resource definition is front-loaded and the PII caveat is placed with the return shape. Slightly dense with filter enumeration that duplicates the schema, but nothing 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 usefully explains the JSON:API return shape and cursor pagination, and flags PII. It is complete enough for a read-only list tool, though it says nothing about auth requirements, rate limits, or default page size.

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, and the description merely enumerates the filter set. It adds only the mapping of page_after/page_before to the links.next/links.prev cursors, which the schema partly states already. 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 (List) and resource (identity-verification inquiries), and immediately glosses the domain term as "an end-user's KYC verification session" plus the underlying REST endpoint. An agent can distinguish it from the singular persona_get_inquiry and the other persona_list_* siblings 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?

Usage is implied by the name and the mention of optional filters, but there is no explicit when-to-use or when-not-to-use guidance — e.g. nothing says to prefer persona_get_inquiry when you already have an inquiry id, or that this is the discovery path for the other persona_get_* tools.

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 the description carries the rest — and it does add real value: the JSON:API { data:[...], links } return shape, the PII warning on returned objects, and the cursor-following pagination contract. It omits auth requirements and rate limits, but for a read-only list endpoint this is solid disclosure beyond the annotation.

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 with the core purpose front-loaded, then pagination, then return shape. The trailing REST endpoint note ('Persona REST: GET /reports') is oriented toward implementers rather than the agent choosing the tool, which is the only near-redundant 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?

With no output schema and only a readOnlyHint annotation, the description steps in to describe the return envelope, the PII sensitivity, and the pagination loop — enough for an agent to call and traverse results correctly. Missing only complementary detail such as ordering or filtering behavior.

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 each cursor parameter ('return the page AFTER this record id (follow the links.next cursor)'). The description largely restates that links.next maps to page_after and links.prev to page_before, adding convenience but no new meaning, 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 immediately defines what a report is in this API (screening/monitoring results such as watchlist, adverse-media, or business lookups), which is knowledge the agent cannot infer from the name alone. It also pins the operation to the Persona REST surface (GET /reports), so it is distinguishable from the get_* 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?

The pagination instruction ('paginate via links.next cursor') gives operational guidance, which implies this is the bulk-retrieval tool. However, it never states when to use this versus persona_get_report (known ID) or the other list_* siblings, and gives no prerequisites or 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 declare readOnlyHint=true, so safety is covered; the description goes further by disclosing the JSON:API response shape ({ data, links }), the cursor pagination model, and a PII warning on returned objects. That is meaningful context beyond the structured fields. It stops short of describing default page sizes or rate limits.

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 verb+resource, then filters, pagination, return shape, and a PII caveat in a compact package with no filler. The single dense sentence is slightly overloaded but 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?

With no output schema, the description compensates by explaining the return shape, cursor pagination, filterable fields, the underlying endpoint, and a PII caveat. For a read-only list tool, an agent has everything needed to call it 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 every parameter is already documented in the schema, including the page_after/page_before cursor semantics and the two filters. The description largely restates links.next/links.prev already present in the schema, so it meets the baseline rather than adding new meaning.

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 (transactions), and even defines what a transaction is ('records submitted for transaction fraud/monitoring analysis') plus the underlying REST endpoint. It does not explicitly differentiate from sibling persona_get_transaction, though list-vs-get is inferable from the name.

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 by naming the optional filters (reference_id, transaction_type_id) and the pagination mechanism, but never states when to prefer this over persona_get_transaction or how pagination should be driven across pages. No exclusions or alternatives are given.

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