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

No annotations are provided, so the description carries full burden. It discloses critical behaviors: guest checkout, Stripe collects email, session is single-use and expires in 24 hours, and caller-supplied entity_name is not displayed (safety about audit data). It also warns against fetching the URL. This is comprehensive and goes beyond basics.

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 a single dense paragraph but efficiently packed with essential information. Each sentence adds value: pricing, required parameters, return value, error conditions, alternatives, and security warnings. Despite length, it is front-loaded with the core purpose and ends with critical usage caveats. No redundant fluff.

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?

Even though there is no output schema, the description explicitly states the return (checkout_url + next_steps) and the follow-up workflow (feed session_id to claim_dossier). With full parameter documentation and clear behavior, the description is complete for the tool's complexity. It addresses all necessary aspects for correct 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 description coverage is high (100%), so baseline is 3, but description adds value: it explains the pricing tiers in prose, clarifies that entity_id comes from search_entities, and details entity_name's audit-only role and its recent behavior change. It supplements the schema with context that helps correct 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 description opens with a specific verb+resource and clear purpose: 'Start a one-off dossier purchase via guest Stripe доListening surtout mailing类专业 unsaturated бы粱作为一名大笑mesytetiwxx: product name visible anywhere, product name without, "buy_dossier" not mention in "Buy" or , and line: "Start a one-off dossier purchase..." This differentiates from siblings like get_payment_link (permanent link) and claim_dossier (token retrieval). It clearly states the action and the return of checkout_url, and distinguishes from get_pricing and get_payment_link.

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 explicitly states when to use this tool vs alternatives: 'WRONG TOOL IF NOBODY IS THERE TO PAY...' and 'Use get_payment_link for a permanent, reusable one...'. It also warns not to fetch checkout_url programmatically. This provides clear when/when-not guidance and names alternatives.

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

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

With no annotations, the description carries full behavioral disclosure. It details depth caps, the meaning of depth_capped, the legacy exposed field's limited usefulness, and a concrete anonymous-caller example, giving the agent excellent expectations for edge cases.

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 long and dense, but the complexity of the verdict semantics justifies much of the length. It is front-loaded with the core purpose and then walks through states and caveats; however, the measured example and repeated warnings could be tightened without losing value.

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 there is no output schema, the description thoroughly explains return values: the chain, flagged hops, verdict states, depth_walked, depth_capped, and legacy exposed. It also covers cap behavior and id sourcing, making the tool usable without additional external 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?

Even though the schema covers both parameters, the description adds meaningful semantic value: it tells the caller to obtain id via search_entities or lookup_by_identifier, and explains that anonymous callers are capped at 2 hops regardless of max_depth. This goes beyond the schema's basic field descriptions.

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: 'Walk the ownership chain upward from an entity and flag...', which clearly identifies what the tool does. It also distinguishes this tool from siblings like trace_ownership_path or get_sanctions by emphasizing the offshore/sanctions-secrecy verdict semantics.

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 provides strong interpretive guidance, such as 'BRANCH ON verdict, NOT on exposed', and warns against promoting checked_full_clean to 'no offshore exposure' without quoting depth_walked. It does not explicitly name alternatives or exclusions, but the context for appropriate 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?

Since no annotations are provided, the description fully carries the burden of behavioral disclosure. It reveals idempotency (same session returns same grant, safe to retry), handles failure (402 not_paid until payment completed), and explains the return structure and tier variations. This is comprehensive and directly addresses operational behaviors an agent needs.

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 a single, well-structured paragraph. It front-loads the core purpose, then provides usage, return details, and error handling without unnecessary verbosity. Every sentence adds value, no fluff.

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 there is no output schema, the description thoroughly explains return values ({ token, entity_id, tier }) and how to use them. It also covers idempotency, retry safety, and error conditions. With no annotations, this is as complete as one could expect for a tool of this complexity.

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 schema already provides 100% coverage for session_id with a clear description. The description adds contextual meaning by explaining where to get the session_id (from the post-payment redirect after buy_dossier) and reiterating the format (cs_...). This goes slightly beyond the schema, so it earns a 4.

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 clearly states a specific action: redeem a paid Stripe Checkout session for a dossier access token. It uses a specific verb+resource (claim dossier) and distinguishes itself from sibling tools by referencing buy_dossier and get_dossier, which is exactly the kind of differentiation needed.

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 explicitly states when to use the tool: after the post-payment redirect following buy_dossier. It also tells the agent to pass the returned token to get_dossier, and explains when not to call (before payment completion), including the 402 not_paid failure and the retry guidance. This is explicit usage context with alternatives.

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

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

