WhiteIntel — Ownership Intelligence

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

Annotations indicate it's not read-only, may have side effects (openWorldHint true) and is not idempotent. The description adds key context: it starts a one-off purchase via guest Stripe Checkout, no account needed, and that Stripe collects an email. It also says it returns checkout_url + next_steps reflecting a multi-step flow. It doesn't mention idempotency or repeated calls, but given openWorldHint, it's implied. This is a good addition beyond annotations.

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 well-structured, front-loaded with the core purpose, then details and follow-up instructions. It's concise despite length, covering all essential aspects without 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 the complexity of a purchase flow with Stripe and tiers, the description covers the purpose, parameters, next steps, and cross-reference to pricing and claim_dossier. It's complete for selecting and invoking 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 0%, so the description must explain parameters. It explains 'tier' with options and prices, 'pack' with values, and 'entity_id' as the target. It does not explain 'entity_name', which remains ambiguous. Since it's not required, maybe acceptable. But given the lack of schema description, it covers most, so 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 the action (start a one-off dossier purchase), the mechanism (guest Stripe Checkout), and the target resource (dossiers). It explicitly distinguishes from siblings like get_pricing (pricing list) and claim_dossier (post-payment claim step), making its 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?

It explains when to use this tool (to start a purchase) and notes that no WhiteIntel account is needed (a key differentiator). It also mentions the follow-up step (feed session_id to claim_dossier) and references get_pricing for the full list, which helps guide selection. However, it doesn't explicitly say when NOT to use this tool vs other tools like get_dossier or get_payment_link, though the purpose is distinct enough.

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, idempotentHint, and destructiveHint=false, so the description's safety profile is covered. The description adds useful behavioral context about traversing an ownership chain and flagging specific hop types, but it does not disclose output behavior, depth boundary effects, or data-source limitations. This is acceptable but not rich given the available annotations.

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, front-loaded sentence with no wasted words. The em-dash phrase adds a clear investigative framing. It could be slightly more informative, but it is concise 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 that there is no output schema, no parameter descriptions, and the tool performs a potentially complex graph walk with sanctions and jurisdiction flagging, the description is incomplete. It does not explain what the returned result contains, how max_depth affects traversal, whether cycles are handled, or how it relates to get_sanctions and trace_ownership_path.

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 0%, and the description does not explain the required 'id' parameter or the optional 'max_depth' parameter. The phrase 'Walk the ownership chain' implies that 'id' is the starting point, but 'max_depth' is completely unmentioned and no formats, defaults, or limits are given. The description fails to compensate for the absent schema 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 uses a specific verb phrase, 'Walk the ownership chain and flag sanctioned + secrecy-jurisdiction hops,' which clearly identifies the tool's core function. It also orients the user with the outcome label 'offshore-layering lead,' distinguishing it from sibling tools like trace_ownership_path or get_sanctions, though it does not explicitly name these alternatives.

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 implies usage for offshore-layering investigation by mentioning 'sanctioned + secrecy-jurisdiction hops,' but it does not explicitly state when to use this tool versus sibling tools such as trace_ownership_path or get_sanctions. No when-not-to-use guidance or alternative tool references are provided.

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?

Even though annotations already declare idempotentHint and destructiveHint, the description adds meaningful behavioral detail: it is idempotent, returns a specific shape, fails with a specific error code before payment, and should be retried later. There is no contradiction with the annotations.

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 three sentences long, front-loads the core purpose, and every sentence adds essential information: what to do, where to get the session_id, what it returns, and important failure/retry behavior. No filler or repetition.

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 one-parameter tool with no output schema, this description is complete. It explains the input source, the output shape, the retry semantics, and how the output feeds into get_dossier, covering all likely failure points and the expected flow.

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 schema description coverage at 0%, the description fully compensates by explaining that session_id is the Stripe Checkout session ID from the post-payment redirect, including the cs_ prefix format and where to obtain it. This adds real semantic value beyond the bare 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 description clearly states a specific action ('Redeem a paid Stripe Checkout session for a dossier access token') and connects it to the buy_dossier and get_dossier flow, making it distinct from siblings. It names the exact resource type and product.

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 tells when to call it: after the post-payment redirect following buy_dossier. It also states what to do next with the token (pass to get_dossier) and that it will fail with 402 not_paid until payment completes, guiding wait-and-retry 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?

