De nombre a CIF

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

Annotations already cover readOnly/idempotent/openWorld, and the description adds genuinely new behavioral facts: the result taxonomy (match / ambiguous / no_match), the billing rule that only 'match' consumes a query, and the required plan tier. These quota and plan details are not derivable from annotations or schema and materially affect how the agent batches calls.

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?

Four short, front-loaded sentences with no filler: capability, result semantics, cost/plan constraint, use case. Every sentence carries information the agent needs.

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?

With no output schema, the description adequately covers the shape of results (match/ambiguous/no_match) plus quota and plan constraints, so an agent knows what to expect. The only gap is the absence of routing guidance against sibling tools, which is minor given the strong capability and cost disclosure.

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 both parameters are already documented (names and the province tie-breaker). The description only restates the 100-item cap, adding nothing new about the parameters themselves; baseline 3 is appropriate when the schema does the work.

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?

States a specific verb (find), a precise resource (CIF), and the input scope (a list of company names, up to 100). This is clearly distinguishable from siblings like get_company (lookup by identifier) and search_companies (fuzzy search), so an agent can select it without opening the schema.

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?

It names a concrete use case ('útil para completar hojas de clientes') and a hard precondition (Pro plan or higher), giving the agent clear selection context. However, it never states when NOT to use it or which sibling to prefer (e.g. get_company when you already have the CIF), leaving alternatives to inference.

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