With no annotations, the description carries full burden and excels: discloses partial coverage (990,055/47,486,969 = 2.1%), skew (99.6% risk-listed, 97% natural persons), behavioral nuance (HTTP 200 with count:0 for non-embedded entities), and a verified example (BARCLAYS BANK PLC). Even warns against misinterpreting empty 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?

Every sentence earns its place. The description front-loads the core purpose, then returns format, then critical limitation warnings. It is longer than average but all content is necessary behavioral caveats, and it remains well-structured and readable.

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 there is no output schema, the description compensates by detailing the return shape ({ id, count, hits } with per-hit fields). It covers the tool's purpose, limitations, fallback alternatives, and edge-case behavior, making it fully self-contained for an agent.

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

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

Schema coverage is 100%, so baseline is 3. Description reinforces that entity_id must come from search_entities, but adds little beyond the schema's existing descriptions for entity_id and k. It does not explain k's effect beyond schema, but no compensation needed due to high schema coverage.

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 clear verb+resource: 'Entities most similar to a given one — the nearest corpus dossier cards ('more like this')'. It explicitly names the intended use case (peer discovery, clustering) and distinguishes itself from semantic_search and search_entities via fallback guidance.

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 explicit when-to-use: 'for peer discovery and clustering around a known entity' and clear exclusion: coverage is partial/skewed, empty results mean 'not embedded' not 'no peers exist'. Directly names alternatives: 'Fall back to semantic_search or search_entities.'

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?

No annotations are provided, so the description carries the full burden. It discloses the return structure ('Returns `{ entity, company_details, provenance, note, source }`'), notes data completeness with a specific measurement date and sample size, and flags overdue statuses. It does not mention potential errors, rate limits, or auth requirements, but for a read-only lookup tool, the provided behavioral context is strong.

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 information-dense but well-structured, front-loading the core purpose and data fields, then usage guidance, return format, and data-quality metric. It is slightly long but every sentence adds value, including the comparative metric against get_financials. No wasted words.

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 moderate complexity (single parameter, no output schema), the description is quite complete: it lists the data fields, return envelope, usage examples, and data-quality context. It could mention pagination or error behavior, but for a single-id lookup with no output schema, the description covers the essential context well.

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 schema already provides 100% coverage for the single parameter 'id' with a description ('Entity id (a UK company).'). The description adds that the id is for a UK company and how to obtain it, but does not add significant new semantics beyond the schema. Baseline 3 is appropriate given full schema coverage.

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 clearly states the tool retrieves Companies House register details for a UK company by entity id, listing specific data fields (registered address, status, company type, incorporation date, SIC codes, filing/compliance layer). It distinguishes itself from siblings by noting it is the 'best-populated of the UK detail tools' and contrasts with get_financials, making its purpose and differentiation explicit.

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 provides explicit usage guidance: 'Use this for 'where is X registered / what does it file / is it overdue / what was it called before''. It also tells the agent how to obtain the required id ('Get the id from search_entities or lookup_by_identifier'), and implicitly contrasts with get_financials for financial data, giving clear when-to-use context.

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

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

With no annotations, the description must carry the behavioral burden. It does so by disclosing the free tier limitation ('first ownership hop + latest financials'), the token/API key unlock mechanism, and provenance guarantees ('Every claim traces to a source URL'). It does not cover rate limits or error handling, but provides strong contextual behavior.

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

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

