investigate_entity

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

With no annotations provided, the description carries full burden and does well at disclosing behavioral traits. It explains the multi-step process, clarifies that it 'returns data only — no risk judgments' (important behavioral constraint), mentions that the AI should interpret results, and notes it requires specific parameters for better precision. It doesn't cover rate limits or authentication needs, but provides substantial 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 appropriately sized and well-structured with clear sections: purpose statement, steps, output behavior clarification, and parameter guidance. Every sentence earns its place, though the final sentence about additional properties could be slightly more concise. It's front-loaded with the core purpose and effectively uses bullet-like formatting for the steps.

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 (8 parameters, multi-step investigation) and lack of both annotations and output schema, the description does a good job of providing context. It explains the investigation process, clarifies the AI's role in interpretation, and provides parameter guidance. The main gap is the absence of output format details, which would be helpful since there's no 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?

Schema description coverage is 100%, so the baseline is 3. The description adds some value by explaining that 'additional properties like birthDate or nationality' improve match precision and that both name and schema are required, but doesn't provide significant semantic context beyond what the schema already documents. It mentions threshold and max_matches defaults but these are already in the 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 clearly states the tool's purpose: 'Run a multi-step compliance investigation on a person or company.' It specifies the exact steps involved (matching, fetching details, relationship traversal) and distinguishes it from siblings by calling it 'the most powerful tool' that combines multiple functions in one call, unlike simpler tools like get_entity or match_entity.

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 clear context for when to use this tool: for comprehensive compliance investigations that require multi-step analysis. It mentions that it 'combines matching, entity details, and relationship traversal in one call,' suggesting it should be used instead of calling multiple simpler tools separately. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the siblings.

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