Papierkram MCP by usefulapi

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

Adds real context beyond the annotations: the customer number is server-assigned, nothing is sent to the contact, and the call consumes API credits with a stated rate and monthly quota. Annotations already cover safety (readOnly=false, destructive=false, idempotent=false), so the credit/quota warning is the valuable extra. It stops short of saying whether the created record is returned or how to retrieve the assigned number.

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

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

Four short sentences: operation, side effect, dedupe prerequisite, cost. Front-loaded verb and no wasted clauses — the credit cost is the only arguably optional detail and it is genuinely decision-relevant for a quota-limited API.

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 14-parameter creation tool with no output schema, the definition covers the mutation semantics, dedupe workflow, and cost budget. The remaining gap is what comes back (does the response include the assigned customer number?) — minor since the schema is fully documented.

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

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

Schema description coverage is 100%, so every one of the 14 parameters is documented inline including both enums. The description adds no parameter-level detail, but the schema already does the heavy lifting, 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?

Opens with 'WRITE: create a contact (company)' — an explicit verb plus precisely-scoped resource that separates it from papierkram_create_person and papierkram_create_invoice. The 'WRITE:' prefix also frames the operation type immediately.

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

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

Gives an explicit prerequisite ('Check papierkram_list_companies first to avoid duplicates') and names the sibling tool to use for that check. It also implies the read-side counterpart for verification, leaving little 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by disclosing that the record is only a draft with no invoice number and requires user completion in Papierkram, and by quantifying cost (10 credits to create, 50 for an invoice) against a limited monthly quota. That is exactly the kind of side-effect and resource-cost context annotations cannot express.

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

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

Three dense sentences, front-loaded with the 'WRITE:' action type and the draft-state caveat, then prerequisites, then verification and cost. 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?

For an 11-parameter mutation with no output schema, the description covers state semantics, required inputs, verification path, and credit cost, which is nearly everything an agent needs. The missing piece is minor: it doesn't mention all four required fields (name, customer_id) or the gross/net pricing switch, leaving those to the schema.

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

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

Schema coverage is 100%, so every parameter including the nested line-item fields is already documented, which sets the baseline at 3. The description reinforces two required inputs (payment_term_id source, at least one line item) but adds no syntax or constraint detail beyond the schema; notably it omits the gross/net pricing nuance and customer_id sourcing that the schema carries.

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 DRAFT outgoing invoice') and pins the resulting state (draft, not finalized or sent, no invoice number until completed in Papierkram). The 'WRITE:' prefix and 'create' verb distinguish it from the get_/list_/update_ siblings at a glance.

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 prerequisites: a payment term id sourced from papierkram_list_payment_terms and at least one line item, plus a follow-up path via papierkram_list_invoices to verify. It does not explicitly state when NOT to use it (e.g. correcting an existing invoice vs. creating a new one), so it falls just short of full alternative 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, destructiveHint=false, idempotentHint=false and openWorldHint=true, so mutation and non-idempotency are covered structurally. The description adds genuinely new context: no notification is dispatched to the contact, and the call consumes API credits (10 per create vs 50 per invoice) against a limited monthly quota — a real cost constraint an agent must know before retrying.

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 WRITE tag and the core operation before the cost note. Efficient, though the parenthetical credit/quota detail is slightly dense and could be trimmed without losing the key warning.

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 creation tool with full schema coverage, no output schema, and annotations carrying the safety profile, the description covers operation, side effects and rate-limit/cost behavior. It stops short of saying what is returned (e.g. the new person id), which an agent would want after a create.

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 all 10 fields (company_id, first_name, last_name, email, phone, etc.) are documented in the schema itself. The description adds no field-level semantics beyond that, 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?

The description opens with an explicit operation tag ("WRITE") and a precise verb+resource: "add a contact person to an existing company." The scope qualifier ("to an existing company") separates it cleanly from list_persons / get_person and from the other create_* siblings, which target different 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?

