Lexware Office MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the description does not need to restate that it writes. It does add real value beyond them: the number is assigned by Lexware, uniqueness must be guarded by pre-checking list_contacts, and per-contact limits (one billing, one shipping, one email, one phone). It omits auth/permission needs and duplicate-handling behavior, so not 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?

Five short sentences, front-loaded with the "WRITE:" signal and ending with the endpoint. Every clause carries a distinct constraint (identity path, cardinality limits, duplicate check, HTTP target); nothing is redundant with the title.

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

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

For a 20-parameter, mutation, non-idempotent tool with no output schema and zero required fields in the schema, the description covers the essentials an agent needs: identity requirements, cardinality caps, and the duplicate-avoidance step. It does not cover role defaults, the meaning of the xrechnung/contact-person field clusters, or what the response returns, leaving some 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 coverage is 70%, so the baseline is 3, but the description adds cross-field semantics the schema never states: company_name and person_last_name are mutually alternative identity paths, and email/phone/address are singular. It leaves the roles enum (customer/vendor default), note, tax_number, and the contact_person_*/xrechnung_* fields unexplained.

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?

Opens with a specific verb+resource ("WRITE: creates a new customer and/or vendor in Lexware Office") and adds distinguishing scope: the number is server-assigned, and address/email/phone cardinality is capped. This clearly separates it from the read-side siblings lexware_get_contact, lexware_list_contacts, and the create_draft_* tools that operate on other resources.

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 rules ("company_name for a company OR person_last_name for a private person") and a prerequisite workflow ("Check lexware_list_contacts first to avoid duplicates"), naming a sibling tool explicitly. There is no explicit when-not-to-use or guidance on choosing between customer and vendor roles, so it stops short of a 5.

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?

With annotations already declaring readOnlyHint=false and destructiveHint=true, the description still adds real value: the draft is never finalized, numbered or sent, Lexware assigns the number only on finalization, prices are EUR, and the call returns id + lexwareAppUrl. It does not warn about the consequence of idempotentHint=false (repeat calls create duplicate drafts), which is a meaningful remaining gap for a non-idempotent write.

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 'WRITE:' marker and the draft semantics, then address handling, then currency, then return values. Every sentence carries distinct information with no filler, which is impressive given the surface area of the tool.

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 21-parameter mutation with no output schema, the description covers the essentials: what is created, its non-finalized lifecycle, how to address it, currency, and what is returned. The missing piece is behavior under repeated invocation and any preconditions on customer role/feature flags, so it is strong 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 schema already documents all 21 parameters, including the contact_id vs name+country_code choice and the EUR pricing rule. The description largely restates those rules rather than adding syntax, ordering or validation 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?

Opens with an explicit 'WRITE:' verb+resource marker and states precisely what is created: an invoice in Lexware Office as a DRAFT that is never finalized, numbered or sent. It also names the endpoint (POST /v1/invoices without finalize) and the two addressing modes, making it clearly distinguishable from read siblings and from lexware_create_draft_quotation.

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 conditional guidance: address to an existing customer via contact_id OR a one-time address via name + country_code, and explains the follow-up (review and finalize in Lexware Office). It stops short of naming alternatives or exclusions (e.g. when to prefer lexware_create_draft_quotation or a finalized-invoice path), so it is strong context without explicit tool routing.

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=false and destructiveHint=true, so the write nature is covered; the description adds genuinely new behavior — the result is always a DRAFT that is never finalized or sent, plus the POST /v1/quotations (without finalize) shape. It still omits failure modes and duplicate-creation/idempotency behavior, so not 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 compact block, front-loaded with the 'WRITE' marker and the DRAFT constraint, with no filler sentences. Every clause carries operational 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?

With 19 parameters, no output schema, and no nested objects, the description usefully fills the return-value gap by naming the returned id and lexwareAppUrl, and it clarifies the draft lifecycle. It leaves out permission/scope requirements and error behavior, so it is slightly short of 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 every parameter is already documented (contact_id vs name+country_code, EUR pricing, tax_type semantics). The description only restates the address either/or and the EUR currency, adding little 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 precise verb and resource ('creates a quotation (Angebot) in Lexware Office as a DRAFT') and immediately scopes it away from the finalized/sent variant. An agent can distinguish it from lexware_create_draft_invoice and lexware_get_quotation 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?

