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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on genuinely non-obvious behavior: 'Pro' tier gating, percentile semantics (100 = top of class, only for bilanzsumme and equity_ratio), and the peer recency rule including the 3→5 year widening and where it surfaces (peer_recency/peers_note). That is real disclosure beyond the structured fields.

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 the one-line purpose, then a compact Parameters block and a returns paragraph with a routing sentence at the end. Slightly dense in the returns section, but every clause carries information an agent needs to interpret percentiles and peer recency.

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, yet the description still names the headline metrics and the percentiles/peers shape, and documents the Austrian-domain constraints (UGB size class, ÖNACE section, recent filers). For a two-parameter composite tool this is more than sufficient.

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 0%, so the description carries the full burden and does: fnr format with example and the tolerated 'AT:' prefix, plus n's default (10) and clamp range (1..50). Nothing about either parameter is left ambiguous.

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 ('Where one company stands in its peer group') and defines the composite method (find_peers + precomputed size-peer percentiles). The sibling set is named explicitly, so an agent can separate it from find_peers and get_cohort_summary 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?

Gives an explicit triggering phrase ('Use for "how does X compare to its peers"') and names both alternatives with their selecting conditions: find_peers for the raw peer list, get_cohort_summary for whole-cohort aggregates.

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 safety is covered; the description nonetheless adds the meaningful fact that the tool returns schema metadata only and no company data, plus the tier structure (search card -> full profile -> full record). It does not discuss any rate limits or output structure beyond that, but with strong annotation coverage this is solid added context.

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 purpose and the schema-only constraint are front-loaded, and the alternative-routing sentence earns its place. The trailing documentation URL and the restated 'describes the SCHEMA only' phrasing add minor redundancy, keeping it just short of ideal.

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 parameterless, read-only catalog tool with an output schema present, the description covers everything an agent needs: what it returns (field names, types, code tables, null rules), what it does not return, when to call it, and where to get real data instead. Return-value explanation is correctly deferred to 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?

Zero parameters, so the baseline is 4; the description explicitly confirms 'no parameters', which matches the empty schema and leaves no ambiguity about invocation.

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 ('Catalog of every field the server can return') and immediately scopes it as schema-only with no company data, which cleanly separates it from the data-returning siblings it names (search_companies, get_company_details, get_full_record). An agent can distinguish it from all 17 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?

Gives an explicit trigger ('Call this once up front when unsure what a field means or which tool to use') and routes the agent to the correct alternatives for actual data, distinguishing the many-result tool from the single-result tools. When-not is implied by 'it returns no company data itself', which is sufficient to prevent misuse.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false), but the description adds substantial context beyond them: each call creates a new short-lived export file auto-deleted after ~1 day, the download_url is a signed link valid 60 minutes (with exact expiry in download.expires_at), bytes are not returned inline, the free plan is capped at 100 rows with basic columns, and truncated=true signals a capped result. It also reconciles the read-only hint with the file-writing side effect ("Read-only over company data; each call writes a new short-lived export file"), which is exactly the nuance idempotentHint=false implies.

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?

Despite its length, the text is front-loaded (purpose and side effects first, then usage, parameters, CSV format, returns) and every block earns its place given the 0% schema coverage and the non-obvious signed-URL/expiry behavior. 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?

Complete for a complex export tool: it documents filters, sort, row limits, plan caps, CSV encoding/columns, truncation behavior, and the download-link lifecycle, even though an output schema exists. It also notes the personal-data gating and provides a field-reference URL, leaving no material gap 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?

