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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context beyond annotations by stating the API key requirement and enumerating the categories of returned data, including names, addresses, identifiers, sanctions programs, and related entities.

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 tight sentences with no filler: the core purpose is front-loaded, followed by return value highlights and the critical API key requirement. Every sentence contributes necessary 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?

The tool is well-covered by the annotations (read-only, idempotent) and has an output schema, so the description does not need to explain return payloads. It covers the required inputs, authentication, and result scope; a minor gap is not explicitly pointing to search_entities or resolve_entity for cases where the ID is not yet known, though this is implied.

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 both parameters with 100% coverage, including an example ID and a detailed explanation of the _apiKey field. The description adds no additional parameter semantics, so the baseline score 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?

The description states a specific verb and resource: 'Get full details for a sanctioned entity by its OpenSanctions ID.' It clearly conveys that this is a by-ID lookup returning comprehensive properties, which distinguishes it from search-oriented or comparison siblings like search_entities, resolve_entity, and compare_entities.

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 the correct use case: when you already have an OpenSanctions ID and need full entity details. The _apiKey parameter description adds an explicit alternative for keyless scenarios, directing users to the sanctions_screen pack, which provides a when-not-to-use signal.

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