apifirme

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the bar is lower. The description adds real context beyond them: results are cached and re-queried at ANAF when the stored answer is older than a day, which tells the agent how fresh the data is. It omits any mention of failure modes (invalid CUI, company not found) or latency.

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?

Two sentences, front-loaded with the use case and then the enumerated checks; nothing is padding. The trailing caching clause is terse to the point of awkwardness ('Asked again at ANAF...') but still earns its place and survives compression.

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 one well-documented parameter and rich annotations, the main gap would be return values, and the description effectively lists them by enumerating the flags checked, compensating for the absent output schema. Only error/edge-case behavior is left unaddressed.

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 CUI format (with or without RO prefix, example values) is already fully documented in the schema. The description adds only the framing that the target is a Romanian company, not new syntax or constraints. Baseline 3 is appropriate.

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?

A specific verb ('check') plus a resource (Romanian company), and the description enumerates exactly what is verified: existence, VAT registration, TVA la încasare, fiscal inactivity, struck-off status, and RO e-Factura. This is far more informative than sibling names like lookup_company or find_company, though it never explicitly says how it differs from them.

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 pre-invoicing context is stated up front ('The check before issuing an invoice to a Romanian company'), which is a clear when-to-use signal. It offers no explicit exclusions or named alternatives among the sibling tools, so the agent must infer when find_company or lookup_company would be preferable.

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?

The annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, so the description carries less burden. It adds the useful access note 'Included in every plan' and restates the recent-registration scope, but it does not discuss return format, rate limits, or other behavioral details beyond that.

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?

Two sentences are used efficiently: the first front-loads the core count purpose and optional filters, and the second adds a short access note. There is no filler or repetition.

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 simple read-only count tool with rich schema descriptions and safety annotations, the definition gives enough context to invoke it correctly. The main missing context is explicit routing against the closely related list_new_companies sibling.

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 input schema already documents all four optional parameters in detail. The description names the same filters in prose but adds no syntax, defaults, or interpretation beyond what the schema provides.

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 clearly states a count operation over newly registered companies and sole traders in Romania within a recent time window. The verb is implicit in 'How many' and the resource and scope are specific, but it does not explicitly distinguish the tool from the sibling list_new_companies.

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 implied usage context by stating that the count can be narrowed by CAEN field, county, and natural-person status. However, it does not say when to use this tool instead of list_new_companies or other siblings, and it offers no explicit exclusions or prerequisites.

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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds substantial behavioral detail beyond them: a cap of 10 results, ordering with active companies first, the `more` truncation flag, and the exact fields returned. It also clarifies that sole traders and liberal professions are included, which preempts a plausible misassumption.

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 format, then return shape, then the `more` caveat — a logical order with no filler. It is a dense single paragraph, however, and the 'F numbers are sole traders'' aside plus the closing sentence about sole traders/liberal professions slightly overlap concepts that could be merged.

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 carry the return-value burden and it does: result count, ordering, and per-entry fields. With annotations covering safety and the schema covering all three parameters, nothing material is missing for correct invocation.

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 baseline is 3; the description goes further by stating the either/or constraint between name and register_number and that `judet` is optional and only meaningful alongside a name. It does not repeat the register-number format detail, which is already in the schema, but the cross-parameter constraint is genuinely additive.

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 ('Finds a Romanian company') and pins the distinguishing condition in the title and first clause: when the CUI is unknown, search by name, partial name, county or register number. That cleanly separates it from lookup_company and the other siblings.

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 selection criteria: use this when the CUI is unknown, 'Give either name or register_number', and hand the returned CUI to the other tools. It also prescribes the follow-up when `more` is true — ask the user for the county or a more exact name instead of guessing — which is exactly the disambiguation guidance an agent needs.

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 this as a safe, idempotent read-only operation, so the description adds useful context beyond that: it lists the event categories observed, states that results are newest-first, and says the list is empty if nothing was observed. It does not describe event record shape or pagination, but it meaningfully improves behavioral transparency.

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 a single, information-dense sentence with no filler, and it front-loads what the tool returns. The long event-type list is slightly dense but each item helps clarify the scope.

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 one-parameter read-only tool with full schema coverage and no output schema, the description is largely complete. It covers scope, event types, ordering, and empty-result behavior, though it could say more about the shape of returned event records.

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 the single CUI parameter is fully documented in the schema, including accepted RO prefix formats. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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 resource (company change events) and temporal scope (since tracking began), and enumerates the event types covered. It does not explicitly distinguish itself from sibling tools, but the resource is clearly different from company lookup, financials, invoices, and FX rate tools.

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?

Usage is implied: an agent would use this to see what changed at a tracked Romanian company. However, there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternatives or prerequisites.

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 establish read-only, idempotent, closed-world behavior, and the description adds real context beyond them: provenance (Ministry of Finance from 2008, with ANAF filling gaps) and units ('whole lei (RON)'), which prevents unit misinterpretation. It does not mention pagination or how large multi-year responses behave, keeping it below a 5.

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?