It implies the precondition that the company must already exist, and "Nothing is sent to the person" tells the agent this is a silent record creation. However, it names no alternatives (e.g. use papierkram_create_company when the company itself doesn't exist yet) and gives no explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the write semantics are covered structurally. The description adds genuinely new information the annotations cannot convey: API credit costs (10 per create, 50 per invoice) and a limited monthly quota, which directly affects whether an agent should batch or retry. Minor gap: it doesn't say a retry creates a duplicate project.

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: the first front-loads the action with a 'WRITE:' marker, the second carries the cost warning. No repetition of schema content and nothing extraneous.

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?

The cost/quota disclosure covers the main non-obvious risk for a 9-parameter write tool. But with no output schema, the description should say what comes back (presumably the created project and its id) so the agent knows how to chain follow-up calls; that gap is left entirely to guesswork.

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 nine parameters, including enum values, date formats, and the budget_type/budget_time branching, are documented in the schema itself. The description adds nothing beyond the fact that a customer is involved, 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?

The verb+resource pair ('create a project') is explicit, and the 'WRITE:' prefix immediately separates it from the get_/list_ siblings such as papierkram_get_project and papierkram_list_projects. It stops short of naming an alternative tool, but the create/get/list split is 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?

'create a project for a customer' implies the usage context (a customer must already exist), and the schema points to papierkram_list_companies for customer_id. However, there is no explicit when-to-use/when-not statement or reference to papierkram_update_company-style siblings for later edits, 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 readOnly=false, destructive=false, idempotent=false and openWorld=true, so the mutation profile is covered structurally. The description adds genuinely new context beyond annotations: creation consumes 10 API credits against a limited monthly quota, and the "WRITE:" prefix front-loads the mutation. It does not say whether duplicate article numbers are rejected or what the response 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?

A single sentence, front-loaded with the WRITE marker and the resource, followed by the credit-cost caveat. No filler and no repetition of schema content beyond the one necessary word "price".

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 nine parameters, five required, no output schema and no nested objects, the credit cost and quota warning cover the main hidden risk. However, the description never indicates what comes back from a successful create (presumably the new proposition id needed for invoicing), nor any prerequisite/order-of-operations detail, leaving a meaningful gap for a mutation 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%, so every one of the nine parameters is already documented in the schema, including the vat_rate format hint pointing at papierkram_get_proposition. The description only echoes "with a price", adding little beyond the structured fields, 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 ("create a stored product or service (Leistung/Artikel) with a price"), which distinguishes it from the create siblings for invoices, persons, projects, tasks and time entries by resource alone. It does not explicitly differentiate itself from papierkram_get_proposition or papierkram_list_propositions, but the write/store semantics are unambiguous.

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

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

The only guidance is a cost warning about API credits and the monthly quota, which is a budgeting constraint rather than a when-to-use rule. Nothing tells the agent when to create a new proposition versus updating or reusing an existing one from papierkram_get_proposition, nor that this must precede invoicing.

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, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context beyond them: API credit cost per create and a limited monthly quota, which is a real operational constraint an agent should weigh before calling.

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 waste, with the WRITE intent and the resource front-loaded ahead of the cost caveat. Every clause earns its place.

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

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

A mutation tool with no output schema but full annotation and schema coverage; the description adds the quota caveat that neither structured field carries. It stops short of saying what a successful call returns (e.g. the new task id) or what happens on quota exhaustion.

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 is documented inline, including which list tool supplies each id. The description adds nothing about parameters, 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 (create) and resource (a time-tracking task in a project), prefixed with an explicit WRITE marker. It does not, however, differentiate itself from the nearby siblings papierkram_create_time_entry or papierkram_create_project, which an agent could plausibly confuse with 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?

The description gives no when-to-use or when-not-to-use guidance and never names an alternative tool. It implies scoping ('in a project') but leaves the task-vs-time-entry decision entirely 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?

Goes well beyond the annotations by disclosing that the entry is unbilled until invoiced and, critically, that each call consumes API credits (create 10, invoice 50) against a limited monthly quota — the kind of cost/rate-limit information an agent cannot get from readOnlyHint/destructiveHint alone. The mutation framing is also consistent with readOnlyHint=false, so no contradiction.

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 with the operation type front-loaded as "WRITE:", followed by billing semantics and cost. No filler, no repetition of schema fields, and the highest-stakes information (credit cost) is placed where it will be read.

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 mutation with full schema coverage and clear annotations, the description supplies the missing non-schema context: costs, quota, and billing status. The only gap is that with no output schema it does not say what comes back (presumably the created time entry and its id), leaving the agent unsure how to reference the entry afterwards.

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 (task_id, user_id, entry_date, started_at_time, ended_at_time, comments, unbillable) is already documented with format hints and source tools. The description adds only the "on a task" framing, which slightly reinforces task_id's importance but adds no new format, default, or constraint detail. 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 specific verb+resource combination ("record a time entry") and narrows scope with "on a task", so an agent can immediately tell this creates a task-linked time entry rather than a project, invoice, or person. It stops short of explicitly contrasting with siblings like papierkram_get_time_entry or papierkram_list_time_entries, relying on naming convention for that separation.

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 leading "WRITE:" tags this as a mutation and the "Not billed until an invoice is made" line implies when the record matters downstream, but there is no explicit statement of when to prefer this over the get/list time-entry siblings or what prerequisites (task must exist, user must exist) are assumed. Usage is inferable but not spelled out.

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, and the description adds nothing on top: no behavior for an unknown/nonexistent id, no indication of what the returned object contains, no notes on permissions. It is consistent with the annotations but contributes no 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?

A single seven-word sentence, front-loaded with verb and resource, with no filler. Brevity here is appropriate, though the space saved is not used for any useful qualification.

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

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

For a one-parameter read tool with annotations covering the safety profile and no output schema, the definition is adequate but thin. An agent still lacks error behavior for missing ids and any hint of the returned record's shape.

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 id property already documents its type, format, and origin ('from papierkram_list_bank_transactions'). The description only repeats 'by id', adding no semantics 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 concrete verb+resource ('Get one bank transaction') and the lookup key ('by id'), which cleanly separates it from the sibling papierkram_list_bank_transactions. It doesn't name that sibling 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 description gives no when-to-use guidance, no prerequisites, and no mention of alternatives such as papierkram_list_bank_transactions. Retrieval of a single known record is only implied by the phrase 'one ... by id'.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description's one contribution beyond annotations is that the result nests the company's people, which is genuinely useful for planning the call. It says nothing about error behavior for invalid ids or about the depth of the embedded people data.

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 short sentence with zero filler, front-loading the action and resource. Nothing redundant or 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?

Adequate for a one-param read tool with full schema coverage and a readOnly annotation. With no output schema, however, the description only hints at the return shape ("with its people") and leaves the rest of the payload undocumented.

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

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

With one required parameter and 100% schema description coverage, the schema already carries the id semantics including its source (papierkram_list_companies) and accepted integer/string forms. The description adds no format or constraint detail beyond that, 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?

States a specific verb and resource ("Get one contact (company) by id") and adds the scope detail that the related people are included. It is clearly distinguishable from papierkram_list_companies and papierkram_get_person, though it never names those siblings 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: fetch a single company when you already have its id (the schema notes the id comes from papierkram_list_companies). There is no explicit statement of when to prefer this over listing companies or fetching a person instead.

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 as a safe read, so the bar is lower. The description does add one piece of behavioral value — that the response includes line items — but says nothing about behavior for a missing or invalid id, nor about how much of the estimate is returned.

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

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

One short sentence, front-loaded with the verb and resource, with zero filler. Every clause earns its place.

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

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

There is no output schema, so the description must carry return-value information; 'with its line items' covers this only partially. For a simple single-record getter the core is adequate, but error/not-found behavior and output shape remain 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 parameter already documents that the id comes from papierkram_list_estimates. The description adds nothing beyond the schema for this parameter, 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?

States a specific verb (Get) and resource (one estimate), and 'one' plus 'with its line items' distinguishes it from papierkram_list_estimates. It does not name the sibling explicitly, so the differentiation is implied rather than stated.

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

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

There is no guidance on when to use this versus papierkram_list_estimates or papierkram_get_invoice, and no mention of prerequisites. The only usage signal is the natural inference from 'one' and the required id.

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

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

readOnlyHint=true already covers the safety profile, so the description's job is to add context — and it does, by linking the returned template ids to the custom_template_id parameter of invoice creation, which is cross-tool information annotations cannot carry. It doesn't say whether other account fields come back, but for a read-only, zero-argument call that is a small gap.

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

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

One sentence, front-loaded with what is read, followed by the actionable hint about the ids. No filler and nothing repeated from the annotations.

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 parameters and no output schema, the description must convey what comes back; it names the API version and custom invoice templates but leaves it ambiguous whether additional account data is returned. Adequate for a trivial read tool, short of fully specifying the response.

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

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

The tool takes zero parameters, so there is nothing to document; baseline is 4. The description instead documents the output's usable values (custom_template_id), which is the relevant semantic for a no-arg call.

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 concrete verb and resources: reads the API version and the account's custom invoice templates. The parenthetical explains what the template ids are for, which disambiguates it from the entity getters and list tools in the sibling set. It is clear, though the generic tool name 'get_info' means the description has to do more work than a well-named tool would.

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 implies when the result matters (before creating an invoice with a custom template), but the description never states when to call this tool versus alternatives or that it takes no arguments and is safe to call freely. Usage is inferred rather than instructed.

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 genuine value by disclosing that the response embeds related data (line items, billing address, payment term), which the agent could not know otherwise. It says nothing about behavior on a missing or invalid id, so it remains thin beyond that.

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 sentence with no filler; the resource and scope lead, and the returned fields follow. Nothing could be removed without losing information.

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

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

For a one-parameter read tool with no output schema, the description covers the essentials: what is fetched and which related records are included. It lacks only edge-case behavior (not found, permissions), a minor gap at this complexity level.

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 id parameter already carries a description pointing to papierkram_list_invoices as the source. The prose adds no format, type or constraint detail 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?

States a specific verb and resource ('Get one outgoing invoice') and enumerates what comes back (line items, billing address, payment term). The singular 'one outgoing invoice' implicitly contrasts with papierkram_list_invoices, but it never names that sibling to make the distinction explicit.

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: an agent infers this is the single-record fetch to use once it has an id. There is no explicit when-to-use vs papierkram_list_invoices, nor any stated prerequisite such as needing an id first, though the schema hints at it.

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 needs to add only lightly, yet it adds nothing about behavior on a missing id, whether company_id must own the person, or access requirements. The company-scoping implication is the sole extra signal.

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 no filler or repetition. It is efficient, though it borders on under-specified for a tool with two coupled identifiers.

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-param read with full schema coverage and a readOnly annotation and no output schema, this is nearly sufficient. It still leaves the not-found behavior and the company/person relationship 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 both parameters are documented there, including the id provenance. The description adds no format, id-type, or scoping nuance 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 contact person of a company.' The singular 'one' implicitly distinguishes it from papierkram_list_persons, but no sibling is named explicitly, so it stops short of full differentiation.

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 contains no when-to-use or when-not-to-use guidance and names no alternative. The only routing hint ('from papierkram_list_persons') lives in the schema's id description, not in the tool description 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds nothing beyond that, no note on what happens if the id does not exist, whether the id must come from the list endpoint, or what fields come back.

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 no filler. It is terse enough that nothing is wasted, though it leaves little room for the context a caller might want.

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

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

For a one-parameter read tool with readOnlyHint, the essentials are present, but since there is no output schema the description could have sketched the returned project or the not-found behavior. Minimum viable.

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 id parameter already documents its format and provenance ('from papierkram_list_projects'). The description's 'by id' duplicates rather than extends 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 project') and scopes it to a single record by id, which distinguishes it from papierkram_list_projects. It does not explicitly name any sibling, but the singular/plural split is obvious.

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

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