Annotations already cover readOnly/idempotent/non-destructive, so the description's added value is the partial-coverage caveat and the empty-not-error behavior. These are important behavioral details beyond the structured annotations, though no additional details like response format 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 compact and front-loaded with purpose, then adds a key edge case warning. Every part earns its place; 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?

For a simple 2-parameter tool with no output schema, the description covers purpose, input source, coverage limitations, and empty-result behavior. It stops short of fully specifying the return shape and the exact effect of k on 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 has 0% description coverage, so the description must compensate. It explains entity_id well by saying to use an id from search_entities or semantic_search, but it does not explain what k controls, leaving an otherwise meaningful 'top-k' parameter ambiguous.

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 finds entities most similar to a given one, explicitly calling it 'more like this' for peer discovery. It also distinguishes itself by requiring an entity id rather than a query, which separates it from search tools.

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

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

It gives concrete usage context: pass an entity id from search_entities or semantic_search, and it explicitly warns that entities outside the embedded subset return empty. It does not explicitly name alternatives or when-not-to-use, but the context is strong enough to guide selection.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds content categories but does not disclose additional behavioral traits such as data source, UK-specific scope, or behavior for missing IDs. No contradiction with annotations exists.

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, front-loaded sentence that efficiently enumerates the key content areas without filler. Every phrase contributes meaningful information about what the tool returns.

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 single-ID read tool with rich safety annotations, the description adequately covers the main return categories. It lacks explicit mention of UK scope (present in the annotation title) and not-found behavior, but the low complexity and available annotations make this sufficient.

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 has one required string parameter 'id' with 0% schema description coverage, and the description does not explain what 'id' refers to or how to obtain it. The tool name and phrase 'for a company' imply it is a company identifier, but the description adds no real parameter-level semantics 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 description clearly identifies the resource as a company's registered profile and lists concrete content areas: address, status, SIC, incorporation, and filing/compliance details. It does not explicitly contrast with sibling tools like get_dossier or get_entity, 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?

The description gives no guidance on when to use this tool versus alternatives such as get_dossier, get_entity, or lookup_company. It implies a use case through the phrase 'Registered profile for a company,' but provides no explicit when-to-use or when-not-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?

Annotations (readOnlyHint, idempotentHint, openWorldHint) already establish safety, and the description adds meaningful behavioral context: the dossier is 'fully-cited' and the token unlocks purchased depth. This goes beyond the annotations by explaining why a token is needed and what it unlocks, improving transparency without contradicting any annotation. No contradiction.

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 deliver a clear definition and a critical usage note. Every phrase ('cross-source identity', 'fully-cited', 'unlock the full paid depth') carries weight. No fluff, direct, and well-structured for scanning.

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 covers the tool's core function, its contents, and the token workflow, which is sufficient for a read-only retrieval tool. It does not describe return format or error cases, but given the lack of an output schema and the presence of sibling tools, the description provides adequate context. A minor gap is not mentioning how this differs from similar 'get_*' tools, but overall it is complete enough for an agent to use 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 50% (only token has a description). The description enriches the token parameter by explaining its origin ('from claim_dossier') and effect ('unlock the full paid depth'), which is helpful. However, the primary required parameter 'id' receives no explanation in the description, leaving the purpose of that parameter undocumented. The description partially compensates for the schema gap but does not fully cover 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?

