sevdesk

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

Annotations declare destructiveHint=true, so a baseline exists, and the description adds the underlying endpoint (POST /CommunicationWay) plus the key_id default. It does not disclose what 'destructive' means here (e.g. whether setting main=true overwrites an existing main entry) or any auth requirements. Given annotations cover the safety flag, a 3 is appropriate.

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

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

Two compact sentences with zero waste; the core action is front-loaded and the endpoint/default notes follow. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter mutation tool with 100% schema coverage and no output schema, the description supplies the endpoint, the key_id default guidance, and a pointer to the lookup tool. It is nearly complete, missing only clarification of the destructiveHint 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 description coverage is 100%, so the schema already documents contact_id, type, value, main, and key_id in detail. The description only re-emphasizes the key_id default ('2 Arbeit/work'), adding marginal value beyond the schema. 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?

States a specific verb (Attach) and resource (email address, phone/mobile number or website) bound to a contact. It is clearly distinguishable from siblings like sevdesk_list_communication_ways and sevdesk_list_communication_way_keys. An agent can identify the operation without opening 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?

The description gives concrete usage guidance on key_id ('2 Arbeit/work is a good default') and routes to sevdesk_list_communication_way_keys for valid values, which is useful context. However, it does not state explicit when/when-not conditions or alternatives for the whole operation.

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 only annotation is destructiveHint=true, so the description carries most of the burden. It usefully discloses that addresses and emails are NOT created here and must go through sevdesk_add_communication_way, which prevents a wrong expectation about the payload. It says nothing about required permissions, error behavior, or whether the new contact's id is returned.

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?

Four short sentences, front-loaded with the action and the discriminating rule, then the sibling pointer, then the raw endpoint. Nothing is wasted and nothing is buried.

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 an 11-parameter create tool with full schema documentation and no output schema, the description covers the one genuinely non-obvious behavior (child data lives in a separate call). It omits mutation-side effects and success/failure semantics, but the rich schema plus the destructiveHint annotation cover most of the remaining ground.

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

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

Schema description coverage is 100%, so every one of the 11 parameters is already documented, including the enum meanings for status and category_id. The description only restates the name/surename/familyname distinction that the schema already spells out, adding no format or cross-field logic beyond it. Baseline 3 applies.

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

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

States a specific verb and resource ('Create a contact') and immediately narrows scope with the organisation-vs-person rule, which distinguishes the call's two modes. It also names the sibling that owns adjacent data (sevdesk_add_communication_way), so an agent can tell it apart from the communication-way tools 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 concrete selection guidance: use `name` for an organisation, `surename`/`familyname` for a person, and use the sibling tool for addresses/emails. It stops short of stating exclusions or prerequisites (e.g. that category_id is mandatory, or what to do for an existing contact — presumably sevdesk_update_contact), so it is clear context without full routing rules.

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?

Adds substantial behavior beyond the destructiveHint annotation: the record is always a draft, never sent or booked, and stays editable. This meaningfully reframes the risk profile of a write operation. It stops short of emphasizing that a persistent record is still created (relevant given destructiveHint=true) or noting auth/permission needs.

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 single most important fact (draft, never sent/booked) before parameter guidance, and every clause carries information. Sentence flow is dense with em-dashes and parentheticals, which slightly hurts scannability but there is 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 an 18-parameter mutation with no output schema and only a bare destructiveHint annotation, the description covers the tricky semantics (status, contact_person_id, tax rule selection) well. It does not state what the call returns (invoice id), which is the only notable omission.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning on top: it clarifies contact_person_id is a sevdesk USER (not the contact) sourced from an existing invoice, and explains the tax_rule_id vs tax_type split with '1 = the usual choice'. These clarifications resolve ambiguities the schema alone leaves open.

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 (create), resource (invoice type RE), and the crucial scope constraint that it is ALWAYS saved as a DRAFT (status 100). An agent immediately knows this produces an editable, unsent invoice rather than a finalized one, which is the key distinction for this tool.

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

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