'by id' implies you need a known id and that listing is a separate tool, but there is no explicit when-to-use/when-not or pointer to papierkram_list_projects for discovery.

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 as a safe read, so the bar is lower. The description adds a small piece of return context by noting the vat_rate is included with both a name and a rate example, but says nothing about other returned fields or behavior on a missing id.

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

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

A single front-loaded sentence that identifies the resource first and the notable returned field second; no filler. The parenthetical vat_rate example is slightly padded but earns its place as disambiguation.

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

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

There is no output schema, so the description carries the burden of describing the return value, yet it only mentions vat_rate out of what is presumably a larger product record (name, price, unit). Adequate but incomplete for a get-by-id 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 id parameter already documents itself as 'Proposition id (from papierkram_list_propositions)'. The description adds no further semantics, 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 ('Get') and resource ('one stored product or service'), which is clearly distinguishable from the get_* siblings for invoices, persons, projects, etc. It does not use the API term 'proposition' that the tool name and list_propositions sibling use, so an agent must infer the product/service = proposition mapping.

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 exclusions, and never points to papierkram_list_propositions (only the schema parameter text does). An agent gets no explicit routing rule beyond 'this fetches one item'.

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 nothing beyond that—no note on what happens when the id doesn't exist, no mention of the returned representation, and no context about 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?