The description clearly states the tool returns a 'Structured, fully-cited dossier for one entity' and enumerates contents (identity, ownership/UBO, risk signals, financials, provenance). While it does not explicitly contrast with sibling tools like get_entity or get_financials, the term 'dossier' and the listed contents make the purpose specific and recognizable.

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 implies a workflow: pass the token from claim_dossier to unlock full paid depth. This hints at when to use the tool (after claiming) but does not explicitly address when NOT to use it or mention alternatives. The guidance is useful but not comprehensive, so a 3 (implied usage) fits.

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 mark the tool as read-only, idempotent, and non-destructive. The description adds output behavior not in annotations: it returns the full record, direct relationships, and provenance, giving a clearer picture of the return payload. It does not mention error behavior or pagination, but annotations cover safety traits.

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 10-word fragment that front-loads the key behavior and return structure. No filler, and it keeps the definition focused.

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 description covers the core return value but lacks usage differentiation from similar getters and id semantics. Provenance and direct relationships are mentioned but not elaborated, so an agent may still be uncertain about what 'direct relationships' includes.

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 has 0% description coverage, so the description must explain the 'id' parameter. It only says 'entity id,' without specifying the id format, namespace, or how it differs from identifiers used by lookup_by_identifier or get_company_details. This is thin compensation for an undocumented 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?

Description states it retrieves the full record for one entity id, including direct relationships and provenance. This is a specific resource (entity by id) and distinguishes from siblings like get_company_details and graph_neighbourhood, which target different resource shapes.

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

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

The phrase 'Full record' implies use when complete entity data and relationships are needed, but there is no explicit when-to-use or when-not-to-use guidance. Alternatives among siblings are not named, so the agent has to infer from tool names.

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 idempotentHint, covering the safety and repeatability profile. The description adds value by specifying that these are 'filed' year-over-year figures from Companies House iXBRL, indicating the data source and historical nature. It does not describe edge cases like missing years or coverage gaps, but it is not required given the annotations.

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, compact sentence that front-loads the core content: what is returned, which fields, and the data source. There is no filler, redundant wording, or repetition of information already present in annotations or 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 simple one-parameter read-only tool with no output schema, the description adequately conveys the return content and source. It could add a sentence clarifying the required ID parameter, but the tool's low complexity and the annotation coverage mean the description is nearly complete.

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

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

The input schema has a single required string 'id' with no description, and schema description coverage is 0%. The description also does not explain what the 'id' parameter refers to (presumably the company ID), the id format, or how to find it. Since the description provides zero compensation for the undocumented parameter, the semantics remain vague.

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 'Filed financials year-over-year: turnover, profit, net assets, cash, employees' clearly identifies the resource (filed financials) and the specific data fields returned, and the source (Companies House iXBRL) further distinguishes it from sibling tools. It lacks an explicit verb, but the tool name 'get_financials' supplies that, so the basic 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?

The description implies that this tool should be used when historical filed financial figures are needed, and the field list suggests typical use cases. However, there is no explicit guidance about when NOT to use it or how it compares with alternatives like get_company_details or get_pulse, so usage context is only 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?

Beyond the safe-read annotations, the description discloses non-obvious behavior: links never expire, are reusable, require no API key or WhiteIntel account, and the default unbound purchase yields a dossier credit. This adds meaningful behavioral context not present in annotations.

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, all high-signal: purpose, comparison with alternative, usage detail, and auth requirements. No filler or repetition.

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 tool with rich annotations and clear sibling distinction, the description fully covers the relevant context: link properties, when to use, optional binding behavior, and access requirements. No output schema is needed given the obvious return is the link.

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 zero schema parameters, the baseline is 4, and the description adds extra value by documenting an optional query parameter ?client_reference_id=<entity uuid> and explaining its consequence. This exceeds 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 'PERMANENT, shareable Stripe payment links for the one-off dossiers', clearly identifying what the tool provides. It differentiates from the sibling buy_dossier by contrasting single-use 24h Checkout Sessions with never-expiring reusable links.

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 directs agents to use this instead of buy_dossier when handing a link to a human, and explains why buy_dossier is unsuitable. It also documents the optional client_reference_id parameter for binding to a specific company, providing clear decision 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context: 'Static, no network' and explicitly states what it returns, including the machine flow. This goes beyond the annotations without contradicting them.

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 core purpose and immediately followed by concrete pricing and flow details. Every word earns its place; no fluff or repetition.

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 zero parameters, no output schema, and a simple informational purpose, the description is complete. It covers what is returned, the pricing details, the step-by-step buying flow, and the static nature—all an agent needs to decide when and how to use this 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?

