firmy.ai

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: free mode only reads what the service already knows, off-memory sections return 'missing' with AUTH_REQUIRED, and the call costs 0 operations. The only weakness is that the identifier-format sentences describe behavior this zero-parameter tool does not perform.

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 core content (mode, login, free-tier limits, cost) is front-loaded and useful, but the middle segment about 'id' formats and search_companies is irrelevant to a no-argument tool and inflates the text. One sentence of genuinely off-topic material undercuts an otherwise compact line.

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?

An output schema exists, so return values need not be spelled out; the description still covers what an agent needs — mode, auth state, free-tier restrictions, AUTH_REQUIRED behavior, and cost. Only the misplaced identifier discussion keeps it from being fully tailored to this tool's actual surface.

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?

With zero parameters the baseline is 4, but the description explicitly discusses an 'id' argument (KRS/NIP/REGON/address/'p-…'), which does not exist in this tool's schema. This injects parameter-like semantics that could mislead an agent into expecting or supplying an identifier, so it scores below the clean 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?

The opening clause names a concrete verb and resource: returns the operating mode (free or Pro) and login status, plus free-tier usage instructions. This is distinguishable from data-fetching siblings like get_company, though the later sentences about 'id' formats (KRS, NIP, REGON, 'p-…') describe identifier semantics that belong to other tools and muddy the purpose.

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?

'Użyj na początku rozmowy' gives an explicit call condition (start of conversation) tied to a stated goal — knowing whether off-memory sections can be fetched. The additional 'zacznij od search_companies, gdy nie masz identyfikatora' is guidance for a different tool and reads as copy-paste, but the core when-to-use is unambiguous.

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 annotations by disclosing free-mode limitations (sections outside cache return 'missing' with AUTH_REQUIRED), per-section Pro-mode costs, default included sections, and the 'available' map listing additional queryable data. These are critical operational details not covered by annotations.

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 dense and lengthy, repeating the full section list twice and embedding cost details in a long paragraph. It is not front-loaded: the primary purpose is stated only after free-mode edge cases. Bullet points or tighter grouping would improve scanability.

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?

Given the tool's complexity, the description is thorough: it covers usage prerequisites, mode differences, section defaults, cost model, identifier types, and a sample call. An output schema exists, so return values need not be detailed further; nothing crucial 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 baseline is 3; however, the description adds meaningful context by noting that 'id' can also be a person ID ('p-…') and provides a concrete example. It also repeats default include behavior already in the schema, but the extra person-ID and example justify a 4.

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: returns a company profile plus selected sections via 'include'. Distinguishes from siblings by naming search_companies when no identifier exists and acknowledging person IDs ('p-…') that route to get_person.

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 this tool when you have KRS, NIP, REGON, or a firm website address, and to call search_companies first when you only have a name. Also clarifies free vs Pro mode behavior and the purpose of 'estimate' and 'fresh'.

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 annotations, the description discloses important behavior: opted-out people return a GONE error, Pro-mode section costs, free-mode AUTH_REQUIRED/'missing' behavior, default sections when 'include' is omitted, and the presence of an 'available' map. These are concrete operational traits not covered by readOnlyHint/openWorldHint/idempotentHint.

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 front-loaded with purpose, then usage, error behavior, cost model, and an example. It is dense and mostly earns its length, but the repeated section/default enumeration and cost detail make it slightly longer than strictly necessary.

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 complex read tool with five parameters, full schema coverage, and an output schema, the description covers the key gaps: identifier sources, default section behavior, error cases, and cost semantics. An agent has enough context to call it correctly without additional documentation.

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 baseline is 3. The description still adds value by explaining the default 'include' set, listing selectable sections, describing per-section cost behavior, and giving a concrete example, though it does not add much for 'fresh', 'id_type', or 'estimate' 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?

The description states a specific verb and resource: 'Zwraca profil osoby z KRS', and explains that it returns selected sections plus an 'available' map in one call. It also distinguishes the tool from search_persons by requiring a person identifier rather than a name.

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 explicitly says when to use it: when you have a 'p-…' identifier from search_persons, get_company, or an /osoba/ page. It also names the alternative path: 'gdy masz tylko imię i nazwisko, najpierw search_persons'.

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=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: zero cost in Pro mode, and the caveat that PKD-division listings read nightly facts and may be unavailable before those facts are built. These are genuine operational traits the schema 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?

Purpose is front-loaded in the first clause, followed by usage, cost, availability caveat, and an example — every sentence carries information. It is dense but slightly sprawling for a single paragraph; splitting the caveat would improve scanability.

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 an output schema present, return values need not be described. The description covers page size, the page parameter, all filter dimensions, the cost model, and the main failure mode, leaving nothing an agent needs before invoking 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 schema already documents each of the five parameters. The description still adds the non-obvious cross-field constraint (letter only with city) and a concrete example payload {"pkd_division": "62", "city": "Kraków", "page": 2} showing how filters combine.

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 concrete action and resource: returns a page of 100 companies from the site's list, with the exact ordering dimensions (city, two-digit PKD division, legal form, or initial letter). It is immediately distinguishable from search_companies, which is named and reserved for name lookups.

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 this for browsing companies within one city, industry, or legal form, and explicitly routes name-based lookup to search_companies. It also encodes the cross-parameter rule that the letter filter works only together with city.

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 only declare readOnly and idempotent; the description adds real behavioural context: zero operation cost on the Pro plan, the coverage caveat that the ranking includes only companies with examined/audited financial statements, and a concrete call example. The one missing trait is sort order (implicitly descending from 'largest' but never stated).

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?