Top-level schema description coverage is 0%, so the description carries the full burden and does: filters is documented as an AND-joined SearchFilters with the same semantics as search_companies (including the equity_ratio-as-fraction rule and auto-conversion of percent values), sort is described with its default (bilanzsumme descending) and the "distance" option, and max_rows is given its default 1000, hard maximum 10000, and the free-plan 100-row cap. This adds meaning well beyond the bare object 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+resource+scope: exporting a whole search result set as ONE downloadable CSV instead of paging through search_companies. It explicitly contrasts itself with two named siblings (search_companies for browsing, get_company_details for a profile), so an agent can disambiguate without opening schemas.

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 triggers, including multilingual user phrasings ("exportiere", "als CSV/Liste", "alle GmbHs in … herunterladen"), plus when-not: use search_companies for on-screen browsing/ranking, get_company_details for a single profile. Also states the workaround when the set exceeds 10,000 rows (refine filters and export in parts).

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 read-only/idempotent, and the description adds substantial behavior beyond them: the sector cascade (class->group->division->section), the size-neighbour fallback, recency window (current year minus 3, widening once to minus 5), exclusion of the reference company, and the same_sector_level/note signals that guard against misreading rows as benchmarks.

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?

Well front-loaded (purpose, then parameters, then the long return/cascade explanation), but the returns paragraph is a dense run-on covering cascade, tie-breaking, recency, and note semantics in one block. Every sentence is informative, though it could be split for 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?

For a tool with non-obvious matching logic, the description covers selection cascade, tie-breaking rules, recency widening, reference exclusion, and the caveat fields (same_sector_level, peer_recency, note). With an output schema present, it appropriately stops short of re-listing raw field types.

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 0%, so the description carries the full burden and does: it explains fnr as the reference Firmenbuchnummer with a concrete format example ('123456a') and defines n's default (10) and clamp (1..50). Both parameters gain meaning unavailable in the bare 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?

First sentence gives a precise verb+resource+scope: find companies most similar in size to a reference company. It is clearly distinguishable from siblings, and the closing sentences explicitly name search_companies and get_cohort_summary as the tools for different jobs.

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 routes the agent: use find_peers for size-based peer discovery, search_companies with oenace_* + size for a strict industry benchmark, and get_cohort_summary for group aggregates. It also states the meaning of an empty result, which removes a common ambiguity.

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 description adds real context beyond the annotations (which already assert read-only, idempotent, non-destructive): it discloses the large-cohort median skip ('the exact median is skipped for very large cohorts to keep the request fast') and clarifies the return is aggregate stats, not rows. This is a meaningful behavioral disclosure not present in the structured fields.

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 parameter documentation, then routing guidance. The parameter list is necessarily detailed given 0% schema coverage, but the prose is tight and every sentence carries information. Could be marginally shorter but nothing is wasted.

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 0% schema, and an output schema already present, the description supplies the only missing pieces: dimension/value semantics and routing. It even notes a behavioral caveat about large cohorts. An agent has everything needed to call it 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 0%, so the description must carry the full burden, and it does: it defines the 'dimension' axis with all valid values ('gkl', 'bundesland', 'legal_form' and the 'size_gkl' alias), explains 'value' semantics with examples and accepted forms (code 'W' or full name 'Wien'), and points to list_sectors for valid legal_form/gkl values.

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 precise verb and resource ('Aggregate statistics for a cohort of companies') and immediately sets scope with 'NOT per-company rows'. It names the alternative siblings (search_companies, get_company_details) in context, so it is clearly distinguishable 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?

Explicitly says when to use it ('what does group X look like in aggregate') and when to use alternatives ('for the individual companies use search_companies, for one company use get_company_details'), naming both siblings. It also points to list_sectors for valid values.

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, non-destructive behavior (the opening 'Read-only' merely repeats that). The description adds genuinely new traits: null fields are omitted so a missing key means no data, always-included sections, and that history=false drops year series while keeping latest values. Only the return format and size expectations are left thin, which the output schema likely covers.

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 and read-only statement, then a clean parameter list, then routing guidance. Slightly verbose: the closing sentence re-enumerates the returned sections already listed in the include description ('Identity, location, company, size, filings...'), which is mild redundancy.

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 with annotations and an output schema, this is complete: it covers routing, parameter semantics, null-omission behavior, and even links a field reference for field-level detail. No output-shape explanation is needed given 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 description coverage is 0%, so the description must carry all parameter meaning, and it does: fnr format with a concrete example and provenance ('from a search card'), the exact include subset with omit-means-all semantics and its purpose, and history's default plus the effect of setting it false. Nothing about the three parameters is left ambiguous.

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 ('Full served profile for one company by FNR') plus the read-only nature and the lookup key. It explicitly names what it is not (get_full_record for the complete record, get_company_history for trends), so an agent can distinguish it from siblings 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?