No parameters exist, so the description carries no parameter burden. It does describe the return value's shape (how_an_agent_buys), which is more than necessary for a zero-parameter tool.

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?

Describes exactly what the tool does: provides WhiteIntel's price list and the buying flow. Includes concrete details (prices, subscription tiers) and names the return field how_an_agent_buys. Clearly distinct from sibling purchase/dossier 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?

Explicitly states 'check it before recommending a purchase', giving a clear when-to-use directive. It also outlines the flow involving siblings (buy_dossier, claim_dossier, get_dossier), placing the tool in context. Does not explicitly exclude alternative price-related tools like get_payment_link, but the static informational nature is evident.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: the default feed only returns events with a source URL, and watchlist events are uncited (source-url NULL). This explains filtering behavior and data provenance, which is not present in the annotations. No contradictions found.

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 compact, with the core purpose front-loaded in the first sentence. It covers essential points (default filter, watchlist caveat, streaming usage) without excess. The structure is logical: purpose → usage hint → behavioral nuance. No redundant or filler content.

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

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

The tool is a feed with 3 parameters and no output schema. The description explains the feed's content (ownership-change and filed-accounts events), default filtering behavior, watchlist specifics, and the streaming mechanism. While it does not describe return fields or pagination details explicitly, the 'since' usage implies a cursor pattern. Given the tool's moderate complexity and the presence of helpful annotations, the description is fairly complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'since' (stream new events) and 'kind' (opt-in watchlist, implying default kinds ownership/filing), but does not explain the 'limit' parameter at all. The description adds meaning for two of three parameters, but the missing 'limit' documentation leaves a gap. Given the low coverage, this is partial compensation.

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: 'The corpus activity feed — recent ownership-change and filed-accounts events, cited.' This provides a specific verb (feed) and resource (corpus activity), and the mention of 'cited' adds a distinguishing feature. However, it does not explicitly contrast with sibling tools like search or entity lookups, so it lacks explicit 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?

The description gives usage instructions for the 'since' parameter ('Pass since=<next_since> to stream only new events') and notes that 'watchlist' is opt-in via 'kind=watchlist'. This implies when to use the tool (to stream new events or request watchlist data) but does not provide explicit guidance on when NOT to use it or how it compares to alternatives like search_entities or get_entity. The guidance is contextual but not comprehensive.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds context by specifying the sanction lists (OFAC/EU/UN/UK) and the 'resolved cluster siblings' scope, which is not visible in structured fields. It does not contradict annotations.

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 sentence with zero redundant words. It conveys the essential information about scope (OFAC/EU/UN/UK) and output (citations) without fluff, making it highly efficient.

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 tool with one parameter and no output schema, the description gives a basic understanding of the result (sanctions exposure with citations). However, it omits details on the return format, what 'exposure' entails (e.g., risk scores, match types), and how the cluster siblings are derived. Given the low complexity, it is adequate but not fully precise.

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 0% and the description does not explicitly explain the 'id' parameter. It refers to 'an entity' implying the id identifies an entity, but it does not clarify the type (company, person, etc.) or how to obtain it. The description provides minimal semantic value beyond what the schema already shows.

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 an entity's sanctions exposure from specific lists (OFAC/EU/UN/UK) and includes resolved cluster siblings with citations. This distinguishes it from siblings like check_offshore_exposure and search_entities, which focus on different data.

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

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

No guidance is given on when to use this tool versus alternatives such as check_offshore_exposure or find_similar. The description implies a sanctions-specific use case but does not explicitly state exclusions or suggest alternative tools for different risk signals.

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, idempotentHint, and destructiveHint=false, but the description goes further by disclosing the hard caps (depth 3, 300 edges, 25 per entity per direction) and the truncation behavior with `truncated: true`, plus the possibility of normal truncation for hubs. This is valuable beyond annotations.

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, tightly packed with essential information: what it returns, the caps, and the truncation behavior. No filler or redundancy; every sentence adds 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?