Gives concrete when-to-use routing: use tax_rule_id on 2.0 accounts and tax_type on 1.0 accounts, checking via sevdesk_get_bookkeeping_system_version, and retrieve contact_person_id via sevdesk_get_invoice. It lacks any explicit when-not-to-use or alternative-tool exclusion, but provides clear operational context.

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, so the safety profile is covered. The description adds real behavioral context beyond that: it explains the consequence of the 2.0 result for invoice fields and that the call is low-cost, which helps an agent decide to use it as a connectivity probe.

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

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

Three short sentences, front-loaded with the return semantics, then the practical use, then the raw endpoint. Every sentence carries information and none is redundant.

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 and no parameters, the description must carry the return meaning itself, and it does — it tells the agent the value is one of two bookkeeping versions and what 2.0 implies. Nothing needed 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. No misleading hints about inputs are present.

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 whether the account runs sevdesk bookkeeping 1.0 or 2.0') and clarifies the practical meaning of the distinction (taxRule vs taxType on invoices). No sibling overlaps with this diagnostics/metadata tool, so no differentiation is needed.

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 a concrete when-to-use case: 'a cheap way to confirm the API token works.' It does not name an alternative or state exclusions, but for a zero-parameter lookup tool the context is clear and actionable.

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, so the safety profile is covered. The description adds genuine behavioral context beyond that: the balance is derived from imported transactions and may diverge from the real bank balance if older transactions were never imported. It does not describe the response shape.

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, front-loaded with the definition of the value returned, then the caveat, then the API mapping. Nothing is wasted, though the trailing endpoint reference is marginally redundant given 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?

For a two-parameter read-only getter with full schema coverage and no output schema, the description covers what the value means and its key accuracy caveat. Only the return format (scalar value, currency) is left implicit, which is a minor gap.

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 both parameters are already documented, including the inclusive-to-23:59:59 semantics of date. The description restates the inclusive date behavior but adds no format or syntax beyond the schema; 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 (get) and resource (balance of one check account) plus the exact computation semantics: sum of every transaction sevdesk knows up to and including the given date. It is clearly distinguishable from siblings like list_check_accounts or list_transactions.

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

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

Usage is implied by the computation description rather than stated: it is the tool for a point-in-time balance. There is no explicit when-to-use versus alternatives or any stated prerequisites, so it remains minimum viable.

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?

readOnlyHint=true already tells the agent this is a non-mutating read, so the description needn't restate safety. It adds the REST endpoint mapping, which is mildly useful context, but nothing about failure modes (e.g. 404 on unknown id) or the shape of the returned contact. Adequate but thin for the burden placed on it.

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

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

Two short sentences, zero filler, with the core action ('Fetch a single contact') front-loaded before the endpoint decoration. Nothing could be trimmed without losing 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 simple two-parameter read tool with full schema coverage and a safety annotation, the essentials are present. The only gap is the absence of any hint about error handling or whether the embed parameter affects response size, which is minor here.

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% – contact_id and embed are both documented in the schema, including the comma-separated expansion syntax. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (Fetch) and resource (a single contact) with the scoping word 'single', which implicitly distinguishes it from sevdesk_list_contacts. The endpoint mapping (GET /Contact/{contactId}) reinforces exactly one record, but no sibling is named explicitly.

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

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

Usage is only implied: 'single contact by id' suggests retrieval of one known record versus the list tool. There is no explicit statement of when to prefer this over sevdesk_list_contacts or sevdesk_update_contact, and no mention of error behavior for a bad id.

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?

readOnlyHint=true already establishes this is a safe, non-mutating read, so the description needn't restate safety. It adds useful payload context (totals, status, dates, contact, contact person) and cites the underlying endpoint, but says nothing about errors on missing ids, auth requirements, or whether the embed expansion changes cost/latency.

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

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

Two tight clauses with the resource and lookup key front-loaded, followed by the payload summary and the API mapping. No filler, no 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 single-record read with full schema coverage and readOnlyHint annotations, the essentials are present, and the field listing partially compensates for the absent output schema. It falls short of 5 only because return-shape details (e.g., nested contact object structure) are left entirely unaddressed.

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

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