Gives explicit when-to-use ('when you already know the company, from search_companies') and names two alternative tools with the precise conditions that select them. The include/history guidance adds tactical advice on when to trim the response.

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 read-only/idempotent profile, but the description adds genuinely non-obvious behavior: unknown fnrs land in result.not_found, billing is 1 credit per company and only returned companies are charged, and batches cap at 50. This is exactly the operational context 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?

Front-loaded one-line summary, then a clean per-parameter block, then return shape. Dense but every sentence carries load — no filler or restatement of the tool name.

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, yet the description still sketches the return shape (year -> value, latest/latest_year, batch nesting under result.companies), which resolves the ambiguity between the two invocation modes. Nothing needed to call 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 coverage is 0%, so the description must carry the load and does: fnr format example and provenance ('the fnr from a search card'), fnrs batch limit and mutual exclusion ('Pass fnr OR fnrs'), and metrics semantics including the 'revenue' -> 'umsatzerloese' alias and the omit-to-get-all default.

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 with scope: 'Per-metric multi-year time series for one company — or a whole cohort.' It distinguishes the single-vs-batch modes and explicitly names the sibling tools it is not (get_company_details, get_full_record).

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 routing: 'Use when you need the trend of specific figures; for a full one-shot profile use get_company_details, for the complete record (all positions) use get_full_record.' It also names the concrete cohort scenario (Branchenradar over 30-200 company pages) that selects the batch path.

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/no-open-world, so safety is covered. The description adds real context beyond that: it is dataset-wide, not per-company, accepts no filters, and is served O(1) from a precomputed stats doc, plus it sketches the return breakdown (XML vs PDF-only vs none).

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 the core purpose and then the return breakdown and routing, with each sentence carrying weight. Slightly verbose in places ('as an aggregate dashboard'), but no wasted filler.

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?

Complete for a parameterless, read-only aggregate tool. An output schema exists so return values are covered, and the description still adds scope, performance, and routing context that fully equips an agent to call it 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?

Zero parameters, which is the baseline-4 case. The description reinforces this with 'no parameters' and 'no filters', leaving no ambiguity that no 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+resource: an aggregate, dataset-wide coverage dashboard showing how much of the register is served. It explicitly distinguishes itself from siblings (list_sectors, get_cohort_summary) and from per-company data, so an agent can identify it immediately.

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 use case ('how complete is the data') and names two alternatives with the conditions that select them: list_sectors for valid filter values, get_cohort_summary for one group's aggregate figures. Nothing 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?

