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

Annotations already cover read-only/idempotent safety, but the description adds substantial context beyond them: the 1987 archive boundary, that links come from holder-name matching rather than tax IDs, that ambiguous holders remain unlinked, and above all the epistemic caveat that a hit is a name match not confirmed ownership and that found=false is not proof the brand is unused. Auth and plan requirements plus 'one request per call' are also disclosed.

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?

Front-loaded with purpose, then routing, then return shape and caveats, then auth. Dense but nearly every sentence carries decision-relevant information; the return-schema field enumeration is the one segment that runs long for a tool with no output schema.

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 supplies the return JSON shape including truncated, source and note, explains the kind discriminator semantics, and pre-empts the two most likely misinterpretations (name match vs ownership, found=false vs unused). Nothing needed to call or interpret it correctly 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 description coverage is 100%, so the schema already documents both the brand string (minimum length, case-insensitivity, partial matching) and the limit range. The description adds no further parameter detail, which is acceptable at full coverage but leaves this at baseline.

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 and resource ('find the Spanish company a trademark or trading name is linked to') and names the exact data source, OEPM trademark and commercial-name records since 1987. It explicitly differentiates itself from two named siblings by input type.

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?

Gives an explicit trigger ('when the user names a brand') and routes two adjacent cases elsewhere: company's own name to search_companies, known company's brands to company_brands. It also adds a follow-up path ('On a hit, use company_history with the slug'), so the agent knows what to do next.

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

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

Beyond the readOnly/idempotent annotations, it discloses the plan gate (basic or higher), the X-API-Key header, one request per call, and the critical caveat that links are name matches rather than confirmed ownership since OEPM publishes no tax IDs. It also explains empty-result semantics, per-kind limits, and what truncated means.

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?

Purpose is front-loaded, followed by usage, return shape, caveats, and access requirements. Every sentence carries information an agent would otherwise have to guess, with no filler or repetition of the schema.

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, and the description fully enumerates the return shape including nested trademark fields. It also covers the truncation/limit interaction and the name-match reliability caveat, leaving no material gap for correct invocation or interpretation.

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 schema already documents both parameters. The description still adds real meaning for limit: it applies per kind, newest first, and truncated=true means raise it. The company parameter gains only the reiteration of the slug source, already in 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?

States a specific verb and resource: lists trademarks and trading names recorded by OEPM under a holder matching the company name. It immediately distinguishes itself from the sibling brand_owner by naming the reverse direction, so an agent can route without opening either 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?

Explicitly says to use it for a known company and where the slug comes from (search_companies or company_history), and names the alternative brand_owner for the opposite lookup. Both the entry condition and the exclusion are stated.

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

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

Annotations already declare readOnly/idempotent, and the description adds genuinely non-inferable context: one request per call, X-API-Key header plus plan requirement, and a coverage caveat (>580,000 mappings, minority of companies) with the crucial semantics that a miss means 'not matched yet', not 'does not exist'. It also decodes each failure reason (invalid_input, nif_check_character_failed, not_registry_entity, ambiguous, nif_caveat) and how to relay it.

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?

Front-loaded with purpose, then alternative, then return handling, then failure modes. It is dense rather than wasteful, though the single paragraph packs many clauses (reason codes, caveats, auth) that could be more cleanly separated.

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?

No output schema exists, so the description must explain returns — and it does, listing the JSON fields, which field to prefer (current_name), and the meaning of each status/reason. For a single-param read tool, nothing an agent needs to call or interpret it correctly 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 description coverage is 100% and already documents the NIF format, length, and accepted separators/prefixes, so the schema carries parameter semantics. The description adds no syntax detail beyond it; its value is in output interpretation, not the input parameter, so baseline 3 is right.

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 and resource ('Look up a Spanish company by its NIF/CIF tax ID') and immediately distinguishes it from the sibling search_companies by input type. An agent can tell it apart without opening any 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?

Explicit routing: use this when the user gives a tax ID, use search_companies when a name is given, and on a hit chain into company_history with the returned company_slug. Both the use case and the alternative are named.

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

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

Annotations already declare readOnlyHint/idempotentHint, but the description goes beyond them: per-call request count, plan-tier windows (7 days anonymous, 365 basic, 2009+ pro/risk), merged-company former_slugs behavior, truncation, the 10000 offset ceiling, and the fact that refusals still count out-of-window events. That is exactly the context an agent needs and no annotation provides.

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?

Front-loaded with purpose, then usage routing, then return shape, then paging, then auth windows — a logical order with dense but information-bearing sentences. Minor redundancy with the schema (offset max 10000, limit/order kept stable) keeps it just short of maximal.

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?