Schema description coverage is 100%, so both parameters (invoice_id, embed) are already documented in the schema and the baseline of 3 applies. The description only echoes the id-based lookup and never mentions the embed parameter's effect.

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 ('Fetch a single invoice by id') and enumerates the payload's key fields, which cleanly separates it from sevdesk_list_invoices by scope. It does not explicitly name the list sibling as an alternative, so it stops short of a 5.

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

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

Usage is implied by 'by id' — an agent can infer this is the lookup path when a specific invoice id is known. There is no explicit when-to-use vs when-not-to-use statement and no routing to sevdesk_list_invoices for discovery, which is what a 4-5 would require.

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, so the safety profile is covered. The description adds the endpoint mapping and the shape of returned items, which is some useful context, but it says nothing about paging defaults, total counts, or whether the list is empty for invoices without positions.

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?

One tight sentence plus the REST endpoint reference, front-loaded with the core purpose and the returned fields. The endpoint mapping is arguably redundant for invocation but is cheap and useful for traceability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns and does so by naming the item fields (name, quantity, price, tax rate, sums). For a simple read-only list endpoint this is nearly complete, with only paging/empty-result behavior left 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 description coverage is 100%, with embed, limit, offset and invoice_id all documented in the schema itself. The description adds no meaning beyond the schema (e.g., no note on how offset/limit interact for positions), so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('positions (line items) of one invoice') and even enumerates the returned fields, so the agent knows exactly what comes back. It does not explicitly contrast with the sibling sevdesk_get_invoice, but the 'of one invoice' scoping makes the distinction fairly obvious.

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 phrase 'of one invoice' implies you must already have an invoice id, but there is no explicit when-to-use guidance, no mention of when to prefer this over sevdesk_get_invoice, and no note about paging origins or prerequisites. Usage is only weakly implied.

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?

readOnlyHint=true already tells the agent this is a safe non-mutating read, so the descriptive bar is lower. The description adds the endpoint mapping but says nothing about behavior on an unknown id or whether embedded resources change the payload; adequate but not rich.

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 short sentences, front-loaded with the verb and scope, with the endpoint detail appended. No filler or restated title boilerplate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-resource read with full schema coverage and no output schema, the description is nearly complete — an agent knows exactly what to call and with what. Only the sibling routing and non-found behavior are unstated, which are minor gaps.

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%, with both voucher_id and embed fully documented in the schema, so the baseline is 3. The description adds only 'by id' and no extra syntax or semantics beyond what the schema already provides.

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

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

States a specific verb (Fetch) and resource (a single voucher/receipt) scoped by id, and adds the underlying endpoint GET /Voucher/{voucherId}. The singular 'single voucher' cleanly distinguishes it from the sibling sevdesk_list_vouchers without needing to name it.

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

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

Usage is only implied: 'by id' tells the agent it needs a known voucher id, but there is no explicit when-to-use/when-not framing and no mention of alternatives like sevdesk_list_vouchers for lookup. Minimum viable 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 readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context — the account types surfaced and the returned fields (IBAN, type, sync status) — but says nothing about pagination behavior, default limits, or auth, so it is adequate rather than rich.

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 front-loaded sentence that defines the resource and its payload, followed by the endpoint mapping. No filler, though the endpoint reference is somewhat redundant for an agent that already has the tool bound.

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 read-only list tool with full schema coverage and annotations, the description supplies the returned fields (IBAN, type, sync status) that substitute for the absent output schema. Only pagination/ordering behavior is left unaddressed.

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

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

Schema description coverage is 100%, with each of the four parameters (embed, limit, offset, count_all) fully documented in the schema, so the baseline of 3 applies. The description adds no parameter-level detail such as default page size or paging guidance beyond what the schema already states.

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 (list) and resource (check accounts) and goes further by defining what a check account is — bank accounts, cash registers, and clearing accounts — plus the fields returned (IBAN, type, sync status). It is clearly distinct from the sibling get_check_account_balance, though it does not explicitly name that sibling.

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

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