A single dense sentence front-loads the resource and scope, with no filler; every clause (source, window, field list, units, year behavior) carries information. The parenthetical about ANAF gaps is slightly convoluted and costs a bit of readability.

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 2 parameters, full schema coverage and annotations, the description does the remaining work well: it names the source systems, the historical coverage, and the returned metrics (turnover, profit, assets, debts, equity, employees), which compensates for the absent output schema. Only return shape/row-per-year structure is left implicit.

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 both parameters are documented there (CUI with/without RO prefix, year with 'Without it, all years'). The description only restates the year default ('All years, or one'), adding no new semantics 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?

A specific verb+resource ('annual financial statements of a Romanian company') plus the exact source (Ministry of Finance, supplemented by ANAF), coverage window (from 2008 on) and the fields returned. An agent can distinguish this from find_company/lookup_company, which identify companies rather than return their statements.

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?

Usage is implied by the required CUI and the 'All years, or one' phrasing, but the description never states when to pick this over siblings like get_company_events or check_invoice, nor prerequisites (e.g., that the CUI must be known first).

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, so the safety profile needs no restating. The description adds genuinely useful behavior beyond them: the default-to-latest behavior, the RON-per-unit direction of the rate, and the 2005 archive boundary. It doesn't describe the response shape, which is the main remaining gap.

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?

Three short sentences, each carrying distinct information: unit and scope first, default second, data range third. No filler or restatement of the title.

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 carries the burden of explaining return values; it implies a per-currency rate mapping but doesn't state whether results come as a list, object, or single value. Otherwise complete for a two-optional-parameter read 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 both the date format and the currency-code semantics are already documented in the schema. The description reinforces the unit (RON per unit) and the all-vs-one behavior, but adds no syntax or format detail beyond the schema. Baseline 3 applies.

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 BNR reference exchange rate, expressed in RON per unit of currency, for either all currencies or a single one. The scope and unit are precise enough that an agent can distinguish it from every sibling (invoice, company, financials tools) without inspecting 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 the default behavior ('By default the latest published') and the data boundary ('archive starts in 2005'), which tells the agent when the tool is applicable and what range it can serve. It doesn't name a fallback or alternative, but no sibling covers exchange rates, so there is nothing to route against.

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 the safe read/idempotent profile, and the description adds genuinely new behavioral context: the subscription-tier gating and the indexing order. It does not mention result freshness windows or pagination behavior, but the plan restriction is exactly the kind of pre-call constraint the annotations cannot express.

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?

Two compact sentences: the first front-loads what the resource is and its ordering, the second carries the conditional usage constraint. No filler, though 'the most recently indexed last' is slightly dense phrasing.

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 full schema coverage, no output schema and rich annotations, the description supplies the two things the structured data cannot: the plan gate and the alternative tool. An agent has enough to decide whether it can call this at all; only cross-sibling comparison with the search tools is left implicit.

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 every parameter including the intricate persoana_fizica caveat is already documented in the schema. The description only restates the filter dimensions (CAEN, county, natural persons) without adding syntax or defaults, which matches the baseline-3 case where the schema does the heavy lifting.

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 the specific resource (newly registered companies and sole traders in Romania), the ordering ('most recently indexed last') and the optional filters, which is far more than the title provides. It does not, however, distinguish itself from siblings like find_company or lookup_company, so the agent must infer that this is a recency list rather than a search tool.

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 description explicitly states the plan prerequisite ('Only on the plans that include the list') and names the sibling that works universally ('count_new_companies works on every plan'), which is a real routing rule. It gives no guidance on when this list is preferable to find_company or lookup_company for a given company.

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/openWorld=false, so safety is covered; the description adds genuinely new behavioral context — data provenance per register (ONRC, ANAF, Ministry of Finance) and freshness/date of the Ministry of Finance yearly list. It stops short of describing response shape or failure modes for unknown CUIs.

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 core purpose, but the opening sentence is a sprawling comma-list of fields and the second sentence is dense with register/provenance detail. Information is useful but poorly chunked, making it slower to scan than it needs to be.

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 carries the burden of explaining return contents, and it does so thoroughly (fields, provenance, as-of dates, natural-person handling). Complete enough to call correctly, though it omits error/not-found behavior.

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 single parameter is fully documented there, including the RO-prefix variants. The description mentions CUI as the key but adds no format or edge-case detail beyond the schema, so baseline 3 applies.

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 ('look up a Romanian company by fiscal code') and enumerates the returned fields, so the agent knows exactly what it gets. It implicitly distinguishes from find_company (search vs. exact CUI lookup) but never names siblings explicitly.

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?

Usage is implied by 'by its fiscal code (CUI)' and by the note that sole traders/liberal professions resolve the same way, but there is no explicit when-to-use vs. find_company/check_invoice guidance nor any stated exclusions or prerequisites.

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