A single front-loaded sentence with zero waste. It is economical, though so terse that it borders on under-specification rather than optimal density.

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-param read tool with annotations and no output schema, the description is adequate but thin. It could briefly indicate the shape of a returned task to help the agent plan, which the absent output schema leaves 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 coverage is 100% and the schema itself documents that the id comes from papierkram_list_tasks. The description's 'by id' restates the parameter name without adding 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?

States a specific verb (get) and resource (one task) scoped by id, which implicitly contrasts with the list_tasks sibling. However, it offers no explicit differentiation from the many other get_* siblings and does nothing beyond the bare minimum.

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

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

There is no guidance on when to use this versus papierkram_list_tasks or other retrieval tools. The agent must infer usage purely from the name and the schema's parenthetical reference to list_tasks.

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=true annotation already communicates that this is a safe read, so the description carries a lighter burden. However, the description adds nothing beyond the annotations — no note on error behavior for a missing id, no indication of whether full detail is returned, and no mention that the id must come from the list endpoint (that hint lives only in the schema).

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 short sentence with the verb and resource front-loaded and zero filler. It is efficient but arguably too terse to be maximally useful.

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 read with a fully documented parameter and readOnly annotations, the essentials are covered. The description still lacks any hint about return shape or failure modes, though the absence of an output schema makes that a minor gap.

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

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