The description is a solid paragraph without fluff. Each sentence contributes value: purpose, provenance, use case, id source, and tier/token details. It could be slightly shortened, but it is appropriately sized for a complex paid tool with no annotations or 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 complex dossier tool with no annotations and no output schema, the description is remarkably complete. It explains what the dossier includes (cross-source records, ownership/control, UBO chain, risk signals), what the user gets on free tier, and how to unlock full depth. It doesn't describe the exact return format, but 'structured dossier' implies sufficient structure for the agent to proceed.

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 context about where the id comes from (search_entities) and where the token comes from (claim_dossier), plus the environment variable alternative. However, the schema already fully documents both parameters, and the description adds little beyond acquisition channels.

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

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

The description opens with a specific verb+resource: 'Build a structured, fully-cited intelligence dossier for one entity by id'. It clearly distinguishes this from siblings like search_entities ('Get the id from search_entities') and get_entity by emphasizing the comprehensive dossier nature and the 'tell me everything about X' use case.

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 provides an explicit use case ('Use this for "tell me everything about X"') and a prerequisite ('Get the id from search_entities'). It also explains free vs paid tiers and token acquisition, but does not explicitly name alternative tools or say when NOT to use it, which is a minor 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?

With no annotations, the description carries the transparency burden. It discloses the main output shape, listing supported fields, and clarifies the entity types. However, it does not mention caveats, limits on relation depth, formatting, authentication needs, or what happens if the id does not exist.

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 sentences, front-loaded with the core purpose, and pack is highly relevant. Every phrase adds something meaningful: the action, the input, the output fields, and the id-source relationship.

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 is reasonably complete: it states input, output fields, entity types, provenance, and how to get the id. It could be improved by briefly mentioning what is not included or why this is distinct from get_dossier/get_company_details, but the essential usage is clear.

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 schema only documents 'Entity id' but the description adds useful semantic guidance: the id refers to a specific entity full record, and the id is typically derived from search_entities or lookup_company. This helps agents understand what value to pass and how to obtain it without duplicating 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?

Description explicitly names the tool's action ('Full record for one entity by id') and enumerates the returned fields (type, identifiers, jurisdiction, risk level, summary, direct relationships with provenance). It distinguishes itself from search tools by referring to them as id-sources, establishing a clear get-by-id purpose.

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 provides direct workflow guidance: 'Get the id from search_entities or lookup_company.' This clearly implies the primary use case (fetch a full entity record once id is known), but it does not list explicit alternatives or when-not-to-use scenarios relative to other sibling tools like get_dossier or get_company_details.

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

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

With no annotations, the description carries the full transparency burden and exceeds it: it discloses the source, the exact return shape, that most entities return empty financials with a note (with a concrete measured sample and even a Barclays example), that balance-sheet fields are well-populated while turnover/profit are sparse, and that absent filings must not be conflated with filed zeros. This is unusually rich operational context.

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

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

The description is longer than average, but every sentence earns its place: purpose, use-case, return shape, normal-empty caveat, measured evidence, field-skew warning, and note-reading instruction. It is front-loaded with the core function and flows logically from purpose to usage to interpretation, with no filler or tautology.

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, but the description compensates by stating the return structure, enumerating the reported financial fields, explaining the empty-financials behavior, and clarifying the meaning of the note field. For a tool whose main risk is misinterpreting missing data, this is a complete and robust 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?

The schema already describes id as 'Entity id (a UK company)' at 100% coverage, so this dimension starts at baseline 3. The description adds meaningful provenance ('Get the id from search_entities') and reinforces that the id must be a UK company entity id, going slightly beyond the schema without needing more detail.

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

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

