sevdesk MCP by usefulapi

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

The annotations already declare destructiveHint=true, so the safety profile is carried structurally; the description adds the underlying API call ('sevdesk: POST /CommunicationWay') but nothing about what happens to an existing main communication way when main=true, duplicate handling, or error behavior. With annotations present, adding the endpoint is useful but the behavioral picture remains 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?

Front-loaded with the purpose in the first sentence and the key_id guidance immediately after; no filler. The trailing 'sevdesk: POST /CommunicationWay.' is the weakest line since it restates an implementation detail the agent cannot act on, but the overall length is tight.

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 five-parameter creation tool with no output schema, the description covers the input side adequately but omits what the call returns (e.g. the new communication way id) and any permission or failure considerations. It is minimally sufficient rather than 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 every parameter including key_id's enum-like values and default is already documented structurally. The description's only addition is recommending 2 as a default, which is marginal reinforcement of what the schema states, so the 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?

The description states a specific verb ('Attach') and resource ('email address, phone/mobile number or website to a contact'), which is more precise than the title's 'Add'. It also names the sibling tool sevdesk_list_communication_way_keys, so an agent can distinguish this write tool from the related read/list tools in the same family.

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 one concrete usage hint for the key_id parameter ('2 Arbeit/work is a good default') and routes the agent to sevdesk_list_communication_way_keys for valid keys. However, it never says when to use this tool versus sevdesk_update_contact or when attaching a communication way is appropriate, so the guidance is implied rather than explicit.

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 provide only `destructiveHint: true`, so the description carries most of the burden; it adds the useful API mapping 'sevdesk: POST /Contact' but says nothing about permissions, duplicate handling, or whether the call is idempotent. For a write tool with minimal annotation coverage this is adequate but shallow.

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 core action, then the field-shape rule, then the sibling hand-off and endpoint. No filler and nothing 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?

Covers the create semantics and the address/email hand-off, but for a tool with no output schema the description never indicates what comes back (e.g. the new contact id), which an agent needs in order to chain into `sevdesk_add_communication_way`. No mention of failure modes or the required `category_id` beyond what the schema already states.

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 11 parameters including the category_id codes and the name/surename/familyname person-vs-organisation rule. The description restates that rule in condensed form, which helps agents that skim, but adds no syntax, format, or validation detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Create a contact') and immediately branches on the two mutually exclusive shapes (organisation via `name`, person via `surename`/`familyname`). It also names the sibling `sevdesk_add_communication_way` as the place for addresses and emails, so an agent can separate create-contact from create-communication-way 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 clear positive guidance on which fields to supply and routes the address/email sub-case to a named alternative. It lacks an explicit 'when not to use' (e.g. an existing contact should go to `sevdesk_update_contact`), but the create-vs-update distinction is self-evident from the verb.

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 destructiveHint=true, so the description carries most of the behavioral burden and does so well: it discloses that the invoice is a draft, not sent, not booked, and stays editable, and clarifies that contact_person_id is a sevdesk USER rather than the customer. This is real context beyond the single hint and does not contradict 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?

Front-loads the core purpose and the draft-status constraint, then layers parameter tips and the raw endpoint for debugging. Dense but every clause earns its place; 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?

For an 18-parameter mutation tool with no output schema, the description covers the critical behaviors (draft state, contact_person semantics, tax routing) while the 100%-covered schema handles the rest. It does not say what the call returns (e.g. the new invoice id), which is a minor gap since no output schema exists.

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 genuine meaning: it disambiguates contact_person_id (a SevUser, not the contact) and explains the mutual-exclusivity logic between tax_rule_id (2.0) and tax_type (1.0). These clarifications beat what the schema alone conveys for the most confusing parameters.

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 normal invoice (type RE)') and immediately pins down the output state ('ALWAYS saved as a DRAFT (status 100)'). This scope is distinctive and lets an agent distinguish it from read-only invoice 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 actionable routing guidance: which upstream tools supply required values (sevdesk_get_invoice for contactPerson.id, sevdesk_get_bookkeeping_system_version for the bookkeeping version) and the tax_rule_id vs tax_type branch. It does not name an explicit 'when not to use' alternative for invoice creation, but no obvious sibling competes for that job.

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 genuinely useful behavioral context beyond that: the call is cheap/side-effect free and can double as an API-token check, which is exactly the kind of operational detail an agent cannot get from 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?