The tool is moderately complex with 3 parameters, but the schema covers them well, annotations cover the safety profile, and the output schema is absent. The description explains the output shape (edges, truncation flag) and the expected scale, making it complete for effective use. No gaps identified.

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% (all three parameters have detailed descriptions). The tool description adds context about the edge budget and truncation but does not add semantics beyond what the schema already provides (e.g., formats or constraints). 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 clearly states the tool's purpose: retrieving ownership/control edges within a bounded number of hops, in both directions, from a given entity. It explicitly contrasts with siblings like graph_path and trace_ownership_path by highlighting the bidirectional neighbourhood walk and the hard-capped nature.

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 implies usage for exploring the ownership neighbourhood around an entity, mentioning the direction (both) and the bounded scope. It does not explicitly name alternatives or state when not to use it, but the context signals make it clear for a graph traversal tool, especially given the sibling names.

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 read-only and open-world hints, but the description adds crucial behavioral specifics: the BFS is bounded to 15 edges per entity per direction per hop, the response always carries exhaustive: false, and negative results must not be treated as conclusive. This goes beyond the annotations and is highly informative.

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 concise yet comprehensive, starting with the core purpose, then highlighting the critical bounded limitation with a warning. Uses formatting (bold, emoji) to emphasize key points. Every sentence adds value, with no redundancy or filler.

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

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

For a tool with no output schema, the description covers the algorithm, limits, response flag, and usage caveats. It also notes max_depth performance trade-offs. Given the annotations and schema coverage, the description is fully sufficient for an agent to use the tool 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 provides full descriptions for all parameters, including max_depth constraints and performance guidance. The description adds little beyond the schema—it mentions the bounded nature but does not clarify parameter syntax or formats further. Baseline 3 is appropriate given complete 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's function: it finds how two entities are connected via a bounded breadth-first search over ownership and control edges in both directions. It distinguishes itself from siblings by specifying the graph traversal algorithm and the bounded nature, which differentiates it from graph_neighbourhood and 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?

Provides clear context on when to use it (to find connection paths) and warns about the bounded nature, implying it should not be used for exhaustive connectivity checks. However, it does not explicitly name alternative tools for exhaustive search or when to prefer 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?

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds context about the meaning of tiers and a cautionary note to read before claiming ownership, but it does not introduce new behavioral details beyond what annotations already cover.

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 detailed but well-structured, using separators to break down tier definitions. It is somewhat long but remains focused and informative, avoiding unnecessary 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?

With no parameters and no output schema, the description explains the meaning of each tier and the distinction between deep and indexed links, which is sufficient context for understanding the tool's output. It does not need to explain return values further.

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 no parameters, so the baseline is 4. The description does not need to explain parameters, and none are missing.

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 provides an asset-ownership coverage map, specifying asset types (plane, yacht, property) and how ownership links are held. It distinguishes itself from list_jurisdictions by targeting physical assets, making its 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 mentions it is a companion to list_jurisdictions for physical assets, implying when to use it. It also explains the tier meanings (deep, indexed, on_demand, community) to guide users in interpreting the coverage, though it does not explicitly contrast with other tools beyond list_jurisdictions.

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 adds substantial behavioral context beyond the readOnly/openWorld/idempotent annotations: tier semantics, the meaning of empty results for subset rows, and the 'procured from source' behavior for on_demand jurisdictions. This prevents misinterpretation of absence as non-existence.

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 it is front-loaded with the purpose and organized with backtick-delimited field definitions and concrete examples. It is dense rather than padded, though it could be tightened without losing meaning.

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

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

No output schema exists, so the description must explain the return shape, and it does: '{ jurisdictions, count, tiers, note }' plus every row's tier/scope/depth/registry semantics. The nuanced coverage concepts are fully explained with examples, making the tool self-contained.

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 are zero parameters and the schema is empty, so the baseline is 4; no parameter documentation is needed. The description instead documents the returned row fields and semantics, which is useful context beyond the empty 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 description opens by defining the tool as 'The WhiteIntel coverage map — every jurisdiction we hold and HOW we hold it,' with a clear scope of returning jurisdictions and their tier/scope/depth. This is a specific, resource-oriented definition that distinguishes it from query/search siblings.

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

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

