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

Well beyond the readOnlyHint/openWorldHint annotations: it discloses geographic scope (Texas only), data provenance (Texas Comptroller or TABC), refresh cadence (nightly), and a critical epistemic caveat ('inferred links, not ownership records'). It also characterizes what the two relationship categories mean (common control vs. handover/sale), which prevents misreading the results.

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

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

The answer returned is front-loaded and the caveats follow, with a concrete example at the end. It is dense — nested parentheticals and a long second sentence — but essentially every clause carries distinct information about outputs or limitations.

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

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

There is no output schema, so the description carries the full burden of describing returns (relation_type, confidence, evidence, took_over_from/taken_over_by, dates) and it does so. Scope, provenance, refresh, and the inferred-not-ownership limitation round out what an agent needs to call and interpret this 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 description coverage is 100%, with both entity_id formats and the min_confidence range/default already documented in the schema. The description adds no extra meaning for the parameters themselves, so the baseline of 3 applies.

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

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

Opens with the exact question the tool answers and names the resource: other entities under common control, plus predecessor/successor handovers. It distinguishes itself from get_entity/resolve_business by framing an inference task (affiliate discovery) rather than a 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?

Framing the tool as the answer to 'which other entities are likely under common control' gives clear context for when to reach for it, and the entity_id provenance (from resolve_business) is stated. It doesn't explicitly exclude cases (e.g. use get_locations when you want a single address, or get_entity for direct record data).

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