Two tight sentences plus the raw endpoint reference, with the core purpose front-loaded. Every clause earns its place: the version meaning, the 2.0 taxRule difference, and the token-check use case.

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 carries the return-value burden and does it — it explains exactly what comes back (1.0 vs 2.0) and why that matters. Nothing an agent needs to call 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter discussion, and none is needed.

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 (get the bookkeeping system version) and immediately explains what the return value means: whether the account runs 1.0 or 2.0, with 2.0 using taxRule instead of taxType. That semantic distinction lets an agent understand the tool's purpose without any sibling comparison, which is fine since no sibling overlaps this resource.

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 clear usage context: use it to determine which invoice tax model applies, and as a cheap token-validation probe. It doesn't state explicit exclusions, but no sibling tool competes for this resource, so there is no alternative to route away from; the missing piece is only a 'when not to bother' note.

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 meaningful behavioral context beyond that: the value is computed as the sum of all known transactions and may diverge from the real bank balance if older transactions were never imported. It omits auth/rate-limit details.

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?

Roughly three short sentences that are front-loaded with the core meaning and the important accuracy caveat. The trailing endpoint reference is mildly redundant but compact; little waste overall.

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?

A simple read-only tool with 2 fully documented params, no output schema and annotations covering safety. The description captures the key behavioral caveat, so an agent has what it needs 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 description coverage is 100%, so both parameters are already fully documented in the schema. The description echoes the date semantics (sum up to and including the given date) but adds no syntax or format detail 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), resource (check account balance) and scope (at a given date, sum of all known transactions). An agent can distinguish it from siblings like sevdesk_list_check_accounts or sevdesk_list_transactions 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 purpose implies when to use it (querying a single account's historical balance at a date), but there is no explicit when-to-use/when-not guidance or named alternative. No prerequisites or exclusions are 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 profile is covered without the description. The description adds the underlying endpoint (GET /Contact/{contactId}), which helps an agent familiar with the sevdesk API, but says nothing about error behavior for unknown ids or the shape of the returned contact.

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 action and scope, and the endpoint reference is compact. Nothing is padded or 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?

For a simple single-record lookup with a fully documented two-parameter schema and a readOnly annotation, the description plus structured fields are sufficient to invoke correctly. The only gap is that, with no output schema, the description does not hint at what the returned contact contains.

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 contact_id and embed fully documented in the schema, so the baseline is 3. The description adds no syntax, format, or expansion semantics for embed 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?

States a specific verb ('Fetch') and resource ('a single contact by id'), which lets an agent distinguish it from sevdesk_list_contacts and sevdesk_create_contact. It does not name those siblings explicitly, so differentiation is implied rather than spelled out.

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?

'By id' implies the precondition that the caller already has a contact id, which is useful routing signal versus the list tool. However, there is no explicit when-to-use guidance, no mention of what to do without an id, and no named alternative.

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

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

Annotations already cover the safety profile (readOnlyHint=true), so the description's added value is the returned field inventory and the underlying API mapping (GET /Invoice/{invoiceId}), which helps an agent ground the call. It does not disclose auth requirements or error behavior for a missing id, keeping it below a 5.

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

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

A single tight sentence with the primary purpose front-loaded, followed by a compact API reference clause. Nearly zero waste, though the raw endpoint string is marginally redundant for an agent that never calls the HTTP API directly.

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 whose annotations declare safety, this covers purpose, the id requirement, and the shape of the returned data, which compensates for the absent output schema. It stops short of clarifying how embed changes the response or what happens on an unknown id.

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 invoice_id and the embed expansion parameter are already documented in the schema. The description names the id but adds no semantics for what values are valid or what embed expansion returns, matching the baseline 3 when the schema does the work.

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 what the response contains (totals, status, dates, contact, contact person). It implicitly separates itself from list_invoices and get_invoice_positions via 'single invoice', but no sibling is named explicitly, 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 phrase 'by id' implies retrieval of a specific known invoice, which is adequate usage context, but there is no explicit when-to-use guidance, no exclusions, and no pointer to list_invoices for browsing or get_invoice_positions for line items.

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 readOnlyHint annotation already establishes this is a safe read, so the bar is lower. The description adds the underlying endpoint mapping (GET /Invoice/{invoiceId}/getPositions), which is genuine backend context, but says nothing about pagination behavior, result caps, or default ordering — all relevant since limit/offset exist.

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 tightly written sentence that front-loads the verb and resource, defines the domain term, and ends with the endpoint reference. Every clause earns its place; nothing is padded.

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 endpoint with no output schema, the description usefully sketches the returned fields and the exact API path, and the input schema is fully self-documenting. It is only short of complete because paging behavior and the relationship to sevdesk_get_invoice are 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%, so the schema fully documents invoice_id, embed, limit, and offset, and the baseline is 3. The description adds no parameter-level meaning — it lists returned fields rather than inputs — so it neither compensates nor detracts.

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 — 'List the positions (line items) of one invoice' — and disambiguates the jargon 'positions' with the plain-language 'line items'. It also enumerates the payload shape (name, quantity, price, tax rate, sums), which separates it from the sibling sevdesk_get_invoice that returns the invoice itself, though it never names that sibling 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 by the scope phrase 'of one invoice' and the required invoice_id. There is no statement of when to prefer this over sevdesk_get_invoice, no prerequisite that the invoice must already exist, and no guidance on paging via limit/offset despite those parameters being present.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's burden is lighter. It adds that this maps to the backend endpoint GET /Voucher/{voucherId}, which is useful provenance, but says nothing about error behavior for invalid ids or what the returned object contains.

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 front-loaded ahead of the API endpoint detail. Nothing here 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?

For a simple two-parameter read tool with no output schema, the description is minimally sufficient: it identifies the lookup key and the operation. It does not hint at the shape of the returned voucher or the referential error case, which keeps it at adequate rather than 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%, with both voucher_id and embed documented in the schema itself, so the baseline is 3. The description adds no syntax, format, or usage notes for either parameter, leaving the schema to carry the explanation entirely.

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 voucher (receipt) by id') and the singular framing implicitly differentiates it from the sibling sevdesk_list_vouchers. It also clarifies that 'voucher' means a receipt, which helps an agent map domain terminology. No sibling is explicitly named, so it falls 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 description gives no when-to-use or when-not-to-use guidance and never references the alternative sevdesk_list_vouchers for broader retrieval. An agent can infer the direct-lookup intent from 'by id', but nothing is stated explicitly.

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 value by naming returned fields (IBAN, type, sync status), but does not disclose pagination behavior, default limits, or rate limits. With annotations handling the core safety trait, a 3 reflects moderate 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 description is front-loaded with the verb and resource, and the explanatory em-dash clause is efficient. The trailing 'sevdesk: GET /CheckAccount.' is a harmless API reference but not strictly necessary for tool selection, slightly reducing conciseness.

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

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

For a simple read-only list tool with no output schema, the description adequately covers what is returned (IBAN, type, sync status) and the domain context. It omits pagination behavior and full response shape, but those are either obvious from the schema or low-risk, making it nearly 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 all four optional parameters (embed, limit, offset, count_all) are already well documented in the schema. The description adds no additional parameter meaning or usage examples.

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 accounts), then clarifies the domain meaning with bank accounts, cash registers and clearing accounts. This distinguishes it from all sibling list tools (contacts, invoices, transactions) and tells the agent exactly what is returned.

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 usage by explaining what check accounts are, but gives no explicit when-to-use or when-not-to-use guidance, and never mentions the closely related sibling get_check_account_balance. The context is enough to infer purpose, but alternatives are left unaddressed.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds the underlying GET /CommunicationWayKey endpoint and the dependency on sevdesk_add_communication_way, but it does not disclose auth requirements, rate limits, or response representation beyond the enumerated keys, so it adds only moderate context over 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?