Clear context: use it when you want an unfinalized quotation addressed either to an existing contact_id or to a one-time address (name + country_code), and it points the agent to Lexware Office for finalization. It does not explicitly state when to prefer this over the sibling draft-invoice tool or exclusions, so it falls short of a 5.

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 safe-read profile, and the description's 'GET /v1/articles/{id}' largely restates that. It does add the shape of the returned record (title, type, article number, GTIN, price, tax rate), which is genuine value given no output schema, but it says nothing about missing-id behavior or error handling.

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

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

A single dense sentence front-loads the action and resource, then compresses the return payload into a scannable list, ending with the 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 a one-parameter read with no output schema, the enumerated field list substitutes well for a return-value spec. Only notable gap is the absence of any note on what happens when the id does not exist.

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 the schema's own 'id' description already tells the agent it is the article id and where to obtain it. The description adds no 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 and resource ('Get one article (product or service) by id') and enumerates the returned fields, which cleanly separates it from the sibling lexware_list_articles. An agent can distinguish single-fetch from list without opening either schema.

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

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

The 'by id' phrasing implies this is the lookup path when an id is already known, but there is no explicit statement of when to use this versus lexware_list_articles or where the id comes from. Usage is implied rather than 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?

readOnlyHint=true already declares this is a safe read, and the description adds useful context about the payload contents (status, items with posting categories, tax amounts, contact, file ids) and the lexwareAppUrl. It still says nothing about error behavior (e.g., not-found), auth needs, or pagination, which is an acceptable gap given annotation coverage.

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

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

Front-loaded with the verb and resource, followed by the return contents and the underlying endpoint. Three dense clauses, all earning their place, though the field enumeration is list-like and slightly dense.

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

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

No output schema exists, so the description usefully summarizes the returned fields and the app link, and it identifies where the id comes from. It is nearly complete for a simple getter, missing only failure/permission behavior.

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

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

Schema coverage is 100% and the single id parameter is fully documented there, including its UUID pattern and origin. The description's "by id" adds no syntax or format detail beyond the schema, so it correctly sits at 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 specific verb and resource (get one bookkeeping voucher) and enumerates the concrete voucher subtypes it retrieves, so an agent can distinguish it from siblings like lexware_get_invoice or lexware_list_vouchers 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?

The parenthetical "from the voucher list" implies the id originates from lexware_list_vouchers, and the schema repeats that source. However, there is no explicit when-to-use vs when-to-prefer-an-alternative guidance or prerequisite statement; usage is only 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 is already declared, so the safety profile is covered. The description adds real behavioral context beyond that: the resolved entity can be a customer and/or vendor, the response includes contact persons and addresses, and it returns lexwareAppUrl. It does not, however, mention the endpoint's error case (unknown id) or pagination/embed options.

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 front-loaded sentence that leads with the verb and resource, then the returned fields, then the URL convenience and the underlying 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?

With no output schema, the description usefully previews the response shape and flags lexwareAppUrl. For a single-id read this is largely complete, though the 'customer and/or vendor' ambiguity and missing error behavior leave 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?

Only one parameter, and the schema documents it at 100% coverage including the UUID pattern and its origin. The description repeats 'by id' but adds no 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 and resource ('Get one contact') scoped by id, and enumerates the returned data (customer/vendor numbers, contact persons, addresses, emails, phones, note). This clearly separates it from the sibling lexware_list_contacts, which returns many.

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 required id, and the schema description points to lexware_list_vouchers / lexware_list_contacts as the source of that id. There is no explicit when-to-use or when-not-to-use statement relative to the list siblings.

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 rest and does so well: it discloses the returned contents (status, line items, totals, related invoice), the presence of a lexwareAppUrl deep link, and the underlying GET /v1/credit-notes/{id} call. No auth, rate-limit, or error/404 behavior is mentioned, which keeps it short of a 5.

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

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