It explicitly instructs 'Read this before telling anyone a country is or is not covered' and then explains the three coverage meanings to prevent misuse. It also clarifies that per-record price/vendor is not exposed, setting boundaries for what this tool should not be used for.

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

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

readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already cover the safety profile. The description adds modest extra context by noting the br-cnpj scheme accepts an 8-digit root or full 14-digit value. However, it does not disclose not-found behavior, whether the resolved entity is returned in full or just an entity ID, or any other 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 a single dense sentence that leads with the primary verb, then delivers the essential scoping (registries and one value nuance). There is no filler or repetition of schema properties; every token contributes meaning.

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 lookup tool with 2 parameters and full annotations, the description is mostly complete. The main gap is the lack of an output schema or any statement about what 'resolve' actually returns (entity metadata, ID, or dossier), and no explicit fallback guidance when the identifier is not found. Given the sibling contract, a little more detail would be warranted.

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 0%, so the description has some burden to explain parameters. It duplicates the scheme enum and only adds meaning to the value parameter for br-cnpj. It does not explain format expectations for other schemes, but because the enum is explicit and value is a natural string identifier, the parameter guidance is minimally adequate.

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 ('Resolve') and resource ('a corpus entity'), then tightly scopes the operation by enumerating the accepted identifier schemes. This clearly differentiates it from sibling search/get tools and makes the tool's single job 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?

The phrase 'strong identifier' plus the full list of accepted registries gives clear context: this tool should be used when the caller already holds a known registry identifier. It does not explicitly mention when not to use it or point to alternatives like resolve or search_entities, but the intent is strongly inferred.

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, idempotent, and non-destructive behavior. The description adds useful context by specifying the input is a Companies House number and that output includes both a record and a ready-built ownership graph, going beyond the schema.

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 sentence that front-loads the scope ('UK company'), the key input ('Companies House number'), and the output. Every element carries meaning with no waste.

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 single parameter, supportive annotations, and straightforward lookup nature, the description covers the core workflow adequately. It does not detail the ownership graph structure or error behavior, but for this simple tool the level is sufficient.

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 defines 'number' as a string with no description, and coverage is 0%. The description compensates by identifying it as a Companies House number, giving the agent the essential semantic needed to invoke the tool 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 clearly states the tool returns a UK company record and a ready-built ownership graph for a Companies House number. It distinguishes itself by the specific identifier type and the ownership graph output, though it does not explicitly name sibling 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 description implies use when you have a UK Companies House number, which narrows the context. However, it gives no explicit guidance on when to prefer this over siblings like lookup_by_identifier or get_company_details, and does not state exclusions.

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

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

Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds critical behavioral detail: it debits €2 from the wallet, is idempotent per (buyer, entity) with no second charge on retry, and returns HTTP 402 with a payment requirement and top-up URL if the balance is insufficient. It also clarifies the agent earns spending ability after a human top-up. This goes well beyond the annotation hints and fully discloses the side effects and error states.

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 typical but every sentence serves a purpose: purpose, payment mechanism, idempotency, error handling, and alternative tool routing. It is front-loaded with the primary goal and structured logically, making it easy to parse. No fluff; each detail is essential for correct invocation.

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 purchase tool with no output schema, the description covers all necessary aspects: what it does, what it returns, side effects (payment), idempotency, error handling, prerequisites, and related tools for obtaining input. The guidance on 402 handling is especially complete, telling the agent to hand top-up to a human and then retry. 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?

The single parameter 'id' is well-described in the schema ('Entity id (uuid) from search_entities / resolve.') with 100% schema coverage. The description reinforces this by repeating the source of the id, which adds helpful context about where to obtain it. While the schema already covers the semantic meaning, the description adds a pointer to the upstream tools, which is valuable for agent usage.

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: 'BUY the full dossier for one entity programmatically' with specific details on what is returned (premium dossier with UBO chain, financials, etc.). It also distinguishes itself from the sibling tool buy_dossier by labeling this the 'AGENT-NATIVE purchase path' versus the 'human/browser path'. This makes it unmistakable what the tool does and how it differs from alternatives.

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: it explains when to use this tool (agent purchases) and the alternative (buy_dossier for human/browser), how to get the id ('from search_entities / resolve'), and error handling instructions (top-up and retry). It also sets prerequisites ('Requires a funded API key'). This leaves no ambiguity about when and how to invoke it.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds valuable context: it returns entity ids + confidence, supports up to 25/100 queries, and mentions the result is canonical. Since the description aligns with annotations and adds rate/scale constraints, it goes beyond the structured data. However, it does not explain failure behavior or partial errors, which could be a 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?

