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

With no annotations provided, the description carries the full burden and does so extensively. It discloses the data source (ONRC Open Data), aggregation logic by name and birth data, structural exclusion of UNRESOLVED clusters, anonymous vs authenticated access limits, confidence tier semantics, credit cost for get_person, and the GDPR constraint that no CNP is returned. This goes far beyond a basic operation description.

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 well-organized with clear headers, bullet lists, and bolded keywords. Almost every section earns its place given the complexity of auth tiers, confidence levels, and disambiguation rules. The opening keyword block is somewhat repetitive, but the overall structure makes the detail navigable rather than overwhelming.

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 must explain return values and behavior, and it does. It lists anonymous result fields (name, companyCount, profileUrl) and authenticated fields (birthYear, knownCounties, occurrenceCount, confidence), explains default sort behavior, and covers cost, access, disambiguation caveats, and follow-up via get_person. Nothing essential for correct invocation 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%, so the baseline is 3, but the description adds meaningful context by explaining how filters like county and birthYearFrom/To are used for disambiguation and by clarifying that minConfidence filters out lower tiers. It also maps anonymous vs authenticated limits to the limit parameter and directs users away from legacy page/pageSize aliases.

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 clear verb-and-resource statement: 'Caută o persoană fizică ... și află în câte firme românești apare.' It also distinguishes itself from get_person, which is the follow-up for full profiles, and from related search tools like search_companies and search_cities. The keyword block and role enumeration (administrator, asociat, lichidator) further specify the exact domain.

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 'CÂND îl folosești' section provides explicit, concrete use cases with complete workflows, such as 'În câte firme apare X?' followed by 'get_person', and conflict-of-interest checks via company taxId. It also explains when to filter by county or birth year to reduce candidates before spending credits, effectively giving both when-to-use and when-to-defer guidance.

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