No output schema exists, so the description carries the return contract and does so fully: field list, the fact that total_events/first_seen/last_seen span the whole window rather than the page, truncated/next_offset paging, former_slugs, and plan_window. Combined with the auth tier explanation, an agent has everything needed to call and interpret it.

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 real semantics: a name of at least 3 characters is searched case-insensitively and may return {ambiguous: true, candidates} or {error}, and paging requires keeping limit and order while passing next_offset as offset. It does not restate the limit range or enum-like order values, which is appropriate since the schema covers them.

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 and resource — the BORME registry timeline for one company, events within the plan window — and immediately scopes it against search_events for the multi-company case. An agent can distinguish it from siblings like search_events and company_by_nif without opening any 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?

Explicitly names the precondition ('once the company is known (a slug from search_companies or company_by_nif)') and the alternative ('across many companies use search_events'). It also covers the name-instead-of-slug fallback and what the ambiguous/no-match responses look like.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing the access model (one request per call; without an X-API-Key only the last 7 days, key URL provided) and the empty-day edge case (weekends/holidays return total_events 0). It also flags a real correctness trap: INSOLVENCY_STATUS can represent any stage, so the payload must be read before asserting a company was declared insolvent.

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?

Front-loads purpose, then the alternative, then the return shape, then caveats — a sensible information hierarchy. It is on the long side and the parenthetical enumeration of excluded act types (SUSPENSION_OF_PAYMENTS, BANKRUPTCY_LEGACY, PROVISIONAL_SHEET_CLOSURE_INSOLVENCY) is verbose, though each clause carries real decision value.

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, and the description compensates by spelling out the returned JSON shape (date, total_events, by_type, top_provinces, insolvencies[{company, province}]). Combined with the auth window, empty-day behavior, and the insolvency-interpretation warning, an agent has everything needed to call it and to interpret the result.

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% and the schema already documents the YYYY-MM-DD format and the omit-for-latest default, so the description needn't repeat it. What it adds is behavioral: a day without a gazette yields total_events 0, which helps interpret the parameter's edge cases but doesn't extend the format semantics.

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?

Opens with a specific verb and resource ("Summarise one BORME publication day") and immediately enumerates the exact contents: totals, counts by act type, top provinces, insolvency notices. It explicitly distinguishes itself from search_events, so an agent can route between the two without opening either 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?