The description is compact yet information-dense: it opens with the core verb + resource, lists schemes, states the outcome (canonical ids + confidence), gives a motivating use case, and mentions rate limits. Every sentence serves a purpose, and it is appropriately front-loaded with the key capability.

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 (one parameter, schema covers it fully, annotations cover safety and idempotency), the description is sufficiently complete for an agent to invoke correctly. It covers purpose, schemes, batch nature, limits, and output. Missing details like error handling or response format are minor because there is no output schema, but the description gives the essential outcome ('canonical ids + confidence') to compensate.

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 has one parameter 'queries' with 100% description coverage ('Names or scheme:value identifiers'). The description adds the list of allowed schemes and batch semantics, which is helpful but not deeply beyond the schema. The baseline of 3 applies because schema coverage is high and the description adds minimal but useful additional meaning.

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

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

The description is highly specific: it states the tool batch-resolves company names or scheme:value identifiers to canonical entity IDs with confidence, and explicitly mentions supported schemes. It clearly distinguishes from siblings like lookup_by_identifier (likely single) and search_companies (likely search-oriented) by emphasizing batch and canonical resolution.

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 clear when-to-use context (enrich a whole supplier/counterparty list, avoid one lookup per row) and hints at limits (25 anon / 100 keyed). It does not explicitly name alternatives for when not to use it, but sibling context and the phrase 'ONE call' imply batch vs single use. Could be more explicit about fallback to single lookup tools.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context beyond the annotations: the search is UK Companies House-specific, uses free-text input, and returns a registration number. It does not contradict the annotations.

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, focused sentence that states the search scope, input type, and output. Every word contributes meaning, and it is front-loaded with the primary 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?

The tool has no output schema and zero schema documentation for its parameters. While the description covers the main purpose and output, it omits limit semantics, result shape, and pagination or return-list behavior. This is adequate for a simple read-only search tool but not 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?

Schema description coverage is 0%, so the description must compensate. It implies q is the free-text company name, but the 'limit' parameter is entirely undocumented in both the schema and description. This leaves a meaningful gap in parameter understanding.

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 the tool: it performs a free-text UK Companies House company-name search and returns a registration number. This distinguishes it from siblings like search_entities or lookup_by_identifier by specifying the jurisdiction, scope, and output.

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 implies when to use the tool—when you need to search for a UK company by name—but it does not explicitly state when not to use it or mention alternatives. With many sibling tools available, there is no direct comparison or exclusion 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, idempotentHint=true, and destructiveHint=false. The description adds meaningful extra context by stating that the search covers all node types and that the output is intended for downstream dossier/ownership tools. It does not contradict annotations. Details about ranking, match behavior, or pagination are absent, but the added purpose context goes beyond annotation defaults.

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 short sentences, with the main action front-loaded. Every clause earns its place: the scope and the return-value purpose are both conveyed without redundant language or 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?

The description captures the core purpose and return-value use case, which is enough for a simple search tool. However, with 5 parameters (including 2 enums), no output schema, and 0% schema description coverage, there are meaningful gaps about filtering, result limits, and formatting that an agent would need to invoke the tool correctly in edge cases.

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

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

Schema description coverage is 0%, and the description only mentions 'by name', which maps loosely to the q parameter. The other five parameters (risk, type, juris, limit) are completely unexplained in both the schema and description. For a tool with this many parameters and no schema descriptions, the description fails to compensate for the coverage gap.

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') plus a precise resource scope ('every node in the corpus — companies AND people — by name'), clearly distinguishing it from sibling search_companies and lookup tools. It also explains the intended downstream use ('Returns entity ids for get_dossier / trace_ownership_path'), reinforcing 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 implies clear usage context: use this tool to find entity IDs for get_dossier/trace_ownership_path and to search across both companies and people. It does not explicitly list exclusions or compare with alternatives like search_companies or semantic_search, but the scope statement provides an implied when-to-use boundary that is useful to an agent.

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?

