run_pt_companies_search

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

No annotations are provided, so the description carries the full burden, and it discloses one genuinely useful behavioral trait: the '2 point per returned record' credit cost, which the schema does not mention. Beyond that it says nothing about permissions, rate limits, or how pagination interacts with cost, so the behavioral profile remains thin for a tool with zero annotation coverage.

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?

Compact, front-loaded with the verb and resource, and the cost note is a short trailing clause. The middle list ('name, NIF/NIPC, municipality and the date and type...') is slightly tangled because it reads as a facet list but is actually output fields, costing it the top score.

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 only 3 parameters at full schema coverage and no output schema, the description helpfully sketches the return fields, which partly compensates for the missing output schema. But it omits the pagination model (25 per page) that an agent needs to iterate results, and gives no guidance on sibling selection, leaving it only adequately complete.

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 schema already documents keyword, max_items, and start_page, which sets the baseline at 3. The description's phrase 'by entity name' loosely reinforces that keyword is a name, but it muddies this by listing NIF/NIPC and municipality, which are not input parameters — it adds little clarity beyond the schema.

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?

Names a specific verb and resource ('Search the Portugal company registry') and even enumerates the returned fields (name, NIF/NIPC, municipality, newest publication date/type). However, it does not distinguish this tool from its close siblings run_pt_companies and run_pt_company_filings, so an agent cannot tell from the description alone which Portugal variant to pick.

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?

There is no statement of when to use this search variant versus the sibling run_pt_companies or run_pt_company_filings, and no prerequisites or exclusions. The reader must infer usage from the tool name alone.

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