Schema description coverage is 100%: the single id parameter documents its type union and where to obtain it ('from papierkram_list_time_entries'). The description adds nothing 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 time entry by id.' This clearly distinguishes it from the sibling papierkram_list_time_entries (plural listing) and from the create/update variants. It stops short of naming siblings explicitly, so a 4 rather than 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?

There is no statement of when to use this tool versus papierkram_list_time_entries or the other get_* tools. 'By id' implies the single-record lookup path, but the agent must infer that from the name and schema alone.

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 no behavioral context beyond restating the operation—no handling for missing users, permissions, or response expectations.

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

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

The description is a single front-loaded sentence with zero filler. It immediately conveys the operation and scope.

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 tool whose annotations already mark it read-only, the description covers what it does and which parameter selects the user. However, it omits any note about return shape or not-found behavior, and there is no output schema to compensate.

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 itself documents the id parameter with its expected source. The description's 'by id' adds no meaning beyond what the schema already provides, so it meets the baseline for high schema coverage.

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

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

The description states a specific verb and resource: 'Get one user by id.' This clearly identifies a single-user lookup, implicitly distinguishing it from the sibling list tool, but it does not name or explicitly contrast with papierkram_list_users.

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 explicit when-to-use guidance and does not mention alternatives such as papierkram_list_users. The only hint comes from the schema parameter description ('from papierkram_list_users'), not the tool description 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 tells the agent this is a safe read. The description adds that the response embeds line items, which is useful context, but says nothing about not-found behavior, permissions, or whether line items are paginated or truncated.

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 no filler; the key scope (one voucher) and the value-add (line items included) come first. It is perhaps terse to the point of under-specification, but nothing is wasted.

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

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

For a one-parameter read tool with full schema coverage and readOnlyHint annotations, the description covers what is fetched and what comes with it. With no output schema, it would help to say a bit more about the returned shape, 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% and the id field already documents its origin (from papierkram_list_vouchers) and accepts either integer or numeric string. The description adds no meaning 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?

States a specific verb and resource ("Get one expense voucher") plus the notable detail that line items are included. It implicitly distinguishes the single-record fetch from papierkram_list_vouchers by the word "one", though it doesn't name any 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?

The schema's id description points to papierkram_list_vouchers as the source of ids, which implies the list-then-get workflow. The description itself gives no when-to-use, when-not-to-use, or 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine context by naming the returned fields (name, IBAN, balance as Papierkram reports it) and flagging pagination, but gives no detail on result ordering, total counts, or what an empty connection list means.

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

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

Two sentences, front-loaded with the verb and resource, then the returned fields, then pagination. Nothing is redundant and no sentence could be dropped without losing information.

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

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

For a simple read-only list tool with full schema coverage and readOnlyHint, the description is close to sufficient, and it usefully lists returned fields in the absence of an output schema. Minor gaps are ordering behavior and the absence of any note about connection status or filters.

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%, with page, page_size, order_by and order_direction all documented including constraints and the paired-use rule. The description contributes only the word 'Paged', which adds no semantics 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 a specific resource ('bank accounts connected to Papierkram'), and enumerates the returned fields (name, IBAN, balance). The resource is distinct enough from the sibling papierkram_list_bank_transactions that an agent can tell them apart, though the description never explicitly contrasts the two.

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 purpose: an agent wanting the list of connected bank accounts will pick this. There is no explicit when-to-use, no exclusion versus papierkram_list_bank_transactions, and no stated prerequisites (e.g. whether a Papierkram connection must exist first).

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 declares the tool as a safe read operation, so the description's main added value is disclosing the returned fields (value, currency, usage text, booking date, counterparty), which is helpful given the absence of an output schema. It still doesn't describe pagination behavior (e.g., next_page token) or sorting defaults, but the core return shape is communicated.

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

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

Three compact sentences with no filler; the core action and returned fields are front-loaded, followed by filtering and paging notes. Every sentence contributes useful information.

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

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

For a read-only paged list tool with fully documented optional parameters and a readOnlyHint annotation, the description is nearly complete: it covers what is returned, that filtering is available, and that results are paged. The main missing piece is explicit routing to sibling tools for single-record retrieval or connection lookup.

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 page, order_by, page_size, order_direction, and bank_connection_id. The description only reiterates the bank-connection filter and paging concept without adding format details, defaults, or constraints 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?

The description uses a specific verb and resource ('List bank transactions') and enumerates the returned fields, making the tool's function unambiguous. It doesn't explicitly differentiate from siblings like get_bank_transaction or list_bank_connections, but the name and content list make the scope clear.

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

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

It implies usage for filtering by bank connection and paging, but offers no explicit guidance on when to choose this over papierkram_get_bank_transaction (single record) or papierkram_list_bank_connections (to find connection IDs). No when-not-to-use conditions 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?

