Onfido MCP by usefulapi

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

Annotations are sparse (only destructiveHint=true), so the description adds genuine value by disclosing that no verification check runs and no cost is incurred, plus that the record holds PII. It does not state persistence/reversibility or whether creation is idempotent, which leaves some mutation behavior unstated.

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 short sentences, front-loaded with the verb and resource, followed by the endpoint and the key behavioral caveat. No filler or repetition of schema 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?

For an 8-parameter write tool with nested objects and no output schema, the description covers the workflow-critical facts (PII-only, no check, no cost). It omits what the call returns (e.g., the applicant ID needed to trigger a subsequent check), which is a minor gap given no output schema exists to carry it.

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% — every parameter, including nested address/location/id_numbers, is documented in the schema, so the baseline is 3. The description adds no parameter-level syntax or format guidance beyond what the schema already carries.

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 ('Creates an applicant (person) record in Onfido') and even maps it to the underlying API endpoint (POST /applicants). It clearly distinguishes this from the get/list/update siblings, which are all reads or mutations of existing applicants.

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 real selection context: 'Creates a PII record only — runs NO verification check and costs nothing,' which tells the agent this is a prerequisite step and that a check/workflow tool must be called separately. It does not explicitly name the follow-up sibling to use, so it stops short of full when-to-use 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 the safety profile is covered. The description adds the useful detail that this maps to GET /applicants/{applicant_id}, but says nothing about what happens on a missing/invalid id (error shape) or whether the response is cached. Adequate but thin for a read tool whose annotations already carry the main signal.

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 sentences, zero filler, with the core action front-loaded before the API 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?

There is no output schema, so the description ideally would hint at what an applicant record contains (e.g., status, PII fields), and it does not. For a trivial get-by-id tool the gap is minor, but the description is thinner than the full burden requires when no output schema exists.

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 coverage is 100% ('The applicant id.'), so the structured data already documents it fully. The description adds no format, source, or retrieval hint for the id beyond the name, 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 ('Retrieve') and resource ('a single applicant record by id'), and the word 'single' implicitly separates it from the sibling onfido_list_applicants. It stops short of naming competitors like onfido_get_check or onfido_get_report, but the resource is unambiguous.

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 id' suggests you must already hold an applicant id, which distinguishes it from the list/search-style siblings. No explicit when-to-use, prerequisites, or exclusion against onfido_get_check / onfido_get_workflow_run 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 already declare readOnlyHint=true, so the safety profile is covered; the description adds real value beyond that by disclosing the returned payload shape (status, report ids, result) and mapping to the underlying REST call GET /checks/{check_id}. It stops short of mentioning error behavior for unknown ids, but for a read-only fetch that is minor.

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 sentences, zero filler, with the purpose front-loaded and the endpoint mapping appended as a compact reference. 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?

No output schema exists, but the parenthetical list of returned fields (status + report ids + result) partially compensates by telling the agent what to expect back. Combined with the read-only annotation and the fully documented single parameter, this is nearly complete, missing only 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?

