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

No annotations are supplied, so the description carries the full disclosure burden, and it only establishes that this is a search and that country code is mandatory. It says nothing about what 'linked to' means (linked entity types vs. text matches), result caps, pagination defaults, or whether the call is read-only. The trailing '### Responses: 200' block is raw OpenAPI boilerplate that conveys no behavioral information.

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 first two sentences are tightly front-loaded and waste nothing. The appended formatted response block is filler that a reader must mentally discard, which keeps it from a 5.

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?

This is a six-parameter search tool with no annotations and no output schema, so the description is the only place to learn about pagination, date-range filtering, and return shape — and it covers none of them. An agent knows what to search for but not how results come back or how many.

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 67%, with gte/lte and page/page_size documented in the schema itself, so the baseline is 3. The description reinforces the country_code requirement but adds no meaning about format, interaction between gte/lte and the phone filter, or how page_size behaves.

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 ('Search Vysion for documents') plus the linking criterion ('containing or linked to a phone number'), which cleanly separates it from siblings such as get_documents_by_email or get_documents_by_wallet. It stops short of explicitly naming an alternative, but the resource and pivot field are 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 'Use for OSINT investigation' clause implies a domain of use, and 'Requires country code' gives a hard prerequisite. There is no guidance on when to prefer this over search_documents or the other pivot-based document lookups, and no exclusions or caveats about partial matches.

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