The description opens with a specific verb and resource: 'Filed financial figures for a UK company by entity id' using Companies House iXBRL accounts, and enumerates the exact metrics (turnover, profit/loss, net assets, cash, shareholder funds, fixed/current assets, employee count). This clearly distinguishes get_financials from sibling tools such as get_dossier or get_company_details, which serve broader company-profile purposes.

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 'use this for' clause ('what are X's revenue / profit / net assets / how many employees') and points to search_entities as the source for the id. It does not explicitly name alternative tools for other data types or state a 'when not to use' condition, but the coverage warning strongly informs expectation-setting around use.

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

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

With no annotations provided, the description takes on a substantial information burden. It explains link permanence, reusability, the lack of need for an API key or WhiteIntel account, and the ability to bind to a company via client_reference_id. It also discloses the exact response tier structure and its limitation (no Premium link).

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 dense and front-loaded, using bolding and uppercase for emphasis. While it's long, every sentence provides necessary context for a financial transaction tool. The most critical distinguishing points (permanent, shareable) appear first.

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

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

For a parameterless tool with no output schema, this description is complete. It covers purpose, usage restrictions, behavioral traits, pricing structure, and limitations. It fully compensates for the absence of structured annotations and output schema.

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 has zero parameters, so the schema is minimal and 100% covered. The description even adds the optional client_reference_id query parameter context, though that isn't an explicit input. Given 0 params, baseline is 4, but the detailed context around query string binding elevates this to 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?

The description clearly identifies this as the tool for permanent, shareable Stripe payment links for one-off dossiers. It emphasizes the distinction from buy_dossier (single-use, 24h expiry), which is the key to its purpose, explicitly naming the sibling tool to prevent confusion.

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 explicitly contrasts with buy_dossier, stating 'use this INSTEAD of buy_dossier whenever you need something you can HAND TO A HUMAN.' It also explains when buy_dossier is required (for Premium), thereby offering clear alternatives and exclusions.

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

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

With no annotations provided, the description carries the full disclosure burden and delivers: 'Static data, no network call' explicitly declares the behavioral contract, alerting the agent that no side effects or costs are involved. It also discloses return semantics ('Returns how_an_agent_buys') and reveals the purchase-side behavior requiring external payment ('buy_dossier opens a Stripe Checkout, a human... pays, claim_dossier mints the access token').

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?

Though long, the description front-loads the key purpose first, then organizes information in digestible parentheticals and enumerations without redundancy. Every element — tiers, discounts, flow, edge case, and behavioral flag — earns its place; the final 'Static data, no network call — check it before recommending a purchase' is a dense, purposeful closer with no wasted words.

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 simplicity (0 params, no annotations, no output schema), the description is remarkably complete: it covers all pricing products, describes the full order-of-operations among siblings, handles the human-less edge case, and flags its read-only network-free nature. There are no gaps an agent would need clarified to use this appropriately when recommending a purchase.

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 has zero parameters with 100% trivial schema coverage, so per the rubric baseline is 4. The description enhances this by specifying what the return payload contains (pricing tiers per product line, discounts, and the purchase flow walkthrough), going beyond the bare schema by describing the data an agent would consume. No parameter documentation burden exists here.

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 clause, 'WhiteIntel's price list plus the exact machine flow for buying access,' uses a specific verb-plus-resource phrasing that unmistakably identifies what the tool returns. It also distinguishes itself from siblings by clarifying this is static reference data explaining the purchase flow rather than the buying action itself — the description explicitly differentiates from buy_dossier, claim_dossier, get_dossier, and get_payment_link.

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 gives explicit when-to-use guidance with 'check it before recommending a purchase' and walks through the full purchase pipeline, including an alternative with a conditional discriminator: 'Step 0 of that list covers the case with no human present: get_payment_link returns permanent Stripe links you can hand over instead.' It even notes the metered API tier and the no-human-present edge case, giving the agent a decision map of when each sibling applies.

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

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

With no annotations to lean on, the description carries the full burden and delivers extraordinary disclosure: the feed is 'NOT A BALANCED MIX', it is 'ordered by ingest recency', and it reveals a measurement that the newest 100 rows were '100% kind: ownership, all from one registry' (2026-08-11). It even corrects prior misinformation ('NOT GLEIF as earlier versions of this description claimed') — the kind of bias disclosure that would be invisible to an agent without this text.

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 front-loads the core definition, then usage, then warnings — good structure with strong leading content. However, the measurement statistics (100/100, dates, percentages) appear twice: once in the main prose and again inside the `kind` enum descriptions, creating slight redundancy. Every sentence otherwise earns its place; the uppercase emphasis is effective but the near-duplicate measurement reports could be consolidated.

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 there is no output schema and no annotations, the description fully compensates: it covers what is returned (events with a source registry), ordering semantics, parameter behavior, per-kind meaning, and dangerous default-bias caveats. For a monitoring/feed tool of moderate complexity, there is nothing essential an agent needs to know that the description omits — it even notes when defaults 'move as loaders run,' setting correct expectations about non-determinism.

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?

Although schema coverage is 100%, the description goes far beyond, defining each enum value with measured composition — e.g., 'watchlist = OpenSanctions non-sanctions listings — politically-exposed persons, criminal/wanted entries and procurement debarments, not PEPs alone' — and clarifies the registry source (borme/companies_house/opensanctions). `since` is meaningfully framed as a sync cursor for polling rather than a plain date filter. This is exactly the value the schema's one-line hints forfeit.

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 crisp noun phrase identifying the exact resource and behavior: 'The WhiteIntel Pulse activity feed: recent corpus events... newest first, each with a source registry.' It enumerates the four event kinds, states the ordering, and notes provenance — a specific verb+resource that is impossible to confuse with the sibling search/lookup/graph tools despite no sibling being named.

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 an explicit when-to-use: 'Use this to answer "what changed recently" or to monitor the corpus.' It also supplies when-not-to-infer guidance ('do not infer "nothing else happened" from the default page') and instructs the agent to pass `kind` when it wants a particular stream. This directly helps the agent choose between this and the search/entity siblings, even without naming them.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals cluster expansion, signal_type semantics, null list/regime behavior, the distinction between sanctioned_self and sanctioned_via_cluster, the false-positive tail, and back-compat behavior. This is far beyond what annotations would have provided.

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 long but every sentence earns its place: it front-loads the core function, then delivers critical caveats, a concrete measured example, flag semantics, and id-source guidance. The structure is logical and dense without redundancy, which is appropriate given the tool's misleading name and nuanced behavior.

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, the absence of an output schema, and the absence of annotations, the description is remarkably complete. It covers return contents, signal types, null handling, flag meanings, false-positive risk, and how to obtain the required id. An agent has enough information to invoke the tool and interpret its results 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?

The input schema already fully documents the single `id` parameter with 100% coverage. The description adds useful semantic value by specifying that the id should come from search_entities or lookup_by_identifier, and by framing the id as an entity id. This goes beyond the schema's bare 'Entity id' description.

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: 'Return an entity's screening exposure for the entity AND its resolved cluster siblings, each with a source URL.' It also explicitly distinguishes the tool from its misleading name by clarifying it is not sanctions-only and by directing attention to `signal_type`. This clearly separates it from sibling tools like get_entity or lookup_by_identifier.

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 provides strong contextual guidance: it explains what the tool returns, warns that a `sanctioned: false` response can still contain adverse findings, and tells the agent to get the id from search_entities or lookup_by_identifier. It does not explicitly enumerate when not to use the tool versus alternatives, but the context is clear enough for an agent to select it appropriately.

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?

No annotations are provided, so the description carries full weight. It discloses hard caps, depth clamping, deduplication changes, truncation behavior, edge-count expectations, and a warning not to trust requested depth. This is far more transparent than typical tool descriptions.

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 front-loaded with the core purpose and sibling distinction, which is helpful. However, it becomes quite long and mixes historical measurements, explicit troubleshooting notes, and warnings in a way that requires careful parsing; a tighter summary would improve scanability without losing key caveats.

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?

Without an output schema, the description provides important response semantics: depth_requested, depth_walked, depth_capped, completeness, truncation, edge_count, and edge origin. It also covers edge cases around hubs and duplicate records, making the tool safe to invoke even under complex conditions.

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 input schema already covers 100% of parameters, so the baseline is 3. The description adds meaningful semantic context for the `depth` and `edges` parameters (request vs actual depth, budget and deduplication) and points to source endpoints for `root`.

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 explicitly that it returns ownership/control edges within a bounded number of hops in both directions, with entity neighbours. It also distinguishes itself from the sibling `trace_ownership_path` by noting that tool is upward-only, making the tool's purpose and scope 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 gives a clear use case: 'what sits around this company?' and explicitly contrasts the wider neighbourhood view with `trace_ownership_path` (upward only). It also tells the agent how to obtain the root id via `search_entities` or `resolve`, so invocation prerequisites are 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It excels here, detailing the bounded BFS, non-exhaustive nature, depth-capping behavior, free-tier plan limitation, and the meaning of found:false. It also discusses response fields like exhaustive, verdict, bounds_note, and depth_capped, giving the agent comprehensive insight into runtime behavior.

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

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

The description is verbose and heavily repetitive, with multiple ALL-CAPS warnings and run-on sentences. While every sentence adds some information, the structure is not concise and would benefit from tighter organization. The core message could be delivered in half the length without losing impact.

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 complexity of the tool and the lack of annotations or output schema, the description is highly complete. It covers edge cases (bounded search), failure semantics (found:false), response structure (verdict, bounds_note, depth_capped), plan limitations, and performance characteristics, ensuring the agent is well-informed about all important behaviors.

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 documents all parameters, so the baseline is 3. The description notably enhances understanding of max_depth by warning that the response's max_depth may be reduced and advising deliberate use of depth 4. However, it adds no new meaning for the from/to parameters beyond what the schema provides.

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 clearly states the tool's purpose: 'Find how two entities are connected' via a bounded breadth-first search over ownership and control edges, returning ordered hops. This is a specific verb+resource description, but it does not explicitly distinguish itself from sibling tools like trace_ownership_path or graph_neighbourhood.

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?

While the description provides extensive operational warnings (e.g., bounded search, not to report found:false as clean), it offers no explicit guidance on when to choose this tool over siblings or what alternatives exist. The usage context is implied but no exclusions or comparisons 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?

With no annotations, the description fully discloses return shape (single entity with id, type, jurisdiction, identifier, risk), distinguishes two failure modes (400 for unsupported scheme, 404 for not found), and states that all schemes were production-tested. It also explicitly documents validation behavior (complete enum, hard-reject with 400).

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 dense but every sentence earns its place: purpose, usage, failure modes, and exclusions are each addressed. It is front-loaded with the core purpose and structured logically, avoiding redundancy despite its length.

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 (11 schemes, two error modes, non-accepted identifiers) and no output schema, the description is remarkably complete. It covers return value shape, error handling, fallback guidance, and test validation date, leaving no major gap for an agent to misinterpret.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the complete accepted set, giving examples of non-accepted identifiers, and detailing error responses tied to parameters. However, much of the parameter detail (e.g., br-cnpj formats) is already in the schema, so the incremental addition is moderate.

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?

Clearly states it resolves an entity by strong external identifier, lists specific identifier types, and explicitly distinguishes from search_entities as fallback. The verb 'resolve' and resource 'entity' are specific, and it scopes to single entity results, differentiating it from sibling tools like lookup_company which uses name-based 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?

Provides explicit when-to-use ('when you already hold a registry id'), when-not-to-use with fallback ('A 404 is a statement about the corpus, not about the tool — fall back to search_entities'), and names alternatives (search_entities for Cyprus ids). Also excludes unsupported identifiers (cy-reg, cusip) with concrete advice.

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

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

With no annotations provided, the description carries the disclosure burden. It clearly states the input constraint behavior (verbatim number, preserve leading zeros) and the return behavior (company record plus ownership graph with specified edge types). It does not discuss missing-company behavior, but for a lookup tool this is reasonably transparent.

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 sentences with no filler. It front-loads the main action, then provides the key nuance (leading zeros) and representative examples.

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 one required parameter, full schema coverage, and no output schema, the description provides a clear picture of both input and output expectations. It names the graph components, making the tool sufficiently complete for selection and 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?

The input schema already covers the single parameter, so the baseline is 3. The description adds meaningful semantics beyond the schema: the number must be passed verbatim, leading zeros must not be stripped, and concrete examples are given. This helps the agent handle real-world Companies House identifiers correctly.

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: 'Look up a UK company by its Companies House registration number.' It also distinguishes itself from siblings by explicitly promising a 'ready-built ownership graph' (officers, PSCs, parent/subsidiary edges), which differentiates it from search_companies or get_company_details.

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 makes the primary use case obvious: pass an exact Companies House registration number. It gives clear input guidance ('Pass the number verbatim — do not strip leading zeros') with examples. It does not explicitly mention when a sibling like search_companies should be used instead, but the context is otherwise 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?

The description discloses behavior thoroughly: it explains confidence levels ('exact' vs 'name'), handling of unmatched rows (returns `{ match: null, confidence: null }`), and warns that 'name' matches are candidate hits, illustrated with a concrete Tesco example. This transparency is essential since no annotations are provided.

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 excessively verbose and repetitive. Key information (e.g., the Tesco example, the confidence semantics, and the limits) is stated multiple times, significantly bloating the text. It could be condensed to a few sentences without losing clarity.

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 description provides comprehensive context, including usage scenarios, limits, and edge cases. However, the completeness is marred by redundancy; while all necessary details are present, the over-explanation detracts from efficiency. A more concise version would achieve the same completeness.

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 explains the 'queries' parameter in detail: it accepts a list of company names or strong identifiers in 'scheme:value' format, with examples like 'siren:552081317' and 'gb-coh:00445790'. This fully clarifies the expected input structure.

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 clearly states the tool's function: batch-resolving a list of company names or strong identifiers to canonical WhiteIntel entity IDs. It also mentions the output format and confidence levels, making the purpose 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?

The description explicitly advises when to use the tool: 'Use this to enrich a whole list — suppliers, counterparties, a portfolio — without one lookup per row.' It also notes the batch size limits (25 anonymously, 100 with API key), providing clear operational 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?

No annotations are provided, so the description carries the transparency burden. It discloses that this is a free-text name search scoped to UK Companies House, but it does not describe return format, ordering, pagination, or no-match behavior. It adds some useful context but is not comprehensive.

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 concise sentences. The first gives the core action and scope, the second explains the purpose and relationship to a sibling tool. Every word earns its place, and the key information is front-loaded.

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

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

For a simple two-parameter search tool with no output schema, the description is sufficiently complete: it explains the input, the source, and the intended downstream use. It could benefit from mentioning the response shape, but this is not a major gap given the tool's simplicity.

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 input schema already provides full descriptions for both parameters (q and limit) with 100% coverage. The description adds no extra parameter-specific semantics, so it stays at the baseline for schema-covered parameters.

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 ('search') and resource ('UK Companies House') and defines the output as resolving a company name into the registration number. It also ties directly to the sibling tool 'lookup_company', making its role 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?

The description clearly tells when to use this tool: to resolve a name to a registration number needed by lookup_company. However, it does not explicitly mention when not to use it or how it differs from search_entities, so it lacks full exclusion/alternative 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?

Discloses that the source field indicates resolved vs live passthrough, does not name the originating registry, suggests get_entity for that, and notes the fallback options. Also provides a concrete example with verified non-UK sources, showing transparency about data coverage.

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 overly verbose, containing a long digression about provenance, specific measurement dates, and an example. While the initial sentence is clear, the subsequent details could be streamlined to improve conciseness without losing essential 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?

Given the tool's complexity and many siblings, the description covers the primary use case, fallback behavior, result handling, and a key parameter. It could mention potential errors or the exact output format, but it is largely complete for a search 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?

The description only adds extra context for the juris parameter (scoping to a country) and does not elaborate on q, risk, type, or limit. Since the schema already provides descriptions for all parameters (coverage 100%), the added value is limited, so a baseline of 3 is appropriate.

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

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

Clearly states it searches all nodes (companies AND people) by name across all fused sources, and distinguishes it from semantic_search by calling it the fallback lexical 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?

Explicitly instructs when to use it (fallback when semantic_search returns thin results), how to use the returned IDs (pass to get_entity or trace_ownership_path), and mentions the juris parameter for scoping.

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?

No annotations are provided, so the description carries full burden. It discloses risk-list bias with measured statistics (embedded 990,055 of 47,486,969, ratio 0.0208; ~99.6% risk-listed, ~97% natural persons), a verified example ('sanctioned russian aluminium holding' returned RU sanctioned ships), the authoritative and moving `coverage` object, and latency (6.4s cold). This is far beyond typical disclosure.

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

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

The description is dense but front-loaded: first sentence states purpose, then filters and return fields, followed by caveats, usage guidance, and latency. Each sentence contributes a distinct fact (mechanism, bias, coverage, paired tool, performance). No filler or redundancy.

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 there is no output schema and no annotations, the description fully compensates: it names return fields, the `coverage` object, limitations of the embedded slice, the need to pair with search_entities, and latency. This is enough for an agent to decide whether and how to call the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces kind values (Company/Person/Asset) and jurisdiction as ISO code, and gives a natural-language query example, but it adds little meaning beyond the schema's parameter descriptions. No contradiction or missing parameter context.

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?

Description opens with a specific verb and resource: 'Meaning-based entity search over the corpus (BGE-M3 vector ANN over the resolved dossier cards).' It clearly states what it finds (companies and people semantically closest to a natural-language query) and differentiates itself from lexical sibling search_entities. It also names return fields and how to chain results into get_dossier / trace_ownership_path.

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 instructs when to use this tool versus alternatives: 'ALWAYS pair this with search_entities, which is lexical and covers the full corpus, before concluding anything about an entity's existence.' It also explains that an empty or off-target result means 'not embedded yet' far more often than 'not found', guiding the agent's interpretation and fallback behavior.

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?

Despite no annotations, the description reveals critical behavior: max_depth is 'a REQUEST, not a PROMISE,' top hop is not necessarily UBO, and includes a measured example of depth capping (max_depth=6 returned as max_depth:2, depth_capped:true). It also discloses the standing caveat on `as_observed` dates, covering data-validity limitations.

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 long but every sentence carries unique information: purpose, use case, root source, critical warnings, response shape, and caveats. It is front-loaded with the main action, but the density makes it slightly less concise than shorter equivalents.

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 provides the full response shape (flat `hops` array with fields from/fromName/to/toName/role/share/source), key response fields (`hop_count`, `max_depth`, `depth_capped`), and interpretation guidance. It covers edge cases and data caveats, making it fully contextual.

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 schema already covers both parameters thoroughly (100% coverage), so baseline is 3. The description adds a concrete measured example and the instruction to fetch root from search_entities, enriching semantics but not fundamentally changing 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?

Description opens with 'Walk the ownership graph upward from a root entity and return the ordered hops' – a specific verb+resource+output. It further clarifies the use case with 'who ultimately controls X?' and distinguishes from general graph tools like graph_path.

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 states 'Use this to answer ''who ultimately controls X?''' and instructs 'Get the root id from search_entities.' It also provides detailed guidance on handling depth capping and verifying UBO, effectively telling the agent when to trust the result.

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