Gives explicit when-to-use ("what was published today" or a day's figures) and names the alternative with the exact invocation pattern: to read the notices use search_events with date_from = date_to = that day. That is a concrete hand-off rule, not just a mention of a sibling.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, and the description adds genuinely new operational facts: no key required, no quota consumption, and equivalence to the borme://act-types resource. The safety restatement ('Read-only, open to everyone') overlaps somewhat with the annotations but the quota and auth disclosures are real added value.

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?

Front-loaded with the identity of the list and the return shape, with usage guidance second and access facts last. Slight redundancy in the 'Read-only, open to everyone, no key needed' cluster, but no sentence is wasted overall.

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?

No output schema exists, and the description fully compensates by specifying the return container (JSON array), the field set of each element, and the sort order (by act_type). An agent can call this and use the result without further inference.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a no-param tool applies. The description correctly implies no filtering arguments are accepted.

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 and resource ('List every normalized BORME act type') and pins down exactly what each entry contains (act_type, spanish, english). It also identifies the consumer relationship — this is the enum used by the act_types filter of search_events — which distinguishes it cleanly from every sibling.

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?

Gives two explicit use cases ('choose act_types values' or 'translate act types in an answer') and an explicit non-use signal ('it reads no registry data'), which routes registry-data queries to search_events. The alternative is named directly.

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

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

Beyond the readOnly/idempotent annotations, it discloses the sample cap, the 7-day window, the auth requirement (X-API-Key, risk plan), one-request-per-call, the exact return shape, and subtle semantics: count 0 does not mean risk-free, and an unknown signal_type is refused with the valid list. The AEAT_DEBTOR note adds an important interpretive constraint (report the historical listing, never say the debt is outstanding).

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?

It is front-loaded with purpose and scope before the alternatives and caveats, and every paragraph (return shape, AEAT handling, count-0 semantics, auth) carries information the agent needs. It runs long, but there is little true waste; a slightly tighter AEAT paragraph would be the only trim.

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 takes responsibility by listing the JSON return fields and explaining count/window/sample_cap/full_feed. Combined with the auth note and the AEAT interpretation caveat, an agent has everything needed to call and report results correctly.

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 enum values are already documented in the schema and the baseline would be 3. The description adds value beyond it by explaining rejection behavior for an unknown signal_type, which the schema does not state, plus the omit-for-all-types default implied by the usage guidance.

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 specific verb and resource ("Get a sample of the latest risk signals") and bounds it precisely: at most 10 rows within the last 7 days. It also names the sibling it is not (company_history) and distinguishes itself from the full hosted feed, so an agent can tell it apart from search_events and daily_digest without opening a 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 gives an explicit use case ("what risk signals appeared this week"), two explicit exclusions with the alternative named (per-company check -> company_history; full feed -> /v1/signals), and the plan/auth prerequisite. Virtually nothing about when to select this tool is left to inference.

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

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

Beyond the read-only/idempotent annotations it discloses non-obvious traits: counts are approximate planner estimates rather than exact tallies, the freshness field is event-weighted over the trailing 30 days, and there are no key or quota costs. It even points to the equivalent resource borme://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?

Front-loaded purpose, then usage, then return shape, then access notes — a sensible order with no filler. Slightly long for a single-purpose stats call, and the example value '(e.g. 0.9987)' is borderline unnecessary.

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 compensates by enumerating every returned field and its meaning, including the approximate nature of counts and the date format. Nothing an agent needs to interpret the result 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?

Zero parameters gives a baseline of 4; the description reinforces this with 'Takes no arguments,' which removes any doubt about whether a date range or filter can be supplied. No further parameter meaning is needed.

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+resource ('Report the coverage and freshness of the BORME data') and draws an explicit boundary against the sibling search tools: 'it says nothing about any one company.' An agent can place it among search_companies/search_events/company_* without ambiguity.

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?

Gives concrete triggering questions ('how much data is there?', 'how fresh is it?', 'can I trust date filters for period X?') and a sequencing rule: call it before running searches. It also names what it is not for.

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

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

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description goes well beyond that with free-plan caps (5 cards, hidden_by_plan counting), plan-gated NIF data, ranking order and the 'empty answer is not proof' caveat — but it omits rate-limit/error behavior beyond 'one request per call'. Wait — reassessing: the plan gating, ranking criteria and empty-result caveat are exactly the kind of non-obvious context annotations cannot express, so the score should reflect that added value.

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?

Purpose and routing are front-loaded in the first two sentences, then matching rules, then result shape and plan caveats. Dense but every clause carries information; the inline JSON return-shape block is the only part bordering on verbose.

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?

For a 5-param search tool with no output schema, the description supplies the return shape, ranking logic, plan-driven truncation behavior, match-type interpretation and the failure caveat. An agent can call it and interpret the response correctly without further context.

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. The description still adds meaning the schema does not: match values are 'a lead, not an identification', ranking order (match, active, newest act), and the semantics of truncated. The hidden_by_plan / NIF-plan notes sit outside the parameters but explain result shape, not parameter use.

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 and resource ('Find Spanish companies by name and return ranked company cards') and explicitly distinguishes itself from company_history, company_by_nif and brand_owner by naming each sibling and the input that routes to it.

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?

Gives an explicit when-to-use rule ('Use it first when the user gives a company name') plus three named alternatives with the exact condition selecting each (slug, tax ID, brand). No inference required.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses one-request-per-call quota consumption, the X-API-Key requirement and its 7-day fallback window, the plan_window and hidden_by_plan fields, the absence of pagination, and that invalid dates/provinces/act types are refused with a corrective message. The warning not to report 'none exist' on a hidden_by_plan empty page is a genuinely important behavioral caveat that no annotation conveys.

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?

Front-loaded with purpose, then routing, then return shape, then operational caveats. Every sentence carries distinct information; the inline return-shape listing is not waste because no output schema exists and it is the only place those fields are documented.

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?

Six optional parameters with 100% schema coverage plus annotations, and the description compensates for the missing output schema by documenting the return envelope and conditional fields. Auth requirements, quota cost, window limits, error behavior and empty-result interpretation are all covered, so an agent has everything needed to call and interpret this tool.

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 per-parameter meaning is already carried by the schema; the description still adds cross-cutting semantics the schema does not, notably 'newest first' ordering and the no-next-page rule tying `limit` to a narrowing strategy rather than paging. It does not restate per-parameter formats, which is appropriate given the schema's detail.

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 and resource with scope: 'Search BORME registry events (since 2009) across companies by publication date, province, act type and company name, newest first.' It also explicitly distinguishes itself from three siblings by name, so an agent can route correctly without opening any 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?

Gives an explicit when-to-use example ('questions about many companies') and then routes the other three cases: one known company -> company_history, find a company -> search_companies, one day's totals -> daily_digest. This is the strongest form of alternative-naming guidance.

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