Read-only is already in annotations, but the description adds real behavioral context the annotations don't: 15-minute (900 s) signed-link expiry, the ~1 minute on-demand fetch from the register for the first call of a year, the financial_institution flag/caveat for banks and insurers, and the precise condition under which download is null (register holds no document).

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 action, then parameter, then return semantics; nearly every sentence earns its place. It does re-enumerate output field names (download.url, expires_at, expires_in_seconds) that the output schema already carries, which is mild redundancy, but the accompanying expiry/latency semantics justify it.

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 a one-parameter tool with an output schema and full annotations, the description supplies everything an agent needs: key format, the expiry window, the latency and null cases, the bank/insurer caveat, and the alternative tools. Nothing material 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 coverage is 0% and the single parameter is undocumented in the schema, so the description carries the full burden — and does: doc_key accepts a document_ref formatted '{fnr}:{stichtag}' from get_company_details, a bare FNR (meaning latest filing), or a legacy doc_key. That is exactly the syntax an agent needs.

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 first sentence states a precise verb+resource+output: it returns a time-limited download link to a company's official Jahresabschluss. It also draws the line against get_company_details / get_full_record for already-parsed figures, so an agent can separate it from the parsing siblings without opening schemas.

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 to fetch the original filing artifact; for the already-parsed figures use get_company_details / get_full_record instead of downloading.' Plus an operational warning to open the link promptly rather than expect inline bytes. Clear when-to-use and named alternatives.

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, destructiveHint=false and openWorldHint=false, so safety and idempotency are covered. The description adds genuinely useful format behavior — XML flattened to 'label: value' lines, PDF text-extracted — plus the `truncated` signal. It stops short of permission requirements or error behavior, so a 3 is appropriate for annotations-covered read tools.

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 sentence, then compact parameter block, then usage-and-alternatives block. Every sentence earns its place; the example questions clarify intent rather than pad.

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 structure need not be explained, and the description still flags the `truncated` field. Combined with thorough parameter documentation and sibling routing, nothing an agent needs to invoke this 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 coverage is 0%, so the description carries full burden and does so well: doc_key format ('{fnr}:{stichtag}'), its source tools, and the bare-FNR fallback to the latest filing are all specified. max_chars documents default 40000, max 120000, and the linked `truncated` flag.

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 ('Return the TEXT of a company's official Jahresabschluss filing') and clarifies what content is exposed (Anhang, Lagebericht, positions). It explicitly distinguishes itself from get_company_details (parsed figures) and get_document (download link) without requiring schema inspection.

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?

Provides an explicit when-to-use trigger with example questions ('Was steht im Lagebericht zum Ausblick?') and names the two alternatives with their differing conditions. An agent can route correctly between text reading, figures, and download.

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 readOnly, idempotent, non-destructive, so safety is handled. The description adds useful traits beyond structured data: the 30-day default window and the 'Forward-only from 2026-07-01' coverage constraint, which materially affects whether results are trustworthy for older periods. Minor gap in not explaining aggregation semantics or pagination, but the coverage boundary is the important disclosure.

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 in the first sentence, then usage, then parameters and return shape. Every block earns its place, though the fragmentary 'Read-only. Pro.' and mixed paragraph/list formatting read slightly unpolished.

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 six-parameter, all-optional aggregation tool with an output schema, the description supplies purpose, alternative routing, parameter defaults, and the coverage window. Nothing essential to calling 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 0%, so the description must compensate, and it mostly does: it labels all six parameters, marks them optional, gives the since/until default, and notes the facet parameters match list_events. It stops short of giving accepted formats or example values for since/until or coded values for oenace/legal_form.

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 ('Aggregate counts of register changes by type and by Bundesland over a window') and explicitly distinguishes itself from the sibling list_events, which handles individual changes. An agent can select 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 an explicit use case ('market-watch dashboards') with a concrete example and names the alternative tool plus the condition that selects it ('for the individual changes use list_events'). This is textbook when/when-not guidance.

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 read-only/idempotent/destructive=false, so the safety profile is handled. The description adds genuine behavioral context beyond that: it is 'the heaviest read', it passes through unknown codes ('nothing dropped'), and it includes completeness flags, guv_years and lineage. It does not mention rate limits or result size/pagination.

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 tool, then the parameter, then the return contents and routing. Every sentence earns its place; no filler.

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 tool with an output schema present, the description supplies everything needed: what it does, the parameter's meaning/format, what comes back at a high level, and when to prefer siblings. Nothing material 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 coverage is 0%, so the description carries the burden. It explains that fnr is the Firmenbuchnummer, gives a concrete format example ('123456a'), and tells the agent its source (the fnr from a search card). That is meaningful added semantics for the single required parameter.

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: 'Complete per-company record, the full superset we hold for one company.' It defines the scope (everything for one company) and explicitly distinguishes itself from get_company_details and get_company_history by naming both 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 routing: 'Use it when you need raw completeness; for the normal curated profile use get_company_details, for a single metric's trend use get_company_history.' Both alternatives and their selecting conditions 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 read-only/idempotent/non-destructive, yet the description adds substantial behavior beyond them: failed attempts cost 0, credits are the billing unit for metered accounts while calls/compute_units are internal telemetry, and the response never leaks another user's data or the e-mail behind the key.

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 and scope in the first sentence, with the parameter and return details following. Some return-field detail is verbose given an output schema exists, but it is organized and each sentence carries information.

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 single optional parameter read-only tool with an output schema, the description supplies the enum values, default, scope guarantees, and billing semantics. Nothing needed to call 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 0% and the enum list is absent from the schema, so the description fully compensates by enumerating all five allowed window values and restating the default 'today'. Without this text an agent could not know the valid inputs.

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 ('Your own API-key usage: call count and weighted compute-units, per tool') and explicitly frames the scope as the calling key only. This is trivially distinguishable from every sibling, which are all company/person/document 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?

Gives concrete usage context: free-plan keys use it to check consumption against monthly free quotas, and credit-metered accounts use it for balance/billing detail. It does not name explicit alternatives or when-not-to-use, but the sibling set makes mis-selection unlikely.

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 the description adds substantial behavior beyond that: strictly newest-first merged chronology, no download links, no personal data, the meaning of parsed=true/false, and that PDF-only years are surfaced honestly rather than silently dropped.

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 parameter, then returns — a logical order with no filler sentences. It is dense however, and the detailed entry-shape enumeration partially duplicates what the output schema already provides, costing a little efficiency.

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 a single required parameter, an output schema, and rich annotations, the description still covers the remaining ambiguities an agent needs: parameter format, ordering guarantee, type semantics, the document_ref handoff to get_document, and the honest-gap 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 0% and the single parameter would otherwise be opaque, but the description fully compensates: it names fnr as Firmenbuchnummer, gives a concrete example format ('123456a'), and states that an 'AT:' prefix is tolerated.

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?

Specific verb + resource + ordering ('List a company's available official documents, newest first') with scope qualifiers ('read-only, metadata only'). It also implicitly distinguishes itself from get_document and get_company_details, which the description names explicitly later.

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 routes the agent: this tool for the listing/metadata, get_document for download links, get_company_details for figures. It also tells when a year appears only as PDF and that this is an intentional gap rather than an error, and clarifies that a Konzernabschluss is not a duplicate of the year's Jahresabschluss.

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 safety (readOnly, idempotent, non-destructive), yet the description adds tier gating ('Pro'), data provenance semantics for `source` (change_feed coarse vs detailed daily-diff), the critical interpretation that an empty result means no matching change rather than missing data, and the default 30-day window. This is substantial context beyond the 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?

Purpose and the sibling alternative are front-loaded, and the parameter block is bulleted and scannable. It is long, but the length is largely justified by ten undocumented parameters; only the extended type enumeration feels slightly dense.

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 10-param, no-required-field query tool with an output schema, the description covers scope, ordering, filtering, defaults, return shape, field semantics, and the empty-result edge case, plus a field reference link. Nothing an agent needs to call 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 0%, so the description carries the full burden and does so well: it enumerates the valid `types` values split by detailed vs coarse, explains their date coverage and source, documents date formats and defaults, facet formats for bundesland/oenace/legal_form, fnrs as a watchlist, and pagination defaults/limits. This fully compensates for the empty 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+resource ('cross-company feed of register CHANGES'), its ordering ('newest first'), and its intended use case ('market-watch / deal-sourcing surface'). It explicitly distinguishes itself from the sibling get_company_details by naming the single-company alternative, so an agent can route correctly 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?

Gives explicit when-to-use framing ('which companies changed X, where, since when'), concrete example queries, and an explicit when-not-to-use clause routing single-company history to get_company_details. Also flags the M&A/restructuring types as the deal/distress surface, which helps an agent pick the right filter.

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 declare readOnlyHint=true, idempotentHint=true, and openWorldHint=false. The description adds valuable behavioral context beyond these: it discloses return structure (matches with ONACE level, code, label, activity concept, filter), explains the concept-only match semantics, and clarifies that counts reflect the served dataset. This is substantive transparency beyond 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?

Reasonably structured with front-loaded purpose and clear sections, but notably lengthy for a single-parameter tool. Every sentence serves a purpose, yet the density and use of parentheses/arrows may reduce scannability. The core value is present without excessive waste.

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?

Despite having only one optional parameter, the description configures how to interpret results (concept-only matches), when to call it (first, before guessing), and where to go for complementary coverage. Given the tool's discovery role and an output schema present, the description provides sufficient context without needing to explain return values in detail.

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 0%, so the description must carry parameter meaning. It does so thoroughly: the optional query parameter accepts 'a German category word or phrase' with concrete examples (Brauereien, Steuerberater, Softwarefirma), and explains the match structure returned. It also documents the enum-like values for size-class (W/K/M/G). This fully compensates for the schema gap.

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 purpose -- valid filter values for search_companies with counts -- and names the sibling it serves. Distinguishes itself from get_coverage explicitly for region/format coverage. An agent can identify its role in the tooling ecosystem without reading 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?

Explicitly instructs to 'call this first to discover real legal_form/size_gkl values' before using search_companies or get_cohort_summary, and directs to get_coverage for region/format coverage instead. Provides clear when-to-use and alternative-routing guidance.

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, so the description's added depth is real value: it discloses credit metering (keyset = 1 credit per company vs 1 per 25 rows), that keyset is 'not combinable with query/near', that unknown sort fields are rejected, that missing-metric companies sort last, and that cards are compact rather than full records.

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 critical routing statement is front-loaded and the parameter/recipe blocks are scannable, but there is internal duplication — the 'unknown sort field is rejected with the list of valid ones' rule appears twice in the same bullet — and the parameter bullet for sort is dense enough to be hard to parse in one pass.

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 6-param tool with a rich nested filter object, an output schema (so return values needn't be spelled out), and heavy sibling overlap, the description covers strategy selection, paging modes, cost model, and error recovery. Nothing an agent needs to invoke 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?

With 0% top-level schema coverage the description carries the full burden and does so: equity_ratio is defined as a fraction with percent auto-conversion, the sort field must be 'founded_year' not 'founded_year_min', 'after' is keyset paging with a ''-to-start protocol, and event_signal groups are enumerated. This adds meaning far 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 opening sentence states a specific verb+resource ('Find or look up Austrian companies by name') and declares itself the primary entry point, explicitly contrasting with named siblings (get_company_details, get_full_record, get_cohort_summary). An agent can distinguish this from every other lookup tool 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 explicit when-to-use ('START HERE', 'call THIS tool first'), a battery of named query strategies with selection rules, and routes to alternatives for events (list_events), aggregates (get_cohort_summary), and full records. The 'pick ONE primary strategy per user intent' plus the 'Zero hits? Read relaxations' guidance is unusually complete.

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 read-only/idempotent/destructive, and the description adds genuinely new behavioral facts: the 3-character minimum, case-insensitive matching, that limit caps companies scanned, that results are grouped by exact name found, and the important caveat that name equality is not identity and should be disclosed to users.

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 sentence, then a compact parameter block, then return shape, then routing. The German legal-form terms and the identity caveat each earn their space; no filler sentences.

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 two-parameter read tool this covers everything an agent needs: input semantics, the shape of the returned persons[]/companies[] structure, the identity caveat, and the sibling routing. Output schema exists, yet the description's return summary adds grouping/equality nuance rather than duplicating field lists.

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 0%, so the description carries the full burden and does: name is required, min 3 characters, case-insensitive, with concrete examples; limit is optional, default 50, max 200 and means maximum companies scanned. Both parameters gain meaning found nowhere 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 action (find the companies a person represents) with the register roles covered (Geschäftsführung, Vorstand, Prokura, Aufsichtsrat) and the data source (official register roster). It is clearly distinguishable from sibling get_company_details, which it explicitly names as the inverse lookup.

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 routing: use this for 'Welche Firmen führt X?' and use get_company_details when the direction is a company's own officers. It also includes a worked query example, so the when-to-use and when-to-use-the-alternative conditions are both covered.

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