Single dense paragraph that front-loads the resource, then metrics, then usage routing, then caveats and example — good ordering. It does repeat the full metric list already present in the enum descriptions, which is redundant but keeps the tool self-contained.

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 annotations, a full schema and an output schema present, the description supplies the remaining decision-relevant facts: cost, data-coverage limitation, alternative route and an example payload. Only sorting direction and the meaning of the AI 'valuation' score remain unstated.

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 each parameter already carries its own description and enum glosses, so the description's metric glosses mostly restate the schema. The only added value is the worked example showing metric+city+limit combined; baseline 3 applies when 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?

Names a specific verb+resource (returns a company ranking) and enumerates exactly which measures can be ranked (revenue, profit, growth, margin, altman, valuation), plus the optional city scoping. It also explicitly contrasts itself with get_company, so an agent can distinguish it from siblings 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?

States the triggering question types ('largest, most profitable, fastest growing companies') and an explicit exclusion: do not use it to compare two specific companies, call get_company with the financials section instead. When-to-use, when-not-to-use and the named alternative are all present.

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 annotations (readOnlyHint=false, idempotentHint=false) it discloses concrete operational traits: the same 6-hour lock as the web button, 25 Pro operations cost, free-mode AUTH_REQUIRED response, and the estimate=true path returning a quote with allowed=false. This is exactly the context annotations cannot carry.

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 operation's effects, then usage, then cost, then example – a sensible order with no filler. It is dense and packs several clauses into one long sentence, which slightly hurts scannability but costs no accuracy.

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 mutation tool with an output schema present, the description supplies everything else an agent needs: trigger condition, alternative, locking/rate-limit behavior, pricing, and auth failure mode. The return values themselves are covered by the output schema.

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 adds a concrete call example ({"id": "0000006865"}) and clarifies the estimate parameter's return semantics in free mode, which the schema's one-line description does not convey.

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 (odświeża) and resource (dane firmy), then enumerates exactly what refresh means: cache invalidation, reload including reports, indicator persistence, and returning changed fields. This clearly separates it from get_company, which only reads.

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?

"Użyj, gdy get_company zwraca dane wyraźnie nieaktualne... w innych wypadkach get_company wystarcza" gives an explicit trigger and an explicit default to the sibling. It additionally surfaces the 6-hour per-company lock and the cost, which an agent needs before choosing this over the cheap read.

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 and idempotentHint, so the safety profile is covered. The description adds genuinely non-structured context: the Pro-mode cost is 0 operations because only KRS search and the database are queried, no paid sources. It does not describe result ordering or page-size behavior, so it stops short of full 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?

Front-loaded with the purpose, then the routing rule, then cost, then an example — a sensible order with little waste. The returned-field enumeration is slightly redundant given an output schema exists, but it is compressed into one clause.

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 search tool with a full 4-parameter schema, an output schema, and safety annotations, nothing an agent needs is missing: match keys, sibling routing, cost, and a usage example are all present. Pagination and limits are fully specified in the schema.

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 baseline is 3; the description earns the extra point by giving a concrete example combining 'query' and 'city' and by stating that city narrows a name search, which the schema only implies. Numeric-format tolerance and limits are left to the schema, which already documents 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 ('Zwraca listę firm z KRS') and enumerates the match keys (nazwa, NIP, KRS, REGON) plus the returned fields. It explicitly contrasts itself with the sibling get_company, so an agent can distinguish 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 both directions: use this when you have no company identifier or want to narrow a name to a city, and call get_company directly when you already have KRS or NIP. That is an explicit when/when-not with a named alternative.

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 readOnlyHint and idempotentHint, but the description adds real behavioral context: cost of 0 operations in Pro mode, the fact that homonyms are disambiguated by company-link count, and the hard limits on searchable fields. It does not discuss result ordering or how paging interacts with large homonym sets, so it stops short of 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 tight paragraph that front-loads what is returned before the usage routing and constraints. Every sentence carries information, though the list of returned fields is somewhat dense and partially redundant with the 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?

For a three-parameter read-only search with an output schema, the description covers everything an agent needs: input shape, the downstream tool to call with the returned id, disambiguation of same-name people, unsupported search keys, and cost. No behavioral question is left open.

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 page, limit and query are already documented; the description adds the query shape via a concrete example ({"query": "Jan Kowalski"}) and reinforces that the input is a full first+last name. Page and limit semantics are left entirely to the schema, which is acceptable given full coverage.

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 names a specific verb and resource (returns a list of persons from KRS matching a first and last name) and enumerates the returned fields (id, names, surname, company-link count, page URL). It also distinguishes itself from the sibling get_person, which is the profile-detail counterpart.

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 states the exact trigger condition ("Użyj, gdy masz imię i nazwisko, a potrzebujesz identyfikatora osoby do get_person") and routes the agent onward to get_person for profiles. It also declares explicit exclusions: no search by PESEL or date of birth, so the agent knows when this tool will not work.

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