Two short sentences, front-loaded with the verb and resource, with the return fields listed compactly. The trailing 'GET /v1/credit-notes/{id}' restates the tool name/resource somewhat redundantly, but everything else 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 no output schema in play, the description's enumeration of returned fields is exactly the compensating detail needed, and the single-parameter surface keeps the scope small. The main gap is that it never says what to do if the id is invalid or where the id comes from within the description itself.

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 a single required 'id' parameter, so the baseline is 3. The description only restates 'by id' and adds no format, provenance, or lookup detail 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 and resource ('Get one credit note by id') and enumerates the payload it returns (status, line items, totals, related invoice). It is self-evidently distinct from the other get_* siblings by resource name, but it never explicitly names an alternative or clarifies why you'd want a credit note versus an invoice or quotation.

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 'by id' phrasing implies a lookup-after-listing workflow, but there is no explicit when-to-use/when-not-to-use guidance and no reference to lexware_list_vouchers (which the sibling schema mentions as the source of ids). An agent must infer the routing itself.

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 carries a lighter burden. It adds genuine value beyond the annotation by disclosing the content shape (status, line items, shipping conditions) and the presence of lexwareAppUrl deep-link, which matters when no output schema exists.

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 core action front-loaded, followed by return content and the REST path. Nothing is wasted, though the trailing 'GET /v1/delivery-notes/{id}' is mildly redundant given the tool name and schema.

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

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

For a single-param read tool with readOnlyHint and no output schema, the definition covers what it needs: the resource, the key input, the returned fields, and the deep-link field. Only the absence of explicit when-to-use guidance keeps it from being 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 coverage is 100% and the single id parameter is fully documented with its UUID pattern and provenance ('from lexware_list_vouchers'). The description adds nothing beyond 'by id', so the baseline 3 is appropriate when the schema does all 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 ('Get one delivery note by id') and even lists the content returned (status, line items, shipping conditions), so an agent can identify it immediately. It doesn't explicitly differentiate itself from the numerous other lexware_get_* siblings, but the resource name is distinct enough to separate 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: fetch a single delivery note by id. There is no when-to-use framing, no mention of prerequisites, and no routing to or from alternatives like lexware_list_vouchers, which is referenced only as a source of the id in the schema.

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 context beyond them: it discloses that the response includes lexwareAppUrl (a link into Lexware Office) and enumerates the returned content, and it names the underlying endpoint. It does not mention error/not-found behavior or auth scoping, which keeps it short of a 5.

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

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

Compact and front-loaded: resource and lookup key come first, then the returned payload, then the raw endpoint. The colon-chained fragments are dense but readable. Every element earns its place; the trailing raw endpoint is the only arguably redundant piece.

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 partially carries the burden of describing the return value, and it does list status, amounts, related closing invoice, and lexwareAppUrl. For a single-parameter read tool with a readOnly annotation, that is close to complete; only failure modes and the exact shape of the amounts are unstated.

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

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

Schema coverage is 100% and the single id parameter is fully documented in the schema, including its UUID pattern and provenance. The description adds nothing beyond 'by id', so the schema does all the work and 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 (get), a specific resource (one down payment invoice / Abschlagsrechnung, singular), and the retrieval key (by id). The German term and the named return fields (status, amounts, related closing invoice) make it distinguishable from siblings like lexware_get_invoice or lexware_get_credit_note 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?

The description implies retrieval by id and even points at the source of that id (lexware_list_vouchers), which is helpful routing. However it gives no explicit when-to-use guidance and never names an alternative or a when-not condition (e.g., when to prefer lexware_get_invoice or the list endpoint), so usage is only 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes further by disclosing the response shape (status, relatedVouchers, line items, totals) and the lexwareAppUrl deep link, which is genuinely useful since no output schema exists. It stops short of noting auth or rate-limit behavior.

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

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

Front-loaded with the purpose, then the payload, in two tight sentences. The trailing 'GET /v1/dunnings/{id}' is mildly redundant with the name and schema but is compact and 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?

With no output schema, the description compensates by naming the returned fields, and it identifies the id source for input. For a single-parameter read tool this is close to sufficient; only error/not-found behavior is 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?

Only one parameter, and schema coverage is 100% — the schema documents the UUID pattern and its source (lexware_list_vouchers). The description's 'by id' adds no 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 and resource ('Get one dunning (payment reminder) by id') and enumerates the salient returned data (status, dunned invoice, line items, totals, lexwareAppUrl). An agent can distinguish it from the many sibling getters (invoice, quotation, credit note, etc.) because the resource 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 implied: retrieve a single dunning when you already have its id. There is no explicit when-to-use vs. when-not guidance and no reference to lexware_list_vouchers as the lookup step (that hint lives only in the schema). Adequate but leaves routing 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?