The context 'accounts sevdesk tracks payments on' implies when the tool is relevant, but there is no explicit when-to-use statement or exclusion relative to siblings like get_check_account_balance or list_transactions. Usage 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that this is a static enum taxonomy by listing every value and the underlying endpoint (GET /CommunicationWayKey), which means an agent knows the result is complete and cacheable. It stops short of explicitly saying the list is static/param-free, keeping it from 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?

Three tight fragments: purpose + values, the dependency, and the endpoint. Zero waste, front-loaded, and the long value list is justified because it is the tool's entire payload.

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 lookup with no output schema, the description fully compensates by enumerating the complete key set, so an agent can even skip the call in some cases. Nothing required to invoke or interpret it correctly is missing.

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

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

Zero parameters, so the baseline of 4 applies. There is nothing for the description to clarify beyond confirming the tool takes no input, which the empty schema already communicates.

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 ('list the labels a communication way can carry') and immediately enumerates the exact values returned (1 Privat, 2 Arbeit, 3 Fax, 4 Mobil, 6 Autobox, 7 Newsletter, 8 Rechnungsadresse). The enumeration effectively distinguishes it from the similarly named sibling sevdesk_list_communication_ways, which returns actual way records rather than this key taxonomy.

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 states the consumption context: 'Needed for sevdesk_add_communication_way,' naming the exact sibling tool that depends on these keys. An agent knows precisely when to call this (as a prerequisite lookup before adding a communication way) rather than guessing.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the upstream endpoint mapping (GET /CommunicationWay), which is mild context, but says nothing about paging behavior, sorting, or what the payload contains. With annotations covering safety, this is adequate but thin.

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?

One sentence plus the endpoint reference; the parenthetical clarification of 'communication ways' is front-loaded where it matters, and no words are 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 no output schema, the description should hint at the return shape or volume, but it only says 'List'. Pagination-relevant parameters (limit, offset, count_all) exist in the schema, so the agent can infer paging, but a one-clause note about the returned collection would round this out.

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

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

Schema description coverage is 100% and seven parameters (type, embed, limit, offset, count_all, main_only, contact_id) are all documented in the schema itself. The description only adds 'optionally for one contact', which loosely maps to contact_id, so it contributes nothing beyond the schema baseline.

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

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