There is a single parameter and schema description coverage is 100%, so the schema already documents check_id fully. The phrase 'by id' adds no syntax, format, or constraint detail beyond that, making the baseline 3 the correct score.

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 ('Retrieve a single check ... by id') and pins the scope to one record via 'single', which contrasts with the sibling onfido_list_checks. The parenthetical enumerates the returned fields, making the tool's job unambiguous, though it never names the 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 only implied: 'by id' signals you must already hold a check id, and 'single' implies this is the lookup path versus onfido_list_checks. There is no explicit when-to-use, when-not-to-use, or prerequisite statement, so the agent must infer the routing from the name.

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 usefully sharpens this by saying only 'metadata' is returned (not the document image itself) and maps to the concrete endpoint, but says nothing about error behavior for invalid ids or what the metadata contains.

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 with zero padding; the purpose is front-loaded and the endpoint detail follows as supporting context.

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 trivial one-parameter read tool with the safety profile already in annotations and no output schema, the definition is close to complete. The modest gap is that no output schema exists, so the description could say a bit more about what 'metadata' comprises.

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 single document_id parameter is already documented in the schema. The description adds no format, provenance, or sourcing guidance for the id beyond 'by id', which is baseline behavior when the schema carries the load.

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 ('Retrieve a single document's metadata by id') and clarifies the scope is one document, which separates it from onfido_list_documents. It stops short of naming any sibling explicitly, so an agent must infer the contrast with the list variant.

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 'by id' implies the precondition of already having a document_id, but there is no explicit when-to-use guidance, no when-not-to-use, and no mention of onfido_list_documents as the alternative for enumeration.

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 and the bar is lower. The description adds the concrete endpoint but discloses nothing about error cases (invalid/unknown id), auth requirements, 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?

Two short sentences with no waste; the action and identifier are front-loaded and the endpoint sits in a supporting clause.

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 a clean readOnly annotation this is nearly complete. Since no output schema exists, it gestures at the return ('detailed breakdown + result') but does not characterize it, leaving 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 there is a single parameter whose format is documented as 'The report id.' The description only restates 'by id' and adds no syntax or format detail 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 (Retrieve), resource (single report), and lookup key (by id), plus the API endpoint GET /reports/{report_id}. The word 'single' cleanly distinguishes it from the sibling onfido_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 implied by 'by id' — the agent infers it should call this when it already has a report_id. No explicit when-to-use/when-not or named alternatives against onfido_list_reports 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?

The readOnlyHint annotation already establishes this is a safe read, and the description goes beyond it by enumerating the returned payload (status, output, task history), which is the most useful behavioral context given there is no output schema. It still omits any error/not-found behavior for an invalid id.

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: purpose and returned fields first, endpoint mapping second. No padding or redundancy, and the important clause leads.

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 readOnlyHint and no output schema, the description covers what the tool does and what it returns, which is enough to call it correctly. Minor omission: it doesn't state behavior on a missing/invalid run id.

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 workflow_run_id parameter, so the schema already documents it fully. The description only restates 'by id' and the REST path template, adding no format or sourcing detail 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 (retrieve) and resource (a single Studio workflow run), plus the scope of data returned (status, output, task history) and the lookup key (id). The singular 'single workflow run' vs. the sibling onfido_list_workflow_runs makes the retrieval-vs-listing distinction clear 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 'a single ... by id', which contrasts naturally with the sibling list_workflow_runs, but the description never explicitly says to use this when you already have a run id rather than to enumerate runs. No exclusions or prerequisites 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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds the pagination trait and the POST/GET endpoint mapping, which is modest but real context. It says nothing about rate limits, permission scope, or default page traversal behavior, so it stays at the baseline for an annotated 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 sentences with the core action front-loaded and no filler. The trailing 'Onfido API: GET /applicants' line is arguably redundant, but it is cheap and aids mapping to Onfido's own documentation.

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 simple, zero-required-parameter read tool whose safety profile is covered by annotations and whose parameters are fully documented in the schema, the description is essentially sufficient. No output schema exists, so return-value explanation is rightly absent; only the absence of any guidance on filtering or sibling choice is a 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 100% – page, per_page, and include_deleted are each fully documented with defaults and bounds in the schema itself. The description only echoes pagination and adds no format, interaction, or edge-case meaning beyond what the schema already 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 and resource ('List applicant (person) records'), plus the underlying API endpoint, so the agent knows exactly what the tool returns. It does not explicitly distinguish itself from the singular sibling onfido_get_applicant, but the plural 'records' and pagination framing make the collection-vs-single distinction inferable.

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?

There is no when-to-use guidance: nothing says to prefer this over onfido_get_applicant, whether any filtering is possible, or when include_deleted should be set. The only usage-adjacent statement is 'paginated', which describes mechanics rather than 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 '(read-only)' note is largely redundant. The description does add the underlying endpoint (GET /checks?applicant_id=…) and hints at the return content ('results/status'), but omits pagination, ordering, or result-size 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 compact sentences, front-loaded with the operation and scope before the API detail. Every clause 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 single-parameter read tool with annotations covering the safety profile and no output schema, the definition is nearly sufficient. It could be more complete by noting pagination or the max checks returned, but nothing critical 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?

Only one parameter exists and schema coverage is 100%, with the schema itself stating 'The applicant id whose checks to list (required)'. The description adds no syntax or format 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+resource ('List the verification checks') scoped to an applicant, and clarifies the payload ('results/status, read-only'). The plural 'checks' implicitly distinguishes it from the singular 'onfido_get_check' sibling, but no sibling is named explicitly, so it stops short of a 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?

Usage is only implied: an agent can infer it should call this to enumerate an applicant's checks. There is no guidance on when to prefer this over onfido_get_check for a single check, nor any mention of pagination 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 tells the agent this is a safe read, so the description is not carrying the full behavioral burden. It usefully adds the "metadata only" return-content constraint and the underlying API endpoint, but says nothing about pagination, result limits, or ordering for a list operation.

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, zero filler. The core purpose and the metadata-only constraint are front-loaded, with the API endpoint trailing as reference detail.

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 list tool with no output schema, the description conveys what is returned (metadata only) but omits any pagination or result-count behavior an agent would need to page through results. It is adequate but not 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 description coverage is 100% and the single parameter is fully documented in the schema, so the description adds no syntax or format meaning beyond it. The endpoint line confirms applicant_id is a query filter, which is mild added value but not substantive. 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 gives a specific verb+resource ("List the identity documents uploaded for an applicant") and adds the scope qualifier "metadata only", which implicitly separates it from the sibling onfido_get_document that fetches a single document's detail. It does not explicitly name that alternative, so sibling differentiation is implied 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?

The parenthetical "metadata only" hints at when this list view is preferable to fetching full document details, and the required applicant_id makes the preconditions obvious. However, there is no explicit when-to-use/when-not statement or named alternative, leaving the agent to infer the choice from the noun alone.

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 valuable context beyond that: '(metadata only)' tells the agent no binary image content is returned, and the underlying 'GET /live_photos?applicant_id=…' endpoint discloses the real API call and query shape.

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 sentences, front-loaded with the operation and scope, with the API path as a compact second sentence. No filler; every clause contributes.

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-only list tool with no output schema and annotations covering safety, the description is nearly sufficient, and '(metadata only)' usefully hints at the return shape. It falls just short on sibling differentiation and pagination/return-detail expectations.

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 applicant_id is already fully documented in the schema as the required identifier. The description only restates it in the endpoint template and adds no format, syntax, or constraint details beyond what the schema 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 (List) and resource (live photos) scoped to a single applicant, and the '(metadata only)' qualifier narrows the payload. However, it does not distinguish itself from the very similar sibling onfido_list_live_videos, which an agent choosing between the two would need.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives. Given the near-identical sibling onfido_list_live_videos, the absence of routing guidance is a real gap, leaving the agent to infer selection from the name alone.

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 '(metadata only)' note does add real value by telling the agent the response is metadata rather than media, but pagination, ordering, and result limits for this list operation are unaddressed.

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 trailing 'Onfido API: GET /live_videos?applicant_id=…' is marginally useful context for a tool-calling agent and is brief enough not to hurt.

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-only list tool with no output schema, the description covers purpose, scope, and the metadata-only nature of the return. It stops short on pagination and result shape, which the absence of an output schema leaves undocumented.

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 applicant_id parameter, so the schema already carries the semantics. The description only echoes it via the URL query string, adding no new meaning; 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+resource+scope: 'List the live videos captured for an applicant.' An agent can distinguish it from onfido_list_live_photos by the resource named, though the description never explicitly contrasts the two near-identical 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?

Usage is implied by the resource and the required applicant_id, but there is no explicit when-to-use, no note on when to prefer it over list_live_photos, and no mention of prerequisites or the case where an applicant has no videos.

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 establishes this is a safe read. The description adds the underlying API endpoint (GET /reports?check_id=…), which is useful for tracing behavior, but says nothing about pagination, ordering, result volume, or whether all report types are always present. Modest added value over 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?

Two tight sentences, purpose first, API hint second. Nothing redundant and nothing padded.

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-param, read-only list tool with a fully documented schema, the description covers what is being listed and how. The only gaps are pagination/return-shape behavior, which are not covered by an output schema either.

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 check_id parameter is fully documented there, so the schema does the heavy lifting. The description's endpoint hint restates the same parameter without adding format, validation, or edge-case detail.

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 (reports) and immediately scopes it: 'the individual reports that make up a check', with examples (document, facial similarity, watchlist). This clearly distinguishes it from the singular sibling onfido_get_report and from onfido_list_checks.

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 'reports that make up a check' plus the required check_id imply you call this after obtaining a check id, but no explicit when-to-use or alternative is named (e.g. why this instead of onfido_get_report, or how it relates to onfido_get_check). Usage is inferable but not 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?

readOnlyHint=true already declares the safety profile, but the description adds real context beyond the annotation: it clarifies the operation is a query over workflow runs, not a trigger for one, and hints at the returned content (status/output). It does not cover pagination behavior or rate limits, but the 'does NOT start a run' clarification is genuine added value.

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 clauses that front-load the resource and its read-only scope, followed by the exact API path. No filler sentences, and the most decision-relevant fact (does not start a run) appears before the endpoint trivia.

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 six optional filters fully described in the schema and an annotation covering safety, the description supplies what remains missing: what the tool returns (status/output) and that it is non-mutating. No output schema exists, so the brief return hint is a reasonable stand-in, though it could say more about result shape.

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 six filter/pagination parameters (page, sort, status enum, applicant_id, created_at bounds) are fully documented in the schema itself. The description adds no parameter-level detail beyond that, 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 (List) and resource (Onfido Studio workflow runs), and explicitly contrasts with the write operation 'does NOT start a run', which is the closest confusion risk. It also names the underlying API endpoint, so the agent can map it precisely to the singular onfido_get_workflow_run 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 an explicit negative condition ('does NOT start a run') that usefully rules out the start-run tool, and the read-only framing signals the correct context. It stops short of naming onfido_get_workflow_run as the single-run alternative, so routing between list and get is left to the reader.

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 give destructiveHint=true, so the description earns credit by disclosing that the operation is reversible and, importantly, that it runs no verification. It stops short of explaining what is overwritten or how partial updates behave, and 'reversible' sits in mild tension with destructiveHint=true rather than fully contradicting it (something can be destructive to old values yet undoable).

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 purpose front-loaded and a single parenthetical for behavioral caveats and endpoint. 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?

Adequate but with clear gaps: for a mutation tool with nested objects and no output schema, the description does not clarify partial-vs-replace update semantics or what the response returns. The rich schema covers the inputs, so the missing pieces are secondary, keeping this at minimum-viable-plus.

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 eight parameters are already documented and the baseline is 3. The description adds no field-level meaning beyond restating the applicant_id path parameter, so 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 and resource ('Updates an applicant's details') that is plainly distinct from the create/get/list siblings, and pins it to the PUT /applicants/{applicant_id} endpoint. It is clear but does not explicitly name an alternative the way a top-tier definition would.

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?

No explicit when-to-use / when-not-to-use or named alternatives; the guidance is implied by the verb. It does add one useful scoping cue ('runs no verification'), telling the agent this call won't trigger a check, which is real usage context but not a full decision rule.

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