readOnlyHint=true already establishes the safe-read profile, and the description adds genuinely useful context beyond it: the set of fields returned, the included lexwareAppUrl deep link, and the concrete HTTP route GET /v1/invoices/{id}. It does not mention error behavior for a missing/invalid id, so it stops short of a 5.

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

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

A single dense sentence front-loads the operation and then lists the payload fields with no filler; the endpoint is appended as a compact suffix. Every clause earns its place, though the trailing endpoint is arguably redundant with 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?

With no output schema, the description correctly compensates by enumerating the returned fields (status, line items, totals, tax, payment/shipping conditions, lexwareAppUrl). Nothing essential for invocation is missing, though it could note behavior when the id does not exist.

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?

There is one parameter and schema coverage is 100%, including the 'from lexware_list_vouchers' provenance note, so the schema already carries the semantics. The description's 'by id' adds nothing the schema does not.

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 one invoice by id') and enumerates what the record contains (status, line items, totals, tax amounts, payment/shipping conditions, related vouchers), which cleanly separates it from sibling getters like lexware_get_credit_note or lexware_get_quotation. The endpoint path reinforces the operation.

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 single-record lookup intent is clear and the sibling name-set makes the resource obvious, but there is no explicit when-to-use/when-not guidance or pointer to alternatives (e.g., lexware_get_payments or lexware_list_vouchers). Usage is implied rather than 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 safety is covered. The description adds real value beyond them by disclosing the returned field set and the presence of lexwareAppUrl, a link that opens the record in Lexware Office — an unusual side-output an agent should know about. It does not cover auth or not-found behavior.

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 resource and result shape, ending with the endpoint. Nothing redundant and 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 read-only single-resource fetch with no output schema, the description usefully compensates by listing the returned sections. The only gap is error/not-found behavior and any pagination or embedding options, which are 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?

There is a single parameter with 100% schema description coverage, including a UUID pattern and the note that the id comes from lexware_list_vouchers. The description says only 'by id' and adds no format or sourcing 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?

Names a precise verb and resource ('Get one order confirmation by id') and enumerates the payload it returns: status, line items, totals, delivery terms. The resource name alone separates it from the many sibling getters (get_invoice, get_delivery_note, get_quotation), and the endpoint snippet confirms the exact REST path.

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: fetch a single order confirmation when you have its id. The description gives no explicit when-to-use or when-not guidance, and does not name alternatives such as lexware_list_vouchers (the schema description carries that routing hint instead). Adequate but leaves selection logic 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 only declare readOnlyHint=true, and the description meaningfully adds the supported resource types, the unsupported ones (quotations, drafts), the exact fields returned, and the underlying endpoint. It does not cover auth/permission needs or behavior for invalid or unbalanced vouchers, keeping it short of a 5.

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

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

A single dense sentence covering scope, exclusions, and return fields, followed by the endpoint. The field enumeration makes it a little list-heavy, but no sentence is wasted and the scope constraint 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?

With no output schema, the description carries the return-value burden and does so by naming the fields and enumeration values (balanced/openRevenue/openExpense). Combined with the readOnly annotation and 100%-covered schema, an agent has nearly everything needed; only error/edge-case behavior is 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% and there is a single parameter, so the schema already documents voucher_id including its origin (lexware_list_vouchers) and UUID pattern. The description adds no further parameter meaning, making the baseline 3 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?