While annotations already include openWorldHint=true ama, the description adds critical transparency: the exact coverage level ('~1.9% and growing'), the fact that a lack of results is NOT proof of unknown entity, and the need to pair with lexical search. This goes beyond what annotations convey, providing actionable behavioral 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 three concise sentences: purpose, capabilities, and critical caveat. It front-loads the core function, adds the key limitation (partial coverage), and gives actionable advice (pair with lexical search). 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 complexity and the presence of openWorldHint in annotations, the description adds essential context about partial coverage (~1.9%) and explicitly tells users not to interpret empty results as absence. It mentions filters but doesn't detail output format; however, no output schema is providedaint necessary for a search tool. Overall, it's complete enough for confident use.

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 0%, so the description must explain parameters. It mentions 'Optional kind + jurisdiction filters' but does not clarify the meaning or allowed values of 'kind' or 'jurisdiction', and completely omits the 'k' parameter. The 'query' parameter is implied but not explicitly described. This leaves the agent guessing about the parameter semantics beyond the names.

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 it's a 'Meaning-based entity search' using vector embeddings (BGE-3) over 'resolved dossier cards', distinguishing it from lexical searches. It specifies the resource (companies/people) and the semantic nature. It also contrasts with search_entities (lexical/name), making its unique 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?

Explicitly states when to use (when keyword match fails) and provides direct alternative guidance: 'pair with search_entities (lexical/name) before concluding an entity does not exist.' It also flags partial coverage, telling the agent not to rely solely on this tool for absence conclusions. This is exemplary usage 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 (readOnlyHint=true, destructiveHint=false, etc.) already establish this is a safe read operation, and the description is fully consistent with them—no contradiction exists. The description adds a modest behavioral detail by clarifying the traversal direction (upward) and the terminal concept ('ultimate beneficial owner(s)'), which goes beyond the tin name. However, it does not disclose behavior around cycles, max_depth enforcement, or how incomplete ownership stakes are handled, so it adds limited incremental context for a graph walk 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?

One sentence of roughly 15 words, front-loaded with the verb, and every word earns its place by communicating direction (upward), starting point (root entity), and endpoint (beneficial owner(s)). Zero fluff or filler.

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

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

For a relatively simple 2-parameter flat tool with no nested objects and no output schema, the description covers the essential mechanism adequately, and the rubric notes the description needn't explain return values without an output schema. However, given the graph-traversal nature of the tool and the existence of similarly-shaped siblings (graph_path, graph_neighbourhood), the description misses key operational details like default depth, cycle handling, and the threshold for 'beneficial owner'—details that would materially affect agent behavior.

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

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

Schema description coverage is 0%, so the description was expected to carry the full explanatory burden for the parameters, but it only loosely echoes the word 'root' from the schema without explaining what a valid root value is or what the 'max_depth' parameter does, its units, or default. A tool that includes both an unbounded 'root' and an optional numeric 'max_depth' leaves real ambiguity (e.g., direction of depth, default behavior when absent) that the description fails to resolve. The description adds almost no parameter-level meaning beyond the schema's bare type declarations.

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 uses a specific verb ('walk') plus a clear resource ('ownership... upward from a root entity to the ultimate beneficial owner(s)') with a directional scope (upward) and a defined terminus (beneficial owners). This is a clear statement of purpose that incidentally differentiates the tool from the sibling `graph_path` (generic pathfinding) and `get_entity` (single-entity lookup), though it doesn't name alternatives. The language is specific enough to avoid confusion with most siblings.

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

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

No explicit when-to-use guidance, exclusions, or named alternatives are provided despite a rich sibling context (graph_path, graph_neighbourhood, find_similar) where such guidance would be valuable. The 'walk upward' phrasing weakly implies a use case (finding ultimate corporate ownership), but there is no statement about when NOT to use this tool or which sibling would be a better fit, leaving the agent to guess between this and graph_path.

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