The readOnlyHint annotation already establishes this is a safe read operation. The description adds that results are paged and identifies the data fields returned, but it does not disclose pagination behavior beyond the word 'Paged' or any access constraints.

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

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

Two short sentences with zero filler. The resource and returned data are front-loaded, and the paging note is placed at the end without disrupting clarity.

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 complete parameter documentation and no output schema, the description covers the resource, the returned fields, and the paged nature. It is nearly complete, though it could note whether all companies are returned or whether any implicit filtering applies.

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 four parameters (page, page_size, order_by, order_direction) are fully documented in the schema. The description only mentions 'Paged' and adds no parameter semantics beyond what the schema provides, which is baseline 3.

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 ('List') and resource ('contacts (companies: customers and suppliers)'), and it names the fields included (address, VAT id, contact data). It is clear what the tool returns, but it does not explicitly differentiate itself from the sibling papierkram_list_persons or papierkram_get_company.

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 only usage context is the word 'Paged.' There is no guidance on when to use this list tool versus papierkram_get_company for a single company, or versus papierkram_list_persons for person contacts. No exclusions or alternatives are mentioned.

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 annotations already declare readOnlyHint=true, so safety is covered. The description adds useful context beyond that: it lists the key fields returned (state, dates, totals) and notes that results are paged, though it does not elaborate on pagination limits or response structure.

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?

It is two compact sentences with the core capability front-loaded and no wasted words. The paging note is brief but 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, the description usefully states that results include state, dates, and totals, and that paging exists. It is complete enough for an agent to call the tool, though it could better route the agent away from similar list or get tools.

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 every parameter is already documented in detail. The description summarizes the filterable dimensions but does not add syntax, defaults, or constraints beyond what the schema 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?

The description states a specific verb and resource: listing estimates, with the German term Angebote and included fields. It is clear what the tool does, but it does not explicitly distinguish itself from siblings such as get_estimate or list_propositions.

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

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

It implies usage by naming filter dimensions (company, project, document date range) and noting the result is paged. However, it gives no explicit when-to-use guidance or alternatives such as get_estimate for a single record.

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's added value is the disclosure of result content (state, dates, totals, outstanding_amount) and pagination. It doesn't spell out paging limits or ordering defaults, but the schema covers those, keeping it above the baseline.

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, each carrying distinct information: what is listed and returned, how to filter, and that output is paged. No redundancy or 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 returned fields and flags pagination, and annotations cover the read-only nature. Minor gaps around ordering defaults and total counts, but an agent can invoke it correctly from this plus the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description only restates which filter axes exist (company, project, date range) and suggests pagination, adding little beyond structured data — baseline 3.

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 ('outgoing invoices / Ausgangsrechnungen'), and names the returned fields (state, dates, totals, outstanding_amount). The resource is distinct enough to separate it from sibling list tools such as list_estimates and list_vouchers 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?

It conveys the supported filters (company, project, document date range) and that results are paged, which implies when the tool is useful. However, it never states when to prefer this over papierkram_get_invoice or papierkram_list_estimates, and gives no exclusions.

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

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

readOnlyHint=true already covers the safety profile, so the description only needs to add context. It confirms the tool is a lookup, but says nothing about ordering of results, whether all templates are returned by default, or whether response items include the display name alongside the id. Adequate but thin for an annotation-covered read tool.

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 short sentence, front-loaded with the verb and resource, with the useful detail placed in a parenthetical rather than padded into another sentence. Nothing to trim.

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 full schema coverage and no output schema, the definition gives the agent enough to call it correctly and to know why. The one real gap is the shape of a returned payment term, which the agent would need for a sensible selection.

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 page, page_size, order_by, and order_direction are all fully documented in the schema with defaults and the order_by/order_direction pairing rule. The description adds no parameter meaning at all, which is the correct baseline 3 when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('List the payment term templates') and adds the downstream motivation (ids feed payment_term_id on invoices), so an agent knows exactly what comes back and why it matters. It falls just short of a 5 because there is no sibling list tool to contrast against and it never says what a payment term actually contains (name, due days, discount terms).

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 'ids needed as payment_term_id when creating an invoice' is an implied trigger for calling this before papierkram_create_invoice, but it is never stated as an instruction and no alternative or exclusion is given. The agent must infer that this is the lookup step preceding invoice creation.

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. 'Paged' is the one added behavioral fact, and even that is already spelled out in the schema's page/page_size descriptions, leaving the description with little beyond structured data.

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, the scope constraint front-loaded, and no filler. Nothing could be cut without losing information.

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

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