Specific verb+resource (get a voucher's payments) with the exact return payload enumerated (open amount, status, paid date, payment items). It scopes the eligible voucher types (invoice, credit note, down payment invoice, bookkeeping voucher) and explicitly excludes quotations and drafts, which cleanly separates it from siblings like lexware_get_invoice or lexware_get_quotation.

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

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

Gives an explicit when-not ('Not available for quotations or drafts') and implicitly defines the use case through the enumerated voucher types and returned payment fields. It stops short of routing the agent to a specific alternative tool (e.g., lexware_get_invoice) when the voucher is a quotation or draft, so it is clear context without full alternative 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 readOnlyHint annotation already establishes the safe-read behavior. The description adds return-field semantics beyond the annotation, including tax type values, the small-business flag, distance-sales principle, and plan features, though it does not mention permissions, rate limits, or error behavior.

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 resource and its returned fields, then adds the practical "Good first call" guidance and endpoint. Every element earns its place, with no filler.

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

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

With no output schema, the description compensates by enumerating the key return fields and their meaning. For a zero-parameter, read-only profile tool with a readOnlyHint annotation, no critical context 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?

This tool takes no parameters, so the baseline for parameter semantics is 4. There are no parameters whose meaning the description would need to clarify.

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

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

The description names the specific resource (the connected Lexware Office organization) and enumerates several returned fields, making the tool's purpose clear. It stops short of an explicit verb in the description body, but the title and endpoint make the action unambiguous.

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

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

"Good first call" gives clear context for when to use this tool, which is useful for a profile-fetch operation. There are no exclusions or sibling alternatives named, but the tool is distinct from the many get/list/create siblings.

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, and the description adds real value beyond that: which fields come back (status enum values, expiration, line items, totals) and the lexwareAppUrl deep link. The underlying endpoint GET /v1/quotations/{id} further anchors the behavior. It does not discuss pagination or empty/error behavior, but for a single-record fetch that is minor.

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

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

Front-loaded with the core action and the returned payload in one tight sentence; the endpoint token is arguably redundant but aids debugging. No filler or restated 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 must carry the return-value burden, and it largely does by naming the key fields and the deep link. Combined with rich annotation and schema coverage, an agent has enough to call this correctly; only edge-case behavior is 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% and the single id parameter is fully described there (including its UUID pattern and the list_vouchers provenance). The description only echoes 'by id' and adds no format or sourcing detail beyond the schema, 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 and resource ('Get one quotation by id') and enumerates what the response contains (status, expiration date, line items, totals). This cleanly separates it from sibling getters for invoices, credit notes, and delivery notes, though it never names a sibling directly.

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: retrieving a single quotation by id after it has been listed. There is no explicit statement of when to prefer this over lexware_list_vouchers or how the id is obtained (that hint lives in the schema, not the description). No exclusions or prerequisites are given.

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 genuinely useful behavior: results are paged and the next page token is fed back in as 'page'. It says nothing about rate limits, auth requirements, default ordering, or total counts, which is acceptable for a simple read-only list 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?

Three tight sentences, front-loaded with the resource identity, then filters, then pagination. No filler; the trailing endpoint reference (GET /v1/articles) costs little and no sentence overstays its usefulness.

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 correctly compensates by naming the core returned fields (price, tax rate, unit) and by explaining the paging contract. It is close to complete for this tool; only the absence of ordering/sorting behavior and total-count semantics keeps it from a 5.

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 slightly beyond the schema by grouping the filters conceptually as 'exact' matches and by revealing that 'next_page' originates from the previous reply (a response-side detail absent from the input schema and from any output 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 and resource ('List articles') and immediately clarifies the domain meaning ('products and services usable as invoice line items') with the returned fields (price, tax rate, unit). This distinguishes it from the singular sibling lexware_get_article and from the other list_* tools without the agent needing to open a schema.

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

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

It states the conditions for the optional filters ('exact filters by article number, GTIN or type') and explains pagination mechanics ('Paged: pass next_page as page'), giving clear operational context. It stops short of explicit when/when-not guidance — e.g. it never says to use lexware_get_article when a single article is known — so there is no exclusion language.

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 still adds real behavior beyond the annotation: AND-combined filters, case-insensitive substring matching with a 3-character minimum, wildcard characters, and the next_page-to-page pagination handoff.

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

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

Three dense sentences, front-loaded with what the tool returns and how filtering works, ending with the endpoint. 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 7-parameter read-only list with no output schema, the description covers filtering, matching rules, and pagination adequately. It does not describe the shape of a returned contact, but with readOnly annotations and thorough schema docs this 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 coverage is 100%, so baseline is 3 and the schema already carries per-parameter meaning. The description adds value by explaining that filters are AND-combined and that name/email match as case-insensitive substrings with wildcard support, semantics not restated in the schema.

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

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

Specific verb ('List') plus resource ('customers and vendors' / contacts) and scope ('optionally filtered'). It is clearly a list/search operation, distinguishable in spirit from lexware_get_contact, but it never explicitly contrasts the single-fetch sibling, so full sibling differentiation is missing.

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 conveys how to use filters ('filters combine with AND') and the paging convention, which is implied usage. However it never states when to prefer this over lexware_get_contact or lexware_create_contact, and offers 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 already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine behavioral value by enumerating the returned fields and the tax-classification values (de, intraCommunity, thirdPartyCountry), plus the underlying GET endpoint. It omits auth and pagination behavior, but for a small static reference list that is minor.

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: the payload description is front-loaded and the endpoint follows as supporting detail. Every clause earns its place with no filler.

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

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

With no output schema, the description is the only source of return-value information, and it delivers that well. It is complete for a no-parameter reference-list call, though it could note that the full set is returned without pagination.

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 the baseline is 4. The description correctly implies no filtering or pagination inputs exist and adds nothing misleading about invocation.

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

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

States a specific verb ('List') and resource ('Countries known to Lexware Office') and further specifies the returned payload fields (code, English and German name, tax classification). No sibling tool could be confused with a country reference lookup.

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

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

The description gives no when-to-use guidance, no indication of whether this is reference data to resolve country codes for other calls, and no exclusions. Usage is only inferable from the name, so this is essentially unstated.

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 context by enumerating the returned fields and citing the GET endpoint, but says nothing about ordering, pagination, or whether the list can be empty.

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 with the resource stated first; the only marginal element is the raw endpoint string, which is minor noise rather than filler. Nothing 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, the description usefully enumerates the fields returned, which is exactly the burden it must carry. It is complete enough to call, missing only return-shape details like ordering or defaults 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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond confirming no filtering arguments exist.

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?

It names the specific resource (payment conditions configured in Lexware Office) and enumerates the concrete attributes returned: days until due, early-payment discount, label template, and organization default. This distinguishes it from generic list siblings, though it never explicitly contrasts itself with any alternative.

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 resource being listed, and there is no competing sibling for payment conditions, but the description offers no explicit when-to-use or triggering context (e.g., before invoice creation). Adequate but not guiding.

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 and the description's burden is lower. The description adds the useful filter behavior (income vs. outgo scoping) but says nothing about pagination, ordering, rate limits, or auth, so it remains a modest supplement rather than rich behavioral 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?

Front-loaded with the resource and its fields, then the filter option, then the endpoint. The dense parenthetical field list is information-rich rather than padding, though the trailing 'GET /v1/posting-categories' adds little 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?

With no output schema, the description usefully enumerates the returned fields (id, name, group, income/outgo, contact requirement, split tax rates) plus the linkage to voucher categoryId, which is what an agent needs to consume the result. Only pagination/ordering behavior is unaddressed for this simple read tool.

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 the single enum parameter is fully documented in the schema with the same income/outgo wording. The description's 'Optionally only income or outgo' merely restates 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 (bookkeeping posting categories), and even enumerates the fields the resource carries. It also ties the resource to its consumer ('used by bookkeeping vouchers' categoryId'), which orients the agent. It does not name a sibling tool to contrast against, 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 clause 'Optionally only income or outgo' implies the filtering use case, and the categoryId link hints at why an agent would call it. There is no explicit when-to-use vs. when-not, and no statement of prerequisites or alternatives among the sibling list/get 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?

Annotations only declare readOnlyHint=true, and the description meaningfully extends this: it discloses the 10,000-result pagination ceiling with mitigation advice, the German-time whole-day date semantics, and the underlying GET /v1/voucherlist endpoint. It does not describe response envelope shape, but the returned metadata fields are enumerated.

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?

Dense but front-loaded: the core purpose and return contents come first, then routing, then date/pagination constraints. It is long and paragraph-heavy, but nearly every clause carries information an agent needs to call the tool correctly, so little is wasted.

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

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

For a 15-parameter, zero-required filter tool with no output schema, the description covers purpose, defaults, date format/timezone, pagination limits, and downstream routing – enough to invoke it correctly. Minor gaps remain around result ordering guarantees and how the 10,000 cap interacts with next_page, but the essentials are present.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real semantic value on top by clarifying that omitted voucher_types/voucher_statuses mean 'all' and that dates are yyyy-mm-dd evaluated as whole days in German time. It does not restate enum nuance already documented in the schema (e.g. overdue exclusivity).

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

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

The description names a specific verb+resource ('Search the voucher list'), enumerates the exact document and bookkeeping voucher types returned, and lists the metadata fields returned. It is clearly distinguishable from every sibling list/get tool because it explicitly maps each type to its corresponding lexware_get_* 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?

It gives explicit filtering guidance ('Omit voucher_types / voucher_statuses for all') and a full when-to-use-the-alternative routing table (invoice → lexware_get_invoice, etc.). The recommendation to narrow dates when exceeding the 10,000-result cap is also actionable usage guidance.

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