firmenliste-mcp

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

The description discloses key behavioral aspects beyond annotations: the offer is valid for 48 hours, price-stable, and the purchase itself is done by the human via bestell_url, not by the tool. It also highlights the confirmation requirement, indicating that calling the tool has real consequences. Since annotations are all false and provide no behavioral hints, the description carries the burden and does so effectively, though it could mention idempotency or side effects more explicitly.

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 sentence followed by a critical warning and variant notes. It front-loads the core function and outputs, then the important usage constraint, then the configurations. There is no fluff; every clause earns its place, making it concise and well-structured for quick scanning.

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 5 parameters and no output schema, the description covers the essential context: outputs (quote_id, bestell_url), the 48-hour validity, the human-triggered purchase, and the confirmation requirement. It explains the main variants but does not fully detail all parameter interactions (e.g., when to combine plz with umkreis_km versus using bundesland). The schema provides some of this info for plz and bundesland, so the description is adequate but not exhaustive for a tool with this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to umfang ('nur_email' variant) and bundesland (example 'Bayern'), clarifying their purpose. However, it does not explain idListe (the required parameter), plz, or umkreis_km beyond what the schema already provides. With schema coverage at only 40%, the description partially compensates but does not fully document all parameters, leaving the agent to infer the relationship between plz+umkreis_km and the other variants.

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 the action ('erzeugt' – generates) with a specific resource ('Angebot' – offer), and specifies the outputs (quote_id, bestell_url). It also mentions validity and price stability, making it distinct from sibling tools like branchen_suchen or liste_details, which are query/list tools. The verb and resource are unambiguous.

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 gives an explicit prerequisite: 'Nur nach ausdruecklicher Bestaetigung des Nutzers aufrufen' (only call after explicit user confirmation), which is crucial for a mutating action. It also explains variants like umfang='nur_email' and bundesland='Bayern', providing context for when to use those configurations. While it doesn't explicitly state 'when not to use', the tool's purpose is clearly unique among siblings, so the absence of alternative routing is not a major gap.

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 the safety profile is covered. The description adds genuinely useful behavioral detail by enumerating what each hit returns (idListe, Datensatzanzahl, field availability, Nettopreis), which matters because there is no output schema. No auth or rate-limit context, but that is a minor gap given the annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with the core purpose front-loaded, followed by return payload and usage ordering. No filler or 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 two-parameter read-only search with no output schema, the description supplies the return-field summary and the workflow position an agent needs. The only omission is any guidance on the 'land' parameter and result volume, which is minor.

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 50%: 'q' is documented in the schema, 'land' is only an enum with a default and no prose. The description reinforces the search-term concept with examples but never mentions the country parameter, so it only partially compensates for the gap. 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?

States a specific verb and resource ('Findet Adresslisten zu einem Suchbegriff') with concrete examples ('Golf', 'Spedition'). It also positions itself relative to siblings by declaring it is the first step before detail lookups (liste_details) or quote creation (angebot_erstellen).

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?

'Immer der erste Schritt vor Details oder Angebot' gives a clear sequencing rule that tells the agent when to reach for this tool versus the downstream ones. It stops short of naming the sibling tools explicitly or stating when this tool should not be used, so it falls just below full marks.

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 (readOnlyHint=true, idempotentHint=true, destructiveHint=false, closed-world), so the description need only add context. It adds the legal/regulatory framing and the relay-to-user obligation, but says nothing about return format, freshness, or versioning of the terms beyond the word 'machine-readable'.

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 what the data is and followed by the usage instruction; every clause carries content. Slightly dense with parenthetical legal terms 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?

For a parameterless, read-only lookup with no output schema, the description supplies enough to call it correctly: what is returned conceptually, when to call it, and what to do with the result. A note on the return structure or the obligation's strength would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero parameters, so there is nothing to document and the baseline is 4. The description makes no false implication of parameters, which is the main risk for a no-input tool.

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 (retrieve/abrufen) and resource (machine-readable purchase and usage terms), and enumerates the content areas it covers (B2B-only, VAT, right of withdrawal, legal limits of data usage under UWG/DSGVO). This is far more specific than the bare title, though it never differentiates itself from the sibling tools, which are unrelated resources anyway.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger: retrieve this before making a purchase recommendation, and instructs how to handle the result (relay it correctly to the user). That is actionable when-to-use guidance; it simply names no alternatives or exclusions, which is understandable since no sibling is a substitute.

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 (readOnlyHint, idempotentHint, destructiveHint=false). The description adds real behavioral context beyond that: which countries are instantly purchasable, that others require a request, and that a data staleness indicator ('Datenstand') is included in the output. That 'Datenstand' note is the most useful behavioral fact and is not in 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?

A single dense sentence front-loaded with the verb and resource, followed by the most decision-relevant scope distinction (DACH online vs others on request). No filler, no repetition 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?

For a zero-parameter list tool with no output schema, the description covers the essential agent decisions: what it returns, which countries are immediately buyable, which need a request, and that freshness metadata is included. It stops short of describing the return shape (fields per country row), but with no output schema that is a minor gap for a list endpoint.

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 per the rubric. There is nothing to document, and the description correctly focuses on scope and output rather than inventing parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Listet alle Laender mit B2B-Firmenadressen von firmenliste.net'), and adds scope details (DACH online-purchasable vs ~40 other countries on request). This distinguishes it clearly from siblings like liste_details or branchen_suchen, which operate on different dimensions of the same data domain.

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 implies how country coverage maps to purchase availability (DACH online vs others on request), which gives some context, but it never says when to call this tool versus liste_details or kaufbedingungen, nor does it state any prerequisite or follow-up step. Usage is inferable but not guided.

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 (readOnlyHint, idempotentHint, non-destructive), so the bar is lower. The description still adds real behavioral context: that passing plz + umkreis_km triggers a live count rather than a cached one, and that figures are net prices plus German VAT — both useful for interpreting results.

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 dense sentences, front-loaded with the returned content before the optional mode and the price caveat. Every sentence carries distinct information with 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?

With no output schema, the description does the right thing by enumerating the returned detail categories (counters, distribution, fields, prices) and the conditional radius behavior. For a read-only lookup tool this is essentially complete, though it could note the cost/credit implication of running the live count.

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 67% (plz and idListe documented; umkreis_km has only bounds). The description adds the joint semantics of plz + umkreis_km that the schema does not spell out — that together they scope a live radius count including price — which meaningfully compensates for the undocumented third 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 and resource ('Detailansicht einer Adressliste') and then enumerates exactly what the view contains: field counters, state distribution, contained fields, and all package prices. This is far more concrete than the title and lets an agent distinguish it from the search/creation siblings such as branchen_suchen or angebot_erstellen.

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 implies use (fetch details and pricing for a known list id) and explains the optional plz + umkreis_km mode for live radius counting. However, it never explicitly states when to prefer this tool over siblings like branchen_suchen or kaufbedingungen, leaving the routing to inference.

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