Resolve PSC ownership chain to find ultimate beneficial owners

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 recursive traversal behavior, the full set of terminal_reason values, including nuanced meanings for unverified_registry and unknown_kind, and details ECCTA identity verification fields with explicit warnings about pending not being a failure and never describing companies as having unverified identity. This goes far beyond a simple description, covering output structure and edge-case semantics.

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 starts with core purpose, enumerates terminal reasons, flags misinterpretations, details ECCTA fields, and closes with use cases. The structure is logical—purpose, behavior, caveats, use—without redundancy. It is dense with information and properly 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?

Given the tool's complexity (recursion, multiple termination reasons, ECCTA status handling) and the absence of an output schema, the description covers all essential information: the tree structure, node fields, terminal_reason semantics, verification status meaning, and chain_metadata. It even pre-empts likely agent missteps. Nothing an agent needs to call or interpret the tool is missing.

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

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

Schema coverage is 100% for both parameters; the schema already documents max_depth's range and per-company cost, and company_number's pattern and padding rule. The description adds no additional parameter detail beyond what the schema provides. The baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description opens with a specific verb-resource pair ('Trace the full ownership chain') and immediately distinguishes itself from the immediate-PSC sibling by stating it returns a tree of ultimate beneficial owners. It explicitly contrasts with 'beyond the immediate PSC layer,' so an agent can tell it apart from get_psc without opening either schema.

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

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

The final sentence states explicit use cases ('KYB checks, AML screening, or any task requiring beneficial ownership beyond the immediate PSC layer'), which both says when to use it and implicitly when not to (for immediate PSC layer). It also lists the terminal_reason values and clarifies their interpretation, so an agent knows when the tool is appropriate.

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