Prometiam Risk Intelligence

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered; the description adds the valuable detail that scope is bound to the calling API key (no parameters to target another account). It does not say whether the call itself consumes credits or whether rate-limit values are static quotas vs. remaining budget, which is the one behavior an agent would still want.

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

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

Two sentences, front-loaded with the return contents, followed by the practical use case. The enumerated fields are all substantive and none of the wording is redundant with the title.

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 burden of describing return values, and it does so by listing the five categories of data returned. It does not describe the response's shape or units beyond parenthetical notes on rate limits, so an agent knows what is available but not exactly how it will be structured.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly reinforces that identity is implicit in the API key rather than supplied as an argument, leaving no ambiguity about how to invoke it.

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?

Names a specific verb-and-resource combination ('Returns the calling API key's account info and current usage') and enumerates the exact contents (plan tier, rate limits, credits used/left, enabled scopes). No sibling tool covers account or credit state, so an agent can immediately tell this apart from the company/LEI/sanctions lookups.

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 a concrete usage scenario in the user's own words ('how many credits do I have left?'), which is exactly the trigger an agent needs. It stops short of stating when-not to call it or naming alternatives, but there is no plausible competing sibling for this purpose.

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?

Goes well past the readOnly/openWorld annotations: per-item credit cost, a 429 batch_exceeds_quota refusal with max_items_now, request-order results with found/not_found/error/timeout statuses, and precise idempotency replay semantics including 409 while running and 422 on differing items. It also discloses fuzzy name matching limits (best match only, no similar-spelling fallback).

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?

The core capability is front-loaded in the first clause and nearly every detail is operationally useful. It is, however, one dense run-on sentence chain, so the quota, credit and idempotency facts are harder to scan than they need to be.

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 contract itself: result ordering, the four status values and the shared company object shape. Combined with the cost and quota behavior, an agent has everything needed to call it and interpret the response.

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 a rule the schema cannot enforce: each item needs country plus either an identifier (company_number, with nif/siren/vat aliases) or a name. It also explains match_score and the 24h idempotency-key replay window beyond the schema's terse field note.

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 ('Resolve up to 100 companies in ONE call') and even names the endpoint. The batch scope plus the sibling reference (companies_search's company object) makes clear this is the bulk counterpart to the search/identifier 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?

The batch-of-100 framing implies when to prefer it over single-record siblings like company_by_identifier or companies_search, and it notes the result objects match companies_search. It never explicitly says 'use companies_search instead when X', so routing is inferred 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?

Beyond the readOnly/openWorld/non-destructive annotations it discloses operationally decisive behavior: 400 validation_error on malformed identifiers or out-of-range limits, credit cost ("1 credit a page"), the ranked pool of ~700 candidates with has_more/next_cursor paging, and that match_score/match_type vary by fallback mode with meta.search_mode flags. It also flags data-quality traps an agent could otherwise misread, such as "dissolved" meaning different things by country and the French non-diffusible record with null name that is excluded from name searches.

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?

The description runs to several thousand words, with nested parentheticals inside parentheticals (the vat_number_source passage alone spans hundreds of words). Country-by-country coverage notes, source credits and licence text have been inlined into a tool description, which buries the three or four facts an agent actually needs — pagination, credit cost, fallback semantics — deep in the text. Only the first sentence 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?

For a 22-parameter, multi-jurisdiction search with no output schema, the definition covers the essentials: what identifiers map to which country, status semantics, null conventions, pagination, credits and error behavior. Its problem is distribution rather than absence — completeness is achieved by dumping the entire coverage and licensing documentation into the description.

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 22 parameters in detail, and the description largely restates it (country codes, VAT rules, match_score bands). The added meaning is modest: the cursor/offset equivalence ("o:<n>", "offset=<n> is the same") and the note that a page past the pool is empty. Baseline 3 is appropriate when the schema carries the parameter burden.

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 opening sentence gives a specific verb and resource ("Search EU + UK companies in official registries by name or identifier") and it explicitly contrasts itself with siblings: "companies_lookup, which stays exact" and "To fetch one company by its register number ... use company_detail". However, the stated scope "EU + UK" is inaccurate against the tool's own country enum, which includes AU, CA, US, BR, CO, JP, IL, SG, TW, AR, UA, RS, EC and CL — an agent may wrongly conclude the tool cannot reach those markets.

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 routing guidance: use country to scope, use company_detail for a single register number, note that fuzzy/nif_other_letter fallbacks "are never applied by companies_lookup", and warn that outside ES a status filter must be combined with a name or company_number. What it lacks is an explicit statement of when NOT to use this tool in favour of e.g. company_by_identifier, lei_search or events_search, and the routing advice is buried inside paragraphs of data documentation rather than stated up front.

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 read-only/non-destructive/open-world, but the description adds cost (1 credit), the underlying endpoint, country-resolution behavior, and the full error contract (400 for VAT-less registers, 404 for no match, 409 with candidates for ambiguous numbers). It also explains meta.resolved_by and its enumerated values, which is real behavioral detail an agent cannot get elsewhere.

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?

The core capability, cost and endpoint are front-loaded, and every sentence carries operational meaning. It reads as one dense run-on paragraph of shorthand, so it is efficient but not maximally scannable.

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 still characterizes the response ('answered like company_detail with the same include', plus meta.resolved_by), and it covers all three identifier modes and their failure modes. 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 baseline is 3, but the description goes beyond it by explaining how VAT prefixes imply country (EL is Greece, XI Northern Ireland, CHE Switzerland) and when country is mandatory. The include parameter is only loosely described as 'as on company_detail', which keeps it from a 5.

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 ('Find ONE company from an identifier') and scopes it further with the endpoint, cost (1 credit) and the promise that it answers like company_detail. That cleanly separates it from name-based siblings such as companies_search and from vat_validate.

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 per-type usage rules: vat needs a prefixed number or a country, lei uses GLEIF links, company_number requires country, and countries with no VAT register return 400. It never explicitly names an alternative tool (e.g. 'use companies_search for names'), so it falls short of the when/when-not/alternatives bar.

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?

Beyond the read-only annotations, the description discloses 404 for unknown numbers, 409 ambiguous_company_number with error.candidates, credit costs, country-specific coverage, and many data caveats such as null disqualified_officers meaning the register could not be read. This is unusually rich behavioral context 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?

The description is extremely long, with per-country provenance, licensing credits, status vocabularies, and register quirks that far exceed what an agent needs to select and invoke the tool. It is front-loaded with a useful first sentence, but the bulk is reference material that harms scannability.

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 carries the return-value burden, and it does so thoroughly: profile fields, age fields, NACE/ISIC/NAICS mappings, officers, registry_details, and include-specific blocks are all described. For a complex, multi-country company lookup, an agent has enough 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 baseline is 3, but the description adds real meaning: it explains the id-versus-register-number choice and details what each include block adds, including risk_flags, insolvency, structure, financials, charges, and country availability. The country parameter's enormous enum is also given operational context, though much of that belongs in reference docs rather than invocation guidance.

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 first sentence states a specific verb and resource: fetch a single company by Prometiam internal ID or by the register's own number with country and company_number. It clearly distinguishes this from companies_search by telling the agent to get an ID there first.

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 the two lookup modes (id versus country + company_number), says to obtain an ID from companies_search first, and explains that include attaches extra blocks. It does not explicitly compare against siblings like company_by_identifier or companies_lookup, so the routing guidance is strong but not exhaustive.

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?

Beyond the read-only annotations, the description discloses credit cost, plan requirements, empty-result behavior, null semantics, missing-value reasons, country-specific limitations, and benchmark caveats. This is unusually rich behavioral context for an agent.

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?

The description is extremely long and presented as a single dense block with repeated licensing, credit, and country-by-country detail. The core purpose is front-loaded, but most sentences do not earn their place for an agent trying to invoke the tool efficiently.

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?

Given the tool's complexity and lack of an output schema, the description is remarkably complete: it explains returned statement fields, null handling, availability statuses, coverage per country, license credits, and benchmark semantics. An agent has enough context to understand both what the tool returns and its limitations.

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 explains the seven parameters. The description adds some meaning for years, currency conversion, and statement types, but it does not systematically clarify every parameter such as include or include_superseded, making this close to the 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?

The description states a specific verb and resource: annual financial statements of a company, mapped to a standard chart, in filing currency and euro, up to ten fiscal years. It does not explicitly distinguish itself from sibling tools such as company_detail or companies_search, but the purpose 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 implied by the extensive coverage and exclusion notes, and the description explains when no statements are available and what plan or credits are needed. However, it never explicitly says when to use this tool versus alternative sibling tools, so the guidance remains implicit rather than directive.

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 annotations already declare this is a read-only, non-destructive, closed-world operation. The description adds useful behavioral context by explaining that it returns aggregate dataset coverage statistics and freshness information rather than individual records.

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?

The description is two tightly written sentences. The return contents are front-loaded, followed immediately by concrete usage examples, with no wasted wording.

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 zero-parameter, read-only metadata tool, the description is complete enough to call correctly. It describes the returned statistics and gives representative user intents, and no output schema is needed because the return shape is summarized in text.

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?

This tool has zero parameters, so there are no parameter semantics to explain. The baseline for a parameterless tool is 4, and the description does not need to compensate for missing schema details.

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 and resource: 'Returns dataset coverage statistics'. It then enumerates the exact metrics returned, making it clearly distinguishable from sibling lookup 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 provides concrete example user questions that should trigger this tool, such as coverage and data freshness. It does not explicitly name alternatives or exclusions, but the intended use is clear.

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 read-only, non-destructive, open-world behavior, so the description adds real value by disclosing the ES-only coverage limit and the degradation behavior (empty set plus a notice) for other countries. It does not mention result ordering or what the rollup aggregates return, which keeps it below 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 short sentences: capability first, then the analytic use case, then the geographic caveat. There is no filler and the most decision-relevant constraint (ES only) is not 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 six-parameter, read-only rollup tool with full schema coverage, the description covers purpose, use case, and the critical coverage limitation. With no output schema, a note on what each result contains (e.g. person plus company count) would close the remaining 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%, so all six parameters are already documented in the schema, including the min_companies threshold and the country enum. The description only echoes the name filter and implies the 'many companies' threshold without explaining the default of 5 or that the threshold is tunable — 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 states a specific verb and resource — 'List directors/officers who sit on many companies (cross-directorship rollup)' — which is a distinct capability from the plain-looking people_search sibling. It does not name the closest sibling explicitly, so sibling 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?

'Useful for spotting nominee directors and network hubs in due diligence' gives a clear use case, and the ES-only note effectively acts as a when-not for non-Spanish countries. However, no alternative tool is named for the case where the agent wants single-person lookups or per-company officer lists.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. Beyond that, the description discloses the returned payload (full before/after values) and the conditional behavior of include=notice, including the null case for countries other than BORME/BODACC/Companies House. It omits error behavior for unknown IDs, 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 sentences, front-loaded with the action and payload, followed by the prerequisite. No filler, and the conditional include behavior is stated inline rather than in a separate rambling 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?

With no output schema, the description carries the burden of describing returns and does so well: before/after values plus the optional source publication. For a two-parameter read tool this is nearly complete; only failure/not-found 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?

Schema description coverage is 100%, so both parameters are already documented, and the description largely restates them (internal ID; include=notice attaches the publication). The added nuance is that the publication may be null outside the three named registries, which is a small increment over the schema wording.

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 and resource ("fetch a single corporate-event record") plus the keying mechanism (Prometiam internal ID) and the payload (before/after values). It contrasts implicitly with the list-style siblings events_search and events_timeline by positioning itself as the single-record retrieval.

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 an explicit prerequisite workflow: "Get an ID from events_search or events_timeline first," which routes the agent to the correct siblings for discovery. It does not spell out a when-not case (e.g. use events_search when you have no ID), but the dependency is unambiguous.

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?

Beyond the readOnly/openWorld annotations, it discloses return fields (event_type, act_type, event date, before/after, notice URL), the event-type enum's meaning, coverage by country, and the register-change dating rules. It also notes that register-change events are not gazette notices and gives start-date constraints.

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?

The first sentence is front-loaded, but the description then becomes a very long wall of country-by-country coverage and register details, much of which is not needed to select or invoke this tool. It repeats or expands on schema/coverage information and is difficult to scan.

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 complex, multi-country event search with no output schema, it supplies enough return-field and coverage context to call the tool correctly. It omits some countries present in the country enum and does not route to sibling event tools, but the schema fills much of that 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%, so the baseline is 3; the description adds meaningful mode semantics by explaining that company_name/company_number select a company search while their absence switches to the country feed and makes country required. It also restates date_from's default and maximum lookback, though it adds little for limit, cursor, include, or event_type 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?

The opening sentence names a specific verb and resource ('Search normalized corporate-event records') and distinguishes the two retrieval modes: by company via company_name/company_number, or as a country event feed when both are absent. An agent can identify what the tool 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?

It clearly states the mode-selection rule (company identifiers vs country feed) and the country-feed requirement that country be supplied, plus date_from's default and 31-day limit. It does not explicitly compare the tool with siblings such as events_timeline or event_detail, so alternative selection is left implicit.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered elsewhere. The description adds genuine context — result ordering (newest first) and the breadth of event categories — but says nothing about pagination, how many events come back, or whether name-based lookups can be ambiguous.

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 primary behavior and ending on the required-input constraint. Nothing is redundant, though it could be tightened slightly by folding the timeline example into the first sentence.

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?

Five parameters at 100% schema coverage and no output schema, so the burden on the description is moderate. The description covers what the tool returns, for what scope, and in what order, leaving only pagination behavior and ambiguous-name handling 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?

The description covers company_id and company_name in terms of the one-of requirement, but never explains the risk of an ambiguous name match or mentions event_types/limit at all. The schema documents the limit and event_types fully, and the company_id descriptions are self-explanatory, so the baseline 3 with partial descriptive coverage 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 and resource: 'Returns the event history for one company, newest first', and enumerates the event categories (incorporation, funding rounds, product launches, key hires). This is clearly distinct from a generic search, though it does not explicitly name a sibling such as events_search or event_detail to sharpen the boundary.

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?

'Useful for building lifecycle timelines' implies the use case, and the single-company scope implies the alternative is events_search for multi-company queries. But it never states when to use events_search or event_detail instead, and gives no exclusions or prerequisites beyond the identifier note.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description goes well beyond that with non-obvious behavior: per-item credit cost, the 24h free replay rule with 409/422 failure codes, result ordering and the 'none is not proof of solvency' caveat. It stops short of stating rate limits or whether 'timeout' items are retried or billed.

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 paragraph, front-loaded with the core action and scope, then output shape, then cost, then the replay caveat. Every clause carries distinct information — no restatement of the title and 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?

With no output schema, the description supplies the return contract itself: up to 5 notices per item newest-first, latest_filing_date, and the four status values. Combined with cost and idempotency semantics, an agent has everything needed to call this correctly and interpret results.

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 already 100%, so the baseline is 3; the description still adds real meaning on top of the schema by noting that `siren` is an alias for `company_number` and that the identifier must be exact as printed on the notice. The idempotency_key semantics (same items, 24h window, 409 while running, 422 on mismatch) also clarify behavior the schema only hints at.

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 ('Check ... counterparties for CORPORATE insolvency notices'), plus the batch scope ('up to 100', 'in ONE call') and the endpoint. The 'CORPORATE' qualifier and the bulk framing let an agent distinguish it from the single-entity insolvency_record / insolvency_search 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 rather than stated: the 'up to 100 ... in ONE call' phrasing signals when batching is appropriate, and the cost note ('every item costs 2 credits') offers an implicit efficiency argument. However, it never explicitly says when not to use this or names a sibling to use instead for a single lookup, and the idempotency note 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 only establish read-only, open-world, non-destructive behavior; the description adds substantial behavioral context: the 16-country scope, exclusion of personal/consumer insolvency, stand-alone DE/AT/US/NL notices, and per-country linking and date limitations. These details materially affect interpretation of results.

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?

The purpose is front-loaded, but the body is a single sprawling paragraph with repeated statements (e.g., US notices not linked, Spanish notices discussed twice) and legal attribution, making it far longer than needed. This hurts scanability for an agent.

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 complex 16-market search with many linkage caveats, the description gives thorough coverage of which notices exist, how they link to company records, and key exclusions. Although it lacks return-shape details, the schema covers all inputs and annotations cover safety, so the definition is functionally 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?

With 100% schema coverage, the schema already documents name, limit, cursor, country, dates, and event_type. The description adds country-specific date semantics (e.g., ES BORME publication vs court resolution, DK decision date, EE register entry date) and country linkage rules, which go beyond the schema but are not organized parameter-by-parameter.

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 opening sentence names a specific operation ('Search CORPORATE insolvency notices') and resource ('notices published in official gazettes and registers'), and the closing line explicitly distinguishes it from insolvency_search's linked ES/FR/GB risk-notice corpus. An agent can identify this as the broad multi-country gazette notice search.

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 says 'Use this for distress coverage in all sixteen markets' and names insolvency_search as the alternative, with country-specific linkage caveats. However, it does not explicitly route against insolvency_check, insolvency_record, or events_search, and the guidance is buried in coverage prose.

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, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds one useful behavioral note — that related corporate events are included, implying an embedded expansion — but says nothing about payload shape, missing-ID behavior, or result size, and there is no output schema to compensate.

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

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

Two sentences, both load-bearing: the first states the operation and its scope, the second supplies the prerequisite. The core action is front-loaded and there is no redundant restatement of the title or parameter 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 trivial one-parameter read tool with strong annotations and no output schema, the description supplies the essentials: what is returned at a high level and where the input comes from. It is only slightly under-complete on error behavior and return shape, which are low-stakes here given the readOnly annotation.

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 parameter, so the baseline is 3. The description echoes the schema's 'Prometiam internal ID' framing and adds the provenance hint about where to obtain the value, but contributes no format, range, or type detail 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 names a specific verb and resource ('Fetch a single insolvency / risk notice') and adds scope detail ('with related corporate events'), which separates it from list-style siblings. It stops short of disambiguating against insolvency_notices_search, another sibling that plausibly yields similar notices, so an agent cannot fully rule out the wrong retrieval tool from the text 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?

It gives a concrete precondition by routing the agent upstream: 'Get an ID from insolvency_search.' That is real when-to-use guidance rather than implied. The gap is that it names only one ID source while insolvency_notices_search exists as a sibling, leaving ambiguity about whether IDs from that tool are also valid here.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the notice categories and the complement-to-registry framing, but it does not disclose freshness, result ordering, pagination behavior, or coverage limits beyond what the schema implies.

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 core search action and examples. Every sentence adds either scope or context; there is no redundant wording.

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?

The definition covers the tool's purpose, primary search keys, geographic/date scoping, and its relationship to registry data, which is sufficient given full schema coverage and read-only annotations. It is slightly thin on return behavior and pagination for an 11-parameter search with no output schema, but not enough to prevent correct selection or invocation.

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 explains all 11 parameters in detail. The description adds useful grouping by saying searches run by company name or identifier and can be scoped by country and date range, but it omits event_type, limit, and cursor semantics that the schema covers.

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 (Search) and resource (insolvency and risk notices), with examples of notice types and search keys. It does not distinguish this from sibling tools such as insolvency_notices_search, insolvency_check, or insolvency_record, so it falls 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?

It establishes a context — complementing company registry data with distress signals — and says to scope by country and date range. However, it offers no explicit when-not guidance or routing among the closely named insolvency siblings, leaving the agent to infer when this is the right 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 establish readOnly, non-destructive, open-world behavior, so the description correctly spends its words elsewhere: the authoritative source (GLEIF global register) and the returned data set. It does not disclose failure behavior (e.g. what happens for an unregistered or malformed LEI), which is the main remaining gap.

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 sentences, each doing distinct work: what it looks up, what it returns, when to use it. The return-field enumeration is front-loaded usefully since no output schema exists, and nothing is 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?

For a one-parameter lookup with no output schema, the description compensates well by listing the returned fields and naming the register. It is nearly complete; only error/not-found behavior and data freshness are 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?

With a single parameter at 100% schema coverage (min/max length 20, example value), the schema already carries the semantics. The description adds only the ISO 17442 framing and 'alphanumeric' context, which is marginal value beyond the structured field.

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 (look up) and resource (LEI in the GLEIF global register), plus the required key format (20-character ISO 17442 code). This implicitly separates it from name-based siblings like lei_search and lei_relationships, but it never names those siblings 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?

"Use to validate or enrich a counterparty that publishes an LEI" gives a clear, actionable context for selecting this tool. It offers no exclusions or explicit pointer to alternatives (e.g. use lei_search when you only have a name), which keeps it below a 5.

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 cover read-only, non-destructive, open-world. Beyond those, the description discloses the returned field set (LEI, legal name, jurisdiction, status, city/country) and, importantly, the data-completeness limitation that most entities report nothing. It does not mention pagination or limits on the children list, but that is a minor omission.

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 sentences, front-loaded with the dataset name and scope, then the return fields, then the coverage caveat. Nothing is redundant and every sentence carries information an agent can act on.

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 return-field inventory and the key expectation that many entities have no reported relationships. That is enough for an agent to call it correctly and interpret an empty 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?

There is one parameter at 100% schema coverage, with the schema already documenting the 20-character format and an example. The description restates '20-character LEI' but adds no new semantics, so the 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 names a specific dataset (GLEIF Level 2 'who owns whom'), a specific resource (a 20-character LEI), and the exact scope (direct parent, ultimate parent, direct children). That scope cleanly separates it from lei_lookup/lei_search, which cover entity identity rather than ownership chain.

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 clear from 'Reveals the accountable ownership chain behind an entity', and the caveat that only GLEIF-reported relationships come back — 'many entities report none' — is an effective when-not signal. It stops short of naming an alternative tool or stating what to do when no relationships exist.

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, openWorldHint and destructiveHint=false, so the safety profile is covered; the description adds genuine value beyond that by naming the returned fields (legal name, jurisdiction, status, city/country) and disclosing the ranking behavior and match_score. It stops short of describing pagination or what an empty result looks like, 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?

Purpose and routing are front-loaded in the first clause, followed by return contents and ranking detail; there is essentially no filler. The ranking parenthetical is slightly dense but each clause carries information an agent would otherwise have to discover by trial.

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?

This is a two-parameter read tool with no output schema, and the description compensates by describing the result fields, the ordering rule, and the downstream hand-off to lei_lookup. Nothing an agent needs in order to call it correctly, or to interpret the ordered candidate list, 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 goes further by explaining how the name parameter is interpreted — exact match first, then prefix matches, then names containing the words — with a concrete example (name=telefonica). That ranking semantics is not derivable from the schema, which merely calls it "Legal entity name to search for"; the limit parameter is left entirely to 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 ("Search the GLEIF global LEI register by legal-entity name (full-text)") plus the return contents, and explicitly differentiates itself from the sibling lei_lookup by positioning itself as the name-to-LEI resolution step. An agent can distinguish it from lei_lookup and companies_search 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?

Gives an explicit sequencing rule — "use to resolve a company name to its LEI before lei_lookup" — which names the alternative and the condition that selects it (you have a name, not an LEI). The implied inverse (if you already hold an LEI, skip this) is clear enough that no inference is required about which tool to pick.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes real value by describing the returned content (alert history with events/status/sanctions matches since subscription), which matters because there is no output schema, but it says nothing about pagination, behavior for an unknown/stopped monitor ID, or freshness of the history.

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, front-loaded with the core action and scope, with the parenthetical detailing the payload. Nothing is wasted, though the parenthetical is slightly compressed to the point of being cryptic ('events/status/sanctions matches').

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-only tool, the definition covers what it fetches, what it returns, and where the ID originates (via the schema). Missing only edge-case behavior such as unknown IDs or history size, which is a modest gap given 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?

Schema description coverage is 100% and the single 'id' parameter is documented in the schema as coming from monitor_subscribe or monitor_list. The description restates that the ID is a monitor ID without adding format, type, or fallback guidance, 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?

The description gives a specific verb and resource ('Get one monitored company by its monitor ID') and adds scope detail by explaining what the payload includes (alert history of events/status/sanctions matches). The word 'one' implicitly sets it apart from monitor_list, but no sibling is named explicitly, 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: by taking a monitor ID, it is clear this is the single-subscription read while monitor_list is the collection read, but the description never states that contrast, nor when to use monitor_subscribe/monitor_stop instead, nor any prerequisites beyond the schema's note about where IDs come from.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: results are scoped to the calling API key, include labels and last-alert timestamps, and the monitoring coverage is country-specific with defined event types. The signal is diluted by the duplicated country roster, but the added behavioral information is 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?

The first sentence is well-formed and front-loaded, but the second is a sprawling run-on that repeats essentially the same country roster twice (once as the monitoring list, once again as the 'corporate events' list with a date caveat buried mid-sentence). This is the dominant content by volume and is close to unparseable, and the coverage detail could be replaced by a pointer to the coverage tool.

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 parameterless read tool with full annotation coverage and no output schema, the description does the needed work: it says what is returned, that results are key-scoped, and what monitoring entails. The only shortfall is the missing routing hint to sibling tools, which keeps it from being fully 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?

The tool takes zero parameters, so there is no parameter meaning for the description to supply. Baseline 4 applies; nothing is ambiguous about invocation.

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 opening sentence gives a specific verb and resource ('List the companies currently subscribed to ongoing monitoring') plus the scope ('for this API key') and the returned fields. It is clearly distinguishable from monitor_get, monitor_subscribe and monitor_stop by the list semantics, though it never names those siblings 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?

There is no when-to-use guidance at all: nothing says to call this to audit subscriptions before monitor_subscribe or monitor_stop, and no alternative is named. The presence of monitor_get/monitor_subscribe/monitor_stop in the sibling set makes the missing routing guidance a real gap.

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 destructiveHint=true and idempotentHint=true, so the safety profile is carried structurally. The description still earns credit by adding context beyond annotations: that the action is irreversible and that alert history is removed, which is exactly the consequence an agent should surface before calling.

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 zero filler; the destructive consequence is front-loaded right after the action statement so the agent sees risk before acting.

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 destructive single-parameter mutation with annotation coverage and no output schema, the description supplies what matters: action, key, irreversibility, and what data is lost. It could optionally note error behavior for invalid IDs, but nothing essential 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?

There is a single required parameter with 100% schema description coverage ('Monitor subscription ID to delete'), so the schema does the heavy lifting. The description adds only the phrase 'by monitor ID,' which does not extend 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?

The description names a specific verb+resource pair ('Stop monitoring a company and delete its subscription') and identifies the key ('by monitor ID'). An agent can distinguish this from siblings like monitor_subscribe and sanctions_unwatch 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 implied by the verb — the agent knows this is the teardown counterpart to monitor_subscribe — but there is no explicit guidance on when to choose this over alternatives or what prerequisites (e.g., needing an existing monitor ID from monitor_list) apply.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true; the description adds real substance on top — 30-minute polling from 05:00 to 22:30 UTC, HMAC-SHA256 signed POSTs to webhook_url, and a webhook_secret shown only once. It does not explain the destructiveHint (whether re-subscribing replaces or duplicates an existing monitor) nor how the claimed idempotency interacts with creating a persistent subscription, which is the main behavioral gap for a write 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?

The purpose and the persistence warning are front-loaded and well placed, but the country list is enumerated twice — once in the event-coverage parenthesis and again in the 'Available for...' sentence — and both duplicate the schema enum. Roughly a third of the text is redundant re-listing rather than new 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?

For a persistent, destructive, webhook-driven subscription it covers coverage, cadence, signing, return values and dissolutions. Two gaps remain: the 'events' filter parameter is documented only as 'default: all' with no enumerated event types anywhere, and there is no mention of the cancel path (monitor_stop) once a subscription 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?

Schema coverage is 100%, so the schema already carries the per-parameter definitions and the 40-value country enum. The description still adds genuine semantics beyond it: Argentina is read monthly with no events before 28 Oct 2026 and no dissolution alert, Germany's energy-market companies are sanctions-match only, Netherlands requires LEI-registered entities with a KVK number, and the dissolution date_basis logic. That goes past restating the enum.

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 first sentence names a specific verb and resource — 'Subscribe a company to ongoing monitoring' — and immediately distinguishes this from the read-oriented siblings (monitor_list, monitor_get, company_detail) by describing an ongoing push to a webhook. An agent knows this is a persistent-write action rather than a query 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?

It gives a clear precondition ('confirm intent before calling') and a hard eligibility constraint (every live country except France and Chile). It does not name monitor_stop for cancellation or monitor_list for viewing existing subscriptions, so the routing guidance against siblings 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 cover the safety profile (readOnlyHint, openWorldHint, non-destructive), so the description's added value is in disclosure of result shape and ranking: appointment counts, a 0–100 fuzzy match_score, best-first ordering. The officer-availability constraint per country is genuinely behavioral context the annotations cannot express. It does not discuss pagination or empty-result behavior, keeping it below 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?

The core purpose and return format are front-loaded in two tight sentences, and the country caveat comes last where a secondary constraint belongs. The final sentence is dense and carries a long country enumeration, but every clause conveys a non-obvious coverage fact rather than 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?

With no output schema, the description correctly carries the burden of describing return values (matching people, appointment counts, match_score ranking) and adds the coverage caveat an agent would otherwise only discover by getting empty results. Pagination and cursor behavior are left entirely to the schema, which is acceptable given the full schema coverage.

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 meaning the schema buries: it isolates the four countries with officer-level data (Spain, France, the UK, Norway) and explains that Polish officers exist only on the company record because the KRS masks natural persons. That is a material disambiguation for the country parameter that the 43-value enum description does not make salient.

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 ('Search officers / directors / shareholders by name') plus the geographic scope (EU + UK registries), which is enough to separate it from companies_search and person_detail 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?

Explicitly routes the agent onward for depth ('Use person_detail for a full appointment history') and gives country scoping guidance including which countries have no person records. It stops short of naming companies_search as the alternative for company-name queries, so the sibling routing is one step less complete than a 5.

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, destructiveHint=false and openWorldHint=true, and the description is consistent with that. It adds substantial behavior beyond the annotations: cross-company appointment history, the null semantics of `disqualifications`, the name+birth-month matching method, the ambiguity rule when two register entries collide, and the explicit caveat that a match is an identity signal not a determination. It does not cover error behavior for an unknown ID or response/pagination 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?

The first two sentences are well front-loaded, but roughly three-quarters of the text is a single sprawling sentence about one sub-field of the response, dense with semicolons and parentheticals. The information is defensible given there is no output schema, yet it is disproportionate to the tool's one-parameter surface and would benefit from breaking into shorter, structured statements.

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 one parameter, the description carries the documentation burden and largely meets it for the highest-risk field (`disqualifications`), including licensing provenance. It is weaker on the overall response shape — the composition of the appointment-history records and other person attributes are not described.

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 `id` parameter, so the schema baseline is already a 3. The description adds meaning by identifying the ID as Prometiam-internal and telling the agent to source it from company_detail or people_search, which is operationally useful beyond the schema text.

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 ("Fetch a single person (officer / director) by Prometiam internal ID") and names the return payload (full appointment history across all companies). This clearly distinguishes it from the sibling people_search, which is a search rather than a by-ID fetch.

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 concrete usage contexts (director-network analysis, counterparty due diligence) and, importantly, tells the agent where the required ID comes from: a company_detail or people_search response. It stops short of explicit when-not-to-use or alternatives for bulk/name-based lookups, so it is not a full 5.

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?

Goes well beyond the readOnly/openWorld/non-destructive annotations: it discloses source coverage and thresholds per country (TED "above the EU thresholds only"), that natural-person suppliers are never returned, and that company_id is only populated when the supplier resolves to a company record. It also flags data-quality traps an agent could otherwise misread — amount_is_ceiling is not spend, amount_suspect is a form default, amount_eur vs amount_contract_eur is a share vs whole-contract distinction.

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?

Purpose and scope are front-loaded in the first clause, then the source coverage and one-row-per-award grain, then the field semantics. It is dense and long, but every clause carries decision-relevant information, especially since there is no output schema to explain the returned amount and competition fields.

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 11-parameter, no-output-schema, multi-country search tool, the description covers sources, thresholds, filtering defaults, result grain, amount semantics, competition signal and the mutual-exclusion precondition. An agent has everything needed to form a valid call and interpret the rows without further documentation.

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 every parameter, making 3 the baseline. The description adds only marginal parameter-level meaning beyond it — the country enumeration coverage across sources and the company_id-to-company_detail linkage, both of which are largely inferable from the schema text.

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?

Opens with a specific verb and resource ("List public-contract awards") plus filter dimensions and sort order ("newest first"), and adds a crucial grain statement ("One row per award to one supplier") that separates it from aggregate siblings like procurement_buyer or procurement_relationship. It never explicitly names a sibling or states what it is not, 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?

Gives concrete routing guidance for the country parameter ("pass country to restrict, omit it for all countries"), a hard precondition ("Requires at least one of company_id, nif, supplier, buyer, cpv or date_from"), and a follow-up pointer ("use company_detail on it"). It does not cover when to prefer procurement_buyer or procurement_relationship over this tool, so alternatives are only partly addressed.

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, openWorldHint and destructiveHint=false, and the description adds meaningful context on top: BETA status, the log-odds 1-10 ladder and its percentile interpretation, the caveat that counterparty is a "weak signal," and the explicit disclaimer that "a score is a prompt to look, not a finding of wrongdoing." That is unusually rich interpretive and epistemic context beyond structured fields.

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?

It is front-loaded with the entity, geography, and BETA status, then proceeds in a logical order. The long enumeration of output fields (base_rate, relative_risk, awards_scored, etc.) is dense and slightly list-like, but each term carries information an agent needs given no output 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?

With no output schema, the description carries the full burden of describing return values, and it does so comprehensively: both scores, their fields, behavior ratios, evidence awards, and top supplier relationships. It also sets expectations about calibration and signal strength, which is essential for correct downstream interpretation.

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 id formats (DIR3/NIF/SIRET) and the country enum with ES default are already documented. The description nonetheless adds cross-tool meaning by telling the agent to resolve the id via procurement_buyers, which the schema cannot convey.

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 the specific verb+resource ("Risk profile of a PUBLIC BUYER (a contracting body) in Spain or France") and immediately scopes it away from siblings: "never about a supplier or a tender." An agent can distinguish it from procurement_awards, procurement_relationship, or company_detail 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?

It gives a clear usability condition (buyer-level risk in ES/FR) and an operational prerequisite: "Find the id with procurement_buyers." It also implicitly excludes supplier/tender use cases. It doesn't state when a buyer profile will be unavailable or how this complements procurement_relationship, so it stops short of full alternative-routing 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, openWorldHint=true and destructiveHint=false, so safety is covered by structured data. The description adds value beyond that: it declares the ordering direction, flags the endpoint as BETA, and — with no output schema present — sketches the row payload (buyer, coverage, both risk blocks with score 1-10, probability, base_rate, relative_risk). It omits any note on rate limits, result caps or what happens when zero buyers match.

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 sentences, front-loaded with what the tool returns and how it is ordered, then usage, then row shape. Dense but every clause carries information; the parenthetical field inventories are slightly heavy but justified given the absence of an output 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, all-optional-parameter list tool with full schema coverage and no output schema, this is close to sufficient: purpose, ordering, screening options, pagination handoff and row contents are all discoverable. Remaining gaps are the BETA caveats (stability/limits) and edge-case behavior on empty results.

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 seven parameters are already documented, which sets the baseline at 3. The description does clarify the ordering semantics behind `model` ('ordered by one buyer score, highest first') and names `min_score` as a screening threshold, but adds no format or interaction details for name, region, country or cursor 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?

Specific verb and resource — lists scored public buyers (contracting bodies) in Spain or France — plus the ordering rule (by one buyer score, highest first) and a BETA status marker. It also distinguishes itself from the sibling procurement_buyer, which returns a single buyer, so an agent can tell the two apart 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?

Gives three concrete selection scenarios: screening a portfolio via min_score, viewing a region, and resolving a buyer name to an identifier before calling procurement_buyer. That is clear usage context with an explicit handoff to a sibling, though it never states what this tool should NOT be used for (e.g. full buyer risk detail, awards history).

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 cover the safety profile (readOnlyHint, openWorldHint, destructiveHint=false), but the description adds non-obvious behavior the annotations cannot: a hard coverage cap of five relationships per buyer, the 404 outcome and its meaning, and BETA status / ES-FR-only data. It stops short of describing response shape or any rate/credential constraints, but the dataset-limitation disclosure is the valuable part 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?

Two sentences, front-loaded with the dependency concept followed by the returned fields, then the coverage limit and fallback. Dense but every clause carries information; the long enumerated field list is justified because there is no output schema to carry it.

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 enumerating the returned metrics, and it also covers the two failure-relevant facts (top-five-only coverage and 404 behavior) plus jurisdiction limits. For a three-parameter, read-only lookup this is enough for an agent to call it correctly and to interpret an empty 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%, so buyer (DIR3/NIF, SIRET), supplier (NIF, SIREN) and the country enum with its ES default are already fully documented in the schema. The description only reinforces the geographic scope; it adds no per-parameter format or constraint detail beyond what the schema supplies, 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?

The description names a specific resource (buyer-supplier dependency for a public buyer and one of its five largest suppliers) and enumerates exactly what each record contains — awards, awarded value, supplier share, first/last award, single-bid awards, average bids, insolvency date. It also scopes it geographically (Spain or France, BETA), so an agent can distinguish it from procurement_buyer and procurement_awards 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?

It states the hard precondition — only the five largest relationships per buyer are held, and anything outside returns 404 — and names the concrete fallback, procurement_awards, for a supplier's full award list. That is an explicit when-not-to-use rule plus a named alternative, not an inference the agent has to make.

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 readOnly, openWorld and non-destructive, so the safety profile is covered. The description adds genuine context beyond them: ordering (newest first), the fact that each change carries the affected entity, and that records can be joined back to sanctions_entity. Pagination behavior beyond the limit parameter is not discussed.

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

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

Two sentences with no filler; the core scope and ordering are front-loaded and the usage hint follows immediately. Every clause carries information an agent would otherwise have to infer.

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 four-optional-parameter read tool with no output schema and full schema coverage, the description covers scope, ordering and result shape enough to call it correctly. Minor missing detail on volume/pagination expectations keeps 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?

Schema coverage is 100% with per-parameter descriptions including examples and ranges, so the schema does the heavy lifting. The description adds no syntax or format detail for 'since', 'list' or 'change_type' 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 ('List additions, removals and amendments detected on the sanctions lists') plus ordering ('newest first'). The contrast with re-screening a whole book of business makes it distinguishable from sanctions_screen 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?

Gives a concrete use case ('what changed recently') and implicitly steers away from full re-screening, which points at sanctions_screen as the alternative. It does not name that sibling explicitly or state exclusions, so it falls short of a full when/when-not pairing.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond them by disclosing the returned content, which matters because there is no output schema. It does not say what happens for an unknown or malformed ID, which is the one behavioral gap.

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

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

Two sentences, no filler: the first front-loads what is returned, the second front-loads the prerequisite. Every clause carries information an agent needs.

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 compensates by listing the returned fields, and it explains ID provenance. For a one-parameter read tool it is close to complete; only error/not-found behavior and the accepted ID types are left 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 'id' parameter is documented as a Prometiam internal sanctions-entity ID, so the baseline is 3. The description earns an extra point by explaining where a valid ID comes from (a sanctions_screen match), which the schema does not say. It does not address the integer-or-string union in 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 ('Fetch full detail for a single sanctions entity') and enumerates the payload (aliases, issuing programme/list, listing date, identifying data). The closing sentence names sanctions_screen as the source of the ID, which separates it from the screening siblings without any schema lookup.

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 a concrete prerequisite and trigger: 'Get an ID from a sanctions_screen match', which tells the agent this is the drill-down step after screening. It stops short of stating exclusions (e.g. don't call this for bulk lookups — use sanctions_screen_batch), so it is clear context rather than full when/when-not 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 cover the safety profile (readOnly, non-destructive, open-world), and the description adds genuinely new behavior: daily refresh cadence, the exact list coverage, Latin transliteration of non-Latin scripts on both sides of the match, and the one-row-per-list dedup rule. The mention of 'unless group is entity' references a parameter absent from this schema, which mildly muddies the disclosure, and neither rate limits nor the BETA caveat's practical consequences are explained.

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?

Purpose and match-score rules are front-loaded, but the middle is a bloated enumeration of all 17 lists plus a licensing attribution and dfat.gov.au URL that cost tokens without helping tool selection. Several clauses are run-on and one references a nonexistent 'group' parameter.

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 correctly carries the return contract — match score bands, source list, aliases, ISO country codes, and one-row-per-list behavior — which is exactly what an agent needs to interpret results. The main gap is that pagination via limit is left entirely unexplained for a call that can return up to 100 rows.

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 83% schema coverage the baseline is 3, but the description earns a bump by explaining what the threshold number actually means — the 100/80–99/50–79/under-50 match-type banding gives the agent real intuition for setting it. limit is never discussed in the description, and the include_pep/pep_min_tier semantics live almost entirely in 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?

Opens with a specific verb and resource — 'Screen a person or entity name against 44,000+ active sanctions and export-control designations' — and names the matching method (trigram fuzzy). It never routes against siblings like sanctions_screen_batch or sanctions_entity, so an agent must infer that this is the single-name variant, but the operation itself is unmistakable.

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 rather than stated: 'Use threshold to control match strictness' and 'Omit to screen all types' tell the agent how to tune an already-chosen call, not when to choose this tool over sanctions_entity or sanctions_screen_batch. No exclusions, prerequisites, or cost/latency guidance 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 cover the safety profile (readOnlyHint=true, openWorldHint=true, destructiveHint=false), and the description adds genuinely new context: per-item credit cost, the four item outcomes, and the caveat that 'clear' is not a certification. It also documents idempotent replay behavior with its 409/422 failure modes, which the annotations say nothing about. That is solid added value, though it stops short of describing result volume or ordering.

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 action and the hard cap, then the gating requirement and cost, then the semantics. It is dense with no filler, but the per-item status explanation and idempotency clause make it longer than a single-scan read; a slightly tighter grouping would help.

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 carries the return-value burden and does so by enumerating all four per-item statuses and warning about the false reassurance of 'clear'. Combined with auth scope, cost, and idempotency semantics, an agent has everything needed to call it correctly 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 coverage is 100%, so the baseline is 3, but the description earns an extra point by tying 'threshold' to what 'clear' actually means and by spelling out the idempotency_key replay contract with concrete 409 (still running) versus 422 (items differ) outcomes. The remaining parameters (list, group, limit, active_only) are left entirely to 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 with explicit scope: 'Screen up to 50 names against the sanctions lists in ONE call' plus the endpoint. The batch framing plus the 50-name cap lets an agent distinguish it from the single-name sibling sanctions_screen 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?

Gives real preconditions: the sanctions scope is required, batch calls do not draw on the free trial allowance, and each item costs 3 credits. It implies but never explicitly names sanctions_screen as the alternative for single-name screening, so the routing guidance stops just short of fully 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 destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is fully covered structurally and the bar for the description is lower. The description adds only the id provenance and says nothing about what happens to the entry (deleted vs flagged), whether it can be re-added, or what is returned — adequate but not enriching.

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 short sentence with the action and target front-loaded, followed immediately by the parameter source. Nothing is redundant or 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 one-parameter, annotation-rich tool with no output schema, the definition supplies what is needed to call it correctly: the action, the id, and where to get the id. It is only slightly incomplete in not stating post-removal effects or confirmation behavior for a destructive operation.

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 schema itself only says "Watchlist entry id." The description adds meaningful provenance — that the id comes from sanctions_watchlist — which tells the agent where to source a valid value. That is a genuine increment beyond the schema, though it stops short of describing id format or scope (per-user vs shared 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 ("Remove") and resource ("one of your sanctions watchlist entries") plus the keying parameter (id). It also distinguishes itself from the sibling sanctions_watchlist by naming that tool as the source of ids, so an agent can tell removal apart from listing/creating watch entries 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 parenthetical "(from sanctions_watchlist)" implies the prerequisite workflow: obtain ids from the watchlist tool first. However, it gives no explicit when-to-use/when-not guidance, does not contrast with the nearby sanctions_watch or sanctions_screen tools, and does not warn that this is irreversible in practice.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, and the description usefully adds what annotations cannot: plan gating and the asynchronous delivery of results via the sanctions_watchlist channel or webhook_url. It does not explain why the call is flagged destructive (e.g. whether an existing entry is overwritten) or how duplicate names are handled, so significant behavioral gaps remain.

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 front-loaded sentence with the action first, then the gating and side-effect details in a subordinate clause. No filler, no restating of the title.

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 three-parameter mutation with no output schema, the description covers the important runtime consequence (re-screening plus notification destination) and the plan requirement. It stops short of telling the agent what the call returns or what happens when the name already exists, which matters given the idempotent and destructive hints.

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 67%, above the baseline where the schema does most of the work. The description adds real meaning only for webhook_url ('calls webhook_url when set'), while entity_type and its enum are left entirely to the schema, which is acceptable given how self-describing the values are.

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?

Specific verb and resource: 'Add a name to your sanctions watchlist', which is clearly distinguishable from the sibling set (sanctions_unwatch, sanctions_watchlist, sanctions_screen). The only slight ambiguity is that it names 'sanctions_watchlist' as the reporting channel, a token identical to a sibling tool name, but the action itself 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?

It states the access prerequisite ('sanctions_watch scope, Starter and above') and describes the ongoing-monitoring behavior, which implicitly frames this as the persistent option versus a one-off screen. It never explicitly names an alternative tool or an exclusion case, but the operational context is strong enough to route the agent correctly.

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?

Beyond the readOnly/non-destructive annotations it discloses the required sanctions_watch scope and a tier-dependent cap on the number of entries, which an agent cannot infer from structured fields. Return shape (watchlists plus recent hits) is sketched but not detailed.

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 purpose, then the prerequisite, then the sibling routing. No filler or repetition of the title.

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 zero-parameter read tool with no output schema, the description covers what is returned, the access requirement, and how to modify the list. A brief note on return shape or pagination/limits behaviour for recent hits would make it 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?

The tool takes zero parameters, so the baseline applies; the description correctly describes a no-argument listing call and adds no misleading parameter expectations.

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 ('Return your sanctions watchlists') plus the payload ('any recent hits against them'), which immediately separates it from the mutation siblings sanctions_watch and sanctions_unwatch.

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?

Explicitly routes the agent to sanctions_watch for adding and sanctions_unwatch for removing entries, and states the scope prerequisite. It does not say when to prefer this over adjacent read tools such as sanctions_changes or sanctions_screen, so it stops short of full when/when-not coverage.

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 cover safety (readOnly, openWorld, non-destructive), and the description adds real behavioral context beyond them: a live official check against VIES, distinct retryable-error semantics for registry outages, and the caveat that Spanish/German registries may withhold the name. It also explains what registry_match actually represents (our own register data, not VIES confirmation), preventing a plausible misinterpretation.

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 purpose and scope, then edge cases in descending importance. It is dense but each sentence carries information an agent needs; the final registry_match sentence is slightly convoluted but resolves a real ambiguity about return values.

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 carries the burden of describing returns — and it does, covering the valid-case payload and the registry_match object's fields. Combined with the scope limits and error semantics, an agent has everything needed to call and interpret this single-parameter 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% and the schema already explains the country prefix and space/punctuation handling, so baseline would be 3. The description adds one genuinely useful format rule beyond the schema — Greek numbers must use the EL prefix — which prevents a common malformed call.

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 ("Validate an EU VAT number against VIES") plus the return payload (registered trader name and address). It also pins the exact geographical scope (27 EU states + XI, EL prefix for Greece, GB out of scope), so an agent knows precisely what this tool will and will not accept.

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 conditions for use and explicit exclusions (GB post-Brexit not covered, Greek numbers need EL), plus the crucial guidance that a retryable error means a down registry rather than an invalid number. It stops short of naming a sibling alternative for out-of-scope lookups, but no sibling covers VAT validation.

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