For a simple read-only list tool with full schema coverage this is close to adequate, but with no output schema the description never says what a person record contains or how the paging envelope is shaped. An agent knows what to call but not what comes back.

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 (page, page_size, order_by, order_direction, company_id) is already documented, including the odd 'Use next_page from the previous reply' hint. The description only echoes the company scoping, adding no format or interaction detail. 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 (contact persons) plus a scope constraint (of one company), which cleanly separates it from papierkram_get_person and papierkram_list_companies. It does not explicitly name an alternative sibling, 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 phrase 'of one company' implies the caller must already have a company in hand, which is the only real usage guidance given. Nothing states when to prefer this over papierkram_get_person for a single contact, and no prerequisites or exclusions are mentioned.

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 structurally. The description adds that results include dates, budget and state, and that the operation is paged, but gives no further behavioral context such as sort defaults or output 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 short sentences, each carrying a distinct fact: what is listed, what fields are included, how to filter, and that results are paged. Nothing is redundant or 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 full schema coverage and no output schema, the description gives an adequate summary of returned fields and pagination. It could better explain when to choose this over get_project, but an agent has enough to invoke 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 the schema already documents all five parameters thoroughly. The description vaguely mentions company filtering and paging but adds no syntax or usage detail beyond what the schema provides, and doesn't mention order_by or order_direction.

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

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

The description states a specific verb and resource ('List projects') and names the included fields ('dates, budget and state'), which is clear enough to distinguish it from create_project and get_project. It stops short of explicitly differentiating from the singular get_project sibling.

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

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

It indicates that the tool supports filtering by company and is paged, implying when to use it for browsing project collections. However, it does not explicitly say when to use this versus papierkram_get_project or other list tools, nor does it state any exclusions.

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 two genuine behavioral facts beyond annotations: results are paged, and the VAT rate is deliberately omitted from this response and only available via papierkram_get_proposition. It does not mention ordering defaults or what happens at the end of the page sequence.

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 entity disambiguation front-loaded where an agent will read it first. The parenthetical about VAT is the one piece of routing information and is attached directly to the field list it qualifies.

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 carries the return-value burden and does so partially by naming the key fields and the notable omission (VAT). With pagination acknowledged and all four parameters documented in the schema, the definition is largely sufficient, missing only details like sort defaults and total-count behavior.

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

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

Schema description coverage is 100%, so page, page_size, order_by and order_direction are all fully documented in the schema, including the requirement that order_by and order_direction be used together. The description adds nothing about parameters beyond 'Paged', 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?

States a specific verb ('List') and resource, and crucially disambiguates the ambiguous tool name by explaining that 'propositions' means stored products/services (Leistungen/Artikel). It also names the fields returned (article number, price, unit), so an agent knows what it gets. It stops short of explicit differentiation from the other list_* siblings, but the resource here is unique among them.

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

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

Usage is implied (browse the stored product catalog) and the description points to papierkram_get_proposition for the VAT rate, which is a light form of routing. There is no statement of when this tool should not be used, no mention of prerequisites, and no guidance on when paging through the full catalog matters versus a targeted lookup.

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

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

readOnlyHint=true already covers the safety profile, so the bar is lower; the description adds that results are paged, which is meaningful operational context. It does not disclose default page size, sort order, or the maximum page window, which matter for paging behavior. Useful but thin given how much the schema already carries.

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 fragments with zero filler and the core purpose front-loaded. It is arguably over-compressed: the fragments are efficient but the terseness is part of why usage and behavior detail are missing.

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-required-parameter list tool with full schema coverage and a readOnly annotation, this is minimally adequate. An agent still lacks the relationship between tasks and time entries (whether a task carries time entries, what fields identify a task), which is the one gap the structured fields cannot fill.

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

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

Schema description coverage is 100%, so all six parameters are already documented, making the 3 baseline appropriate. The description does add useful gloss ('product/service' for proposition_id), which the schema name alone would obscure, but adds nothing about order_by/order_direction pairing or page defaults beyond what the schema 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 and resource ('List time-tracking tasks') and notes the two filter axes, which is enough to distinguish it from get_task or create_task. It stops short of naming the closest sibling (papierkram_list_time_entries), so an agent must infer the boundary between tasks and time entries.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The filtering sentence implies a retrieval use case, but nothing tells an agent whether to reach for list_time_entries, get_task, or this tool when both tasks and time entries are relevant.

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 needn't repeat safety. It adds "Paged", which is useful behavioral context beyond the annotation, but it doesn't say how filters combine (AND), what the default ordering is, or what the paging envelope looks like beyond the schema's next_page hint.

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

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

Two sentences, front-loaded with the purpose and then the filter axes, with zero filler. The trailing "Paged." is terse to the point of being a fragment, but it is still information-dense and appropriately sized for a list 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?