Two compact sentences that are front-loaded with the purpose and the actual key values, followed by the usage dependency and endpoint. Every element is useful and there is no redundant or filler text.

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 tool with readOnlyHint and no output schema, the description provides everything an agent needs: what the tool returns, the exact key values, why it exists, and the underlying endpoint. No critical gap remains.

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 has zero input parameters, so the baseline is 4. The description does not need to explain parameter semantics, and its enumeration of possible key labels adds useful domain context about the output rather than input parameters.

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 precise verb and resource: list the labels/keys a communication way can carry. It enumerates the actual key labels, making the resource concrete and distinguishable from sibling list_communication_ways, which lists actual communication ways rather than their 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?

It explicitly says the tool is 'Needed for sevdesk_add_communication_way', giving clear usage context. It does not, however, state when not to use it or point to an alternative such as sevdesk_list_communication_ways for retrieving existing communication ways.

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, so the description only needs to add context. It discloses the underlying endpoint (GET /CommunicationWay), which is mildly useful, but says nothing about pagination behaviour, total counts, or volume characteristics that the limit/offset/count_all params 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 tight sentences with the resource definition front-loaded and no filler. The trailing endpoint reference is compact and informative rather than wasteful, though it is not strictly necessary.

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

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

For a read-only, no-required-param list tool with fully documented parameters, the definition covers what is needed to invoke it correctly. There is no output schema, so the description could optionally say what a returned record contains, but the omissions are 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 description coverage is 100%, so every parameter is already documented in the schema, including the enum, limit bounds, and paging semantics; baseline 3 applies. The description's 'optionally for one contact' only restates what contact_id's schema description already says, adding no new meaning.

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 ('communication ways'), then defines the resource with parenthetical examples (emails, phones, mobiles, websites), so an agent knows exactly what entities come back. It does not name a sibling to distinguish itself from, and its relation to sevdesk_add_communication_way is left implicit.

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?