States a specific verb (List) plus resource (communication ways) and immediately disambiguates the jargon by enumerating examples: email addresses, phone and mobile numbers, websites. It also names the contact-scoping option. It does not, however, explicitly differentiate itself from the write-side sibling sevdesk_add_communication_way or from sevdesk_get_contact.

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 phrase 'optionally for one contact' implies the main use case (all communication ways vs. one contact's), which is implied guidance rather than explicit. It never states when to prefer this over sevdesk_get_contact or sevdesk_list_communication_way_keys, and there are no exclusions or prerequisites.

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

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

Annotations only assert readOnlyHint=true, so the safety profile is covered; the description adds genuine behavioral context beyond that: the non-obvious default that only organisations are returned and that include_persons maps to sevdesk depth=1. It also anchors the tool to the underlying endpoint (GET /Contact). It stops short of noting pagination behavior or result size.

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 compact sentences, front-loaded with purpose and then the default-vs-opt-in behavior, which is the most useful callout. Every sentence carries information; the API endpoint note is marginal but harmless.

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 read-only list tool with no output schema and fully documented parameters, the description covers the one genuinely surprising behavior (orgs only by default). It could mention paging given limit/offset exist, but nothing critical to correct invocation 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 all 11 parameters are already documented, including include_persons and the category_id enum values. The description's only parameter-relevant statement (include_persons and the organisation-only default) restates what the schema already says, so it adds little beyond the baseline.

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

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

States a clear verb+resource ('List contacts') and enumerates the entity subtypes it covers (customers, suppliers, partners, prospects), so an agent knows the dataset. It does not explicitly distinguish itself from the singular sevdesk_get_contact sibling, but the plural/list framing makes the split inferable.

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?

Explains the default return semantics ('only organisations') and the flag to broaden it ('set include_persons'), which implies when the parameter matters. However, it gives no explicit when-to-use vs sevdesk_get_contact or sevdesk_create_contact, and no conditions under which this tool should not be used.

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 readOnlyHint=true, so the description carries the extra load and does so usefully: it decodes the status codes (100 draft, 200 open/delivered, 750 partially paid, 1000 paid) and names the backing endpoint (GET /CreditNote). It says nothing about pagination behavior or result volume caps, keeping it from 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?

Two tight sentences: the core purpose and filter dimensions come first, the status-code legend and endpoint follow. No sentence is wasted and everything is front-loaded.

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 read-only list tool with full schema coverage and an explicit readOnlyHint, the definition covers purpose, filters, and status semantics adequately; no output schema is needed to explain returns. Only the omission of paging/result-volume guidance keeps it from full completeness.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters and the baseline is 3. The description adds genuine value only for `status` by translating the enum codes into human meanings; the remaining filters are merely enumerated, adding nothing 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?

States a specific verb ('List') and resource ('credit notes'), and even supplies the German synonym ('Gutschriften'), making the target resource unambiguous against siblings like list_invoices or list_vouchers. It does not explicitly contrast itself with those siblings, so it stops just short of a 5.

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 list of filterable dimensions implies a querying use case, but there is no explicit when-to-use, when-not-to-use, or named alternative among the many other list_* sibling tools. Usage is inferable for a straightforward list tool but never stated.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered. The description adds the status code meanings and the underlying sevdesk endpoint, but it does not disclose pagination behavior, default limits, authentication requirements, or response shape.

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 the core purpose and filter list, then provides a compact status code legend. The closing endpoint reference ('sevdesk: GET /Invoice') is minor extra detail but does not significantly reduce clarity or add bloat.

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 an 11-parameter list tool with no output schema, the description covers the primary filters and status semantics but omits explanation of pagination, default limit behavior, count_all, and several filter parameters like invoice_type and delinquent. The rich schema fills many of these gaps, so the description is adequate but not 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?

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining what each status code means (50 deactivated recurring, 100 draft, etc.), which the enum values alone do not convey. It also lists the main filter categories, adding useful semantic context.

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 gives a specific verb and resource ('List invoices') and lists the main filter dimensions. It is clearly distinct from the singular get_invoice sibling by name and function, but it never explicitly names or contrasts with any alternative tool, so it falls short of the top score.

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?

There is no guidance on when to use this tool versus alternatives such as get_invoice or list_credit_notes. The description only states what can be filtered, not the conditions or scenarios that should trigger this tool.

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?

readOnlyHint=true already covers the safety profile, so the bar is lower, and the description still adds genuine context: the underlying GET /Order endpoint and the meaning of each status code, which is behavior an agent cannot get from 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?

Front-loaded purpose, then the filter axes, then the status legend, then the endpoint mapping — dense but every clause carries information. The status list is long but earns its space given the opaque numeric codes.

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 read-only, zero-required-parameter list tool with 100% schema coverage and no output schema, the description plus schema is sufficient to call it correctly; only pagination/return-shape guidance is absent, which the annotations and schema largely imply.

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 goes beyond it by decoding the status enum values (100 draft, 200 delivered, 500 accepted, etc.), which the schema lists as bare codes with no 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?

States a specific verb (List) and resource (orders) and then enumerates the concrete document types it covers (quotes/Angebote, order confirmations, delivery notes), which lets an agent place it precisely relative to siblings like sevdesk_list_invoices and sevdesk_list_credit_notes.

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 implies usage by naming the available filters (status, number, date range, contact), so an agent can infer when this tool fits, but it never states when to prefer it over list_invoices/list_credit_notes or any preconditions.

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?

readOnlyHint=true already declares the safety profile, so the description need not restate that this is a non-mutating read. It adds useful context by disclosing the returned field categories and the underlying endpoint (GET /Part), but says nothing about pagination limits, result ordering, or rate behavior beyond what the parameters imply.

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

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

Two compact sentences, with the core resource definition front-loaded and the endpoint reference trailing. No filler or restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the burden of describing returns and does so by naming prices, tax rate and stock. It is slightly thin on pagination/total semantics (only hinted at by the params), but otherwise complete for a filtered list operation.

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 all six parameters (name, part_number, embed, limit, offset, count_all) are already documented in the schema. The description adds no filter syntax, embedding rules, or paging guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb ('List') and resource ('parts') and immediately disambiguates the term by defining parts as 'the products and services in the sevdesk inventory,' which separates it from the contact/invoice/voucher listers among its siblings. It also names the returned fields (prices, tax rate, stock), so an agent knows exactly what it gets.

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

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

Usage is implied rather than stated: the resource scope is clear enough that an agent can tell it retrieves the product/service catalogue, but there is no explicit when-to-use, when-not, or named alternative. For a single-purpose read-only list tool with no competing sibling, implied usage is adequate but not instructive.

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?

readOnlyHint=true already declares the safety profile, so the description needn't carry it. It adds the filter capability set and the underlying endpoint, but says nothing about pagination behavior, default result size, or ordering that an agent might need.

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 tight sentences with the resource and filter set front-loaded. 'bank payments in and out' marginally duplicates what only_debit/only_credit already express, a small 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 read-only list tool with no output schema and fully documented params, the description covers purpose and filter scope adequately. It omits mention of paging fields (limit/offset) and embed, though those are covered by 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% (12 params, each documented including limit range and ISO date guidance), so the schema already does the work. The description restates filter categories but adds no syntax or defaults beyond it.

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 (List) and resource (check-account transactions), and clarifies the domain as 'bank payments in and out'. It does not explicitly name how it differs from siblings like sevdesk_list_check_accounts or sevdesk_get_check_account_balance, so it stops short of a 5.

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 enumerated filters convey implied usage (narrow by account, booking state, date, party, purpose), but there is no explicit when-to-use guidance or routing to alternatives such as get_check_account_balance for balance queries.

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?

readOnlyHint=true already establishes this as a safe read operation. The description adds the underlying API endpoint (GET /Voucher) and domain meanings for status codes, but does not disclose pagination behavior, return format, auth requirements, or rate limits.

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 compact sentences, front-loaded with the operation and resource. Each clause adds useful domain context or endpoint information with no wasted wording.

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-parameter, all-optional list tool with no output schema, the description covers purpose and the critical enum semantics while the schema handles the remaining filters. It could mention return/pagination behavior, but the readOnly annotation and schema cover most operational needs.

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 would be 3. The description adds value beyond the schema by explaining what status codes 50, 100, and 1000 mean, while also reinforcing the C/D credit_debit semantics. It does not cover the other filter parameters, but the added enum meaning is meaningful.

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 (List) and resource (vouchers), and clarifies that vouchers are receipts and incoming/outgoing bills. It does not differentiate itself from sibling tools such as list_invoices, list_credit_notes, or get_voucher, so it falls short of a 5.

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 status and credit/debit code semantics, but does not say when to choose this tool over siblings like list_invoices or get_voucher. There is no explicit when-to-use or when-not-to-use 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?

The destructiveHint annotation already signals a mutating operation. The description adds the important behavioral detail that only provided fields are sent, clarifying the partial-update semantics beyond what the annotations provide.

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 short sentences with zero waste: the first states the purpose and key behavior, the second gives the API endpoint. It is front-loaded and appropriately sized.

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 an update tool with 12 parameters, no output schema, and a destructiveHint annotation, the description plus schema and annotations give enough context to invoke it correctly. It could mention auth or error behavior, but those are not essential for basic invocation.

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

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

Schema description coverage is 100%, so the schema fully documents all 12 parameters. The description adds only a collective note about partial updates, but no individual parameter meaning beyond the schema, which matches the baseline of 3 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?

The description states a specific verb ('Update') and resource ('contact'), specifies scope ('an existing contact'), and distinguishes from sibling tools like create_contact, get_contact, and list_contacts. It also names the underlying API endpoint.

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 implies usage by specifying 'an existing contact' and noting that only passed fields are sent, which tells the agent this is for partial updates. However, it does not explicitly compare with alternatives or state when not to use it.

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