With no output schema, the description could say more about what an entry contains or how pagination results are returned, and for an 11-parameter tool it doesn't mention sorting or filter combination behavior. It is nonetheless adequate to call the tool correctly, since the schema carries all parameter detail.

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

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

Schema description coverage is 100%, so all 11 parameters — including page, page_size, order_by/order_direction pairing, and the RFC 3339 bounds — are already documented in the schema. The description's filter list largely mirrors that, and it omits the sorting parameters entirely, so it adds little beyond the structured data.

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

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

The description gives a specific verb and resource ("List tracked time entries") plus the filterable dimensions, which clearly separates it from the single-record get_time_entry or the write-side create_time_entry siblings. It stops short of naming any sibling explicitly, so the differentiation is implied rather than stated.

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 enumeration of filters implies when this tool is appropriate (browsing/querying entries by project, user, billing state, etc.), but there is no explicit "use this instead of X" routing and no stated prerequisite such as needing a project_id or user_id first. An agent has to infer that this is the collection-level read versus papierkram_get_time_entry.

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 declares this is a safe read, and the description adds nothing behavioral beyond that — no mention of pagination behavior, result size, or what happens with no users. The id-lookup note is a usage hint, not behavioral disclosure.

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

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

A single short sentence with the core purpose front-loaded and the practical motivation attached; nothing wasted or 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 simple paginated list with no output schema, annotations covering the safety profile, and fully documented params, the description is nearly sufficient. Only the return shape and pagination flow are left implicit.

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 paging and ordering semantics are fully documented in the schema. The description contributes no additional parameter meaning, which makes baseline 3 appropriate.

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

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

States a specific verb and resource ('List the users of the account') and clarifies the downstream value of the returned ids. It does not explicitly differentiate from the sibling papierkram_get_user, 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?

Gives a clear use case: call this when you need user_ids for time entries or tasks. It lacks any exclusion or explicit comparison to papierkram_get_user, which would be required for 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 tells the agent this is a safe read, so the description is not carrying the safety burden. It adds the useful 'Paged.' signal and confirms what each row contains (creditor, state, dates, amounts). It says nothing about default sort order, total counts, or whether an empty result set is possible when filters match nothing.

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, zero filler: what it lists, what the rows contain, how to filter, and that results are paged. The filter information is front-loaded before the pagination note.

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, fully documented 8-parameter list tool with no output schema, the description covers identity, row shape, filterable dimensions and pagination. Only secondary details — default sort, page-size cap, and behavior on no matches — are left to the schema or 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%, covering page, page_size, order_by/order_direction coupling and yyyy-mm-dd date formats, so the schema is the primary source. The description only restates that creditor, project and document dates are filterable, adding no syntax or edge-case meaning 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?

The description uses a specific verb and resource ('List expense vouchers') and disambiguates the term with parenthetical synonyms ('Belege / incoming invoices and receipts'), which the sibling papierkram_list_invoices does not share. It also enumerates the returned attributes (creditor, state, dates, amounts). It stops short of naming papierkram_list_invoices or papierkram_get_voucher as the contrast cases.

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 when the tool applies by listing the available filters ('Filter by creditor (supplier company), project or document date range') and noting 'Paged.'. It gives no explicit when-not guidance and never points to papierkram_get_voucher for a single record or papierkram_list_invoices for outgoing invoices, so the agent must infer the boundary.

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, destructiveHint=true, idempotentHint=true and openWorldHint=true. The description's real contribution is the PATCH semantics ('only the fields you pass are changed'), which meaningfully lowers the agent's fear of clobbering untouched fields. It never addresses the destructiveHint flag (e.g., whether empty strings clear values) or error behavior on an invalid id, so it adds context but stays mid-range.

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

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

Two sentences, front-loaded with the 'WRITE:' modality marker, then the semantics, then the prerequisite. Nothing is wasted and the mutating nature is the first thing read.

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 mutation with no output schema, the definition covers modality, partial-update behavior, and read-before-write. Remaining gap is field-clearing behavior and validation failure handling, which matters given destructiveHint=true, but it is otherwise sufficient to call 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% across all 15 parameters, with enums documented for contact_type and delivery_method, so the schema carries the load. The description adds only the partial-update contract, not per-field semantics. 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+resource ('change fields of an existing contact') and adds the crucial detail that it is a partial update ('only the fields you pass are changed'). 'Existing' implicitly separates it from papierkram_create_company, though no sibling is named explicitly for that contrast.

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 prerequisite: read the record first with papierkram_get_company, which tells the agent the correct call sequence. It does not state exclusions (e.g., use create_company for new records), so 4 rather than 5.

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