'optionally for one contact' implies the two usage modes: list everything, or scope to a single contact. There is no explicit when-to-use guidance, no mention of the write counterpart (sevdesk_add_communication_way) or of sevdesk_get_contact as an alternative path to contact data.

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 carry readOnlyHint=true, so the description usefully adds that the endpoint returns organisations only by default and that include_persons must be set to receive individual persons. This is meaningful non-obvious behavioural 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?

Three tight sentences, front-loaded with the resource and categories, then the key default-vs-expanded behaviour and the raw endpoint. 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 11-parameter read tool with no output schema and only a readOnlyHint annotation, the description covers the essential quirk (default organisation-only results). It could say more about pagination or the shape of results, but it is adequate.

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 the include_persons default and category_id values. The description restates include_persons rather than adding syntax or format detail beyond the schema, 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 (contacts) and enumerates the contact categories returned, so the agent knows exactly what this fetches. It doesn't explicitly contrast itself with the sibling sevdesk_get_contact, but the list-vs-get distinction is clear from the name and description.

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 notes the default behaviour and how include_persons changes results, which is useful invocation guidance. However, it gives no when-to-use direction relative to alternatives like sevdesk_get_contact or the list_communication_ways siblings, leaving routing partly 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 the safety profile is clear. The description adds the status code meanings (100 draft, 200 open/delivered, etc.) and confirms the GET /CreditNote endpoint, but does not disclose default pagination behavior, sort order, or response characteristics beyond what the schema 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?

Two compact sentences front-load the core action and filters, then provide status semantics and the underlying endpoint. Every clause earns its place, and no relevant detail 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 a read-only list tool with no output schema, the description covers the resource, filterable fields, status meanings, and endpoint. It could mention the default page size or return shape, but the schema already handles limit/offset and pagination expectations.

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. The description adds meaningful domain context by expanding the bare status codes into human-readable labels (draft, open/delivered, partially paid, paid), which the enum alone does not convey.

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

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

States a specific verb and resource: 'List credit notes (Gutschriften)'. The localized term and endpoint confirm the exact sevdesk entity, but the description does not explicitly distinguish this from sibling list tools such as list_invoices or list_vouchers.

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 verb ('List credit notes'), but there is no explicit guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The status code mapping helps interpret filters but does not route the agent between tools.

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 the safe-read profile, so the bar is lower. The description adds genuinely useful behavioral context by decoding status codes (50/100/200/750/1000) into business states and noting the underlying endpoint, which the annotations do not provide. It stops short of describing pagination defaults 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?

Three front-loaded clauses: purpose, filterable dimensions, then the status legend and endpoint. No filler, and the most useful detail (status semantics) is placed early. Slightly dense in the status run-on, but every element 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?

With 11 optional params, 100% schema coverage and a readOnly annotation, the definition covers purpose, filtering, and status semantics adequately. The one gap is that no output schema exists and the description says nothing about the returned shape or paging envelope (limit/offset/count_all interaction), which the agent must infer.

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 meaning the schema lacks: the status enum in the schema is bare codes with only 'Only invoices with this status code', while the description maps each code to a real state (draft, open/due, partially paid, paid). That is meaningful semantic enrichment of a 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 ('List invoices') and enumerates the filter dimensions, so the agent immediately knows this is the collection-retrieval counterpart to sevdesk_get_invoice. It does not explicitly name a sibling, but 'List' vs 'get' is self-evident from the naming.

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 'filterable by status, number, date range and contact' implies when the tool is useful (bulk/queried retrieval) but gives no explicit when-to-use vs. when-not, and never routes the agent to alternatives like sevdesk_get_invoice for a single record or sevdesk_list_credit_notes for a different document type.

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 context beyond that: the underlying sevdesk endpoint (GET /Order) and the meaning of each status code, which is behavioral knowledge not present in the structured fields. It stops short of describing pagination defaults 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?

Two dense sentences plus a short endpoint tag, front-loaded with the resource scope before filters and status semantics. No filler; every clause carries information an agent needs.

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?

No output schema exists, but the tool is a read-only list with zero required params and fully documented schema. The description supplies scope, filters and status semantics, which is sufficient; return-shape and paging-default details are the only minor omissions.

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, but the description genuinely adds parameter meaning by labeling the enum codes (100 draft, 200 delivered, 300 rejected, 500 accepted, 750 partially calculated, 1000 calculated) — labels the schema enum lacks. It also groups the filters by dimension (status, number, date range, contact).

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 immediately disambiguates the resource by enumerating the subtypes it covers — quotes (Angebote), order confirmations, delivery notes. This clearly separates it from sibling list tools such as list_invoices, list_credit_notes and list_vouchers.

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 names the available filters (status, number, date range, contact), which implies how the tool is meant to be used, but it never states when to choose it over the sibling list tools or any prerequisite/exclusion. Usage is only implied, matching a 3.

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 the safe-read profile, so the description's main added value is noting that records carry prices, tax rate and stock — useful return-shape context given there is no output schema. However, it omits pagination behavior, default limits, and total-count semantics, so it goes only modestly beyond the annotation.

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 the purpose front-loaded and no filler. The trailing 'sevdesk: GET /Part' is compact and useful for API mapping rather than padding.

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 low-complexity read-only list tool with full schema coverage and a readOnlyHint, the description covers purpose and record contents adequately. Only filters/pagination usage context is left implicit, which the schema largely supplies.

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 every parameter (name, part_number, embed, limit, offset, count_all) is documented in the schema itself. The description adds no parameter-level meaning, so the baseline of 3 is correct.

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 crucially disambiguates the ambiguous term by defining parts as 'the products and services in the sevdesk inventory'. This lets an agent distinguish it from invoice/contact/voucher listers without opening the schema, though it does not name a sibling it is not.

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 says what the tool returns but gives no when-to-use guidance, no conditions that select it over alternatives, and no exclusions. An agent must infer applicable scenarios entirely on its own.

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 scope context ('bank payments in and out') but says nothing about pagination defaults, the limit ceiling, or that count_all changes the response shape. Moderate added value on top of 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?

Two economical sentences: purpose and scope first, filter dimensions second, API mapping last. 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 read-only, zero-required-parameter list tool with no output schema, the description covers what is returned and what can be filtered, which is the bulk of what an agent needs. It could be slightly stronger by noting paging behavior, but nothing critical 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 every parameter is already documented with format hints (ISO 8601, 1-1000 limits, embed syntax). The description only groups the filter family at a high level, adding no new semantics beyond the schema, so baseline 3 applies.

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

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

Specific verb (List) plus resource (check-account transactions), with a clarifying gloss 'bank payments in and out' and a summary of the filter dimensions. It is clearly distinguishable from siblings such as sevdesk_list_check_accounts and sevdesk_get_check_account_balance.

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 usage by enumerating filter dimensions, so an agent can infer this is the read path for transaction listings. However, it never states when to prefer it over related tools (e.g. balance or account listing) nor any 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying endpoint (GET /Voucher) and semantic meaning for status and credit_debit codes, but says nothing about pagination defaults, rate limits, or auth needs. Adequate against an annotation that already carries the safety profile.

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 clauses, zero padding, and the purpose is front-loaded before the filter-code reference. Every sentence earns its place; the trailing endpoint note is a minor but harmless implementation hint.

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, zero-required list tool with no output schema, the description covers purpose and the non-obvious enum semantics, while the schema handles pagination and filtering parameters. It stops short of describing the return shape, though without an output schema that gap 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 100%, so baseline is 3, but the description goes beyond the schema by decoding the enum values the schema only lists: 50=draft, 100=unpaid/due, 1000=paid, and C/D=credit/debit. That mapping is genuinely useful domain knowledge not derivable from the raw enums.

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 ("List vouchers") and clarifies the domain meaning of "voucher" as receipts and incoming/outgoing bills, which distinguishes it from sibling list tools like sevdesk_list_invoices or sevdesk_list_credit_notes. It does not explicitly name or contrast with those siblings, 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?

Usage is implied by the list semantics and the filter codes, but there is no explicit when-to-use guidance, no distinction from sevdesk_get_voucher for single lookup, and no note on paging strategy. The status/credit_debit code map helps the caller filter, but doesn't route between 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 destructiveHint=true, so the safety profile is partly covered. The description adds a genuinely useful trait beyond the annotations — 'only the fields you pass are sent' (partial-update/PUT-with-merge semantics) — but says nothing about reversibility, side effects such as organisation-vs-person conversion, or required permissions.

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 plus an endpoint reference, with the core semantics ('only the fields you pass are sent') front-loaded. Every element carries information and 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 a 12-parameter mutation the schema does most of the work and the partial-update behavior is covered, but the description omits consequences of the destructive update (e.g. whether omitted fields are cleared vs preserved is only partly answered) and any note on side effects or auth.

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 12 parameters are already documented in the schema, including the non-obvious ones (surename spelling, status codes, category ids). The description adds no parameter-level meaning beyond that, so the baseline of 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 (update) and resource (contact), and clarifies the scope is 'an existing contact'. It does not name or distinguish itself from siblings like sevdesk_create_contact or sevdesk_get_contact, so the differentiation is only implied.

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 'existing contact' implicitly signals this is for modifications rather than creation, but there is no explicit when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as sevdesk_create_contact for new records.

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