bexio MCP by usefulapi

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

With annotations already declaring readOnlyHint=false, destructiveHint=true and openWorldHint=true, the description usefully clarifies that no existing record is modified and states default ownership behavior. However, it says nothing about duplicate-contact handling or side effects that would justify destructiveHint=true, and with no output schema it does not say what is returned (the created contact and its 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?

Three short sentences, front-loaded with the WRITE marker and the resource, with the non-obvious name mapping second and the defaults last. No filler and nothing important 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 18-parameter mutation with no output schema, the description covers the action and two subtle field mappings but omits the return value and any failure/precondition notes. An agent can call it, yet still does not know what comes back or how to handle an existing duplicate.

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 already documents name as company name/last name, first_name as first name/name addition, and the owner_id/user_id defaults. The description's person-name mapping and default ownership restate the schema rather than adding new semantics, 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?

"WRITE: create a new contact (company or person) in bexio" gives a specific verb, resource and scope in the first few words. It is trivially distinguishable from the read siblings (bexio_get_contact, bexio_list_contacts) and from the other create siblings by naming the resource.

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

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

The "WRITE:" prefix and "Nothing existing is changed" make the mutation-vs-read distinction explicit, which is the main routing decision among these siblings. It stops short of exclusions or advice on when NOT to use it (e.g. checking for an existing contact first), so it does not reach the top band.

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 a non-idempotent, open-world mutation; the description adds the important nuance that the record stays a draft and is never issued, sent or booked, which is exactly the side-effect context an agent needs before writing. It does not, however, say what is returned (no output schema) or how contact/tax validation failures surface.

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 mutation marker, then scope, then the safety caveat, then the tax prerequisite. Nothing redundant 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 18-parameter write tool with full schema coverage, the description covers the risk profile, lifecycle and the one cross-tool prerequisite. The remaining gap is the return value — no output schema exists, so saying what a successful call yields (draft id/number) would complete it.

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 field including nested position properties is already documented. The description's only added parameter information is the restatement that taxes must be active sales taxes, which the tax_id description already says. 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 and resource ('create a DRAFT invoice in bexio for a contact') plus the supported line types, which cleanly separates it from the read-only get_/list_ siblings. The 'WRITE:' prefix makes the mutation class immediately visible.

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

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

Explains the workflow position — the user reviews and issues the invoice in bexio afterwards — and names the prerequisite source of valid tax ids (bexio_list_taxes with types sales_tax, scope active). No explicit 'do not use this when…' against a competing create-invoice sibling, but none exists.

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?

"Nothing existing is changed" usefully discloses that this is additive, and "and/or" clarifies that contact_id and project_id may both be supplied. However, it never says what is returned (no output schema exists, so the note ID/response shape is unknown) or whether any permission/scope is needed. Note the mild tension with destructiveHint=true, which the description implicitly softens rather than contradicts outright.

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 operation class ("WRITE:") is front-loaded and the side-effect statement follows immediately. Every clause carries 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 6-parameter mutation with no output schema, the description covers intent and side-effect scope but omits the return value, whether a note can exist with no contact/project attachment, and any permission prerequisites. Enough to call it, not enough to predict the result.

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 subject, info, user_id default, contact_id, project_id, and the event_start time format are all documented in the schema. The description only adds the notion that contact and project can be combined; it says nothing about which attachment is required (only subject is required) or about the user_id/event_start defaults. 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?

Uses a specific verb ("add a note") plus the resource and the target entities (contact and/or project) in bexio, and the examples of note kinds (call log, meeting minutes, follow-up) pin down what a "note" is. No sibling tool creates notes, so the resource alone distinguishes it from the create_contact/create_invoice/create_timesheet siblings.

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 examples imply when the tool fits (logging interactions and meetings), but there is no explicit when-to-use/when-not statement and no named alternative. For an additive write with no competing sibling, implicit guidance is adequate but thin.

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 'WRITE:' prefix and the prerequisite routing are useful, and 'Nothing existing is changed' clarifies the additive write scope. But that sentence directly conflicts with the annotation destructiveHint=true, leaving an agent with contradictory safety signals about a write operation. No mention of what is returned or how duplicate logs are handled.

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

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

Three short clauses, front-loaded with the operation class ('WRITE') and the resource, then the valid input shapes, then the prerequisite. No filler and nothing to cut.

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

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

For an 11-parameter create tool with no output schema, it covers the operation class, the two input modes and the required dependency. It leaves unaddressed whether billable entries need contact/project, but the schema's per-field descriptions and defaults carry that load adequately.

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

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

Schema coverage is 100%, so the baseline is 3; every parameter is already documented inline. The description does add real value by stating that date+duration and start+end are mutually exclusive input modes, a relationship the schema only hints at with '(with start)' / '(with duration)'.

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 ('log time in bexio'), with the resource made explicit by the tool name and the timesheet domain. It implicitly separates itself from the mutating siblings by noting 'Nothing existing is changed', though it never names bexio_list_timesheets or an update tool as the alternative.

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

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

Gives the two valid input shapes ('either date + duration (HH:MM), or start + end') and the hard prerequisite ('Needs a business activity (bexio_list_business_activities)'), naming the exact tool to call first. It stops short of stating when not to use this tool (e.g. when logging against an existing 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the genuinely useful cardinality fact (one profile per account), which tells the agent there is no paging or list handling. It does not describe the response shape or what happens when profile data is incomplete, and there is no output schema to cover that 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?

Two sentences, zero waste. The resource and its field contents come first, and the cardinality constraint is a tight follow-up. Every clause earns its place.

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

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

For a read-only, parameterless getter with annotations covering safety and no output schema, the description's field enumeration effectively serves as a lightweight return-value spec. What is missing is minor: error behavior when the profile is unset, and any permission requirement.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed by stating the profile is singular and account-scoped; nothing about parameters is misrepresented.

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

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

The description names the exact resource (the bexio company profile) and enumerates its contents: name, address, legal form, VAT/MWST, UID, contact details. That is far more specific than the bare title. It stops short of a verb-led statement and never contrasts itself with the potentially confusable bexio_get_current_user or bexio_list_users siblings.

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?

"Each bexio account has one profile" implies this is a fixed, parameterless lookup with no filtering or selection step, which is a useful usage cue. However, there is no explicit statement of when to reach for this versus bexio_get_current_user or bexio_list_users, and no exclusions or prerequisites.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds return-content context by enumerating the included fields, which is valuable given there is no output schema, but it says nothing about error behavior or what happens for missing/archived contacts.

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 efficient sentence-fragment with zero padding, front-loading the resource and its payload. It loses a point only for being a fragment rather than a complete, scannable statement of purpose.

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-item read with annotations covering safety and a fully documented two-parameter schema, the description adequately fills the one gap – return contents – since no output schema exists. Slightly more (e.g., behavior for archived contacts) would make it complete.

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

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

Schema description coverage is 100% and the schema already explains contact_id ('from bexio_list_contacts') and archived. The description adds no parameter-level detail, so the baseline 3 for fully documented schemas 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 names the resource ('One contact') and enumerates the returned fields (address, emails, phones, language, groups, remarks), so the intent is inferrable. However, it is a noun phrase fragment with no explicit verb and does not explicitly contrast with bexio_list_contacts, leaving the single-vs-many distinction implicit.

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

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

There is no guidance on when to use this tool versus bexio_list_contacts or other get tools, and no prerequisites or exclusions are stated. The agent must infer usage entirely from the name and the plural sibling.

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 and openWorldHint=true, so the safety profile needs no restating. The description adds one genuinely non-obvious fact — that the returned id is the default user_id for new records — but says nothing about failure modes, auth requirements, or what happens if the session has no user.

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

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

Two compact sentences with zero filler: the first establishes what is returned, the second immediately delivers the operational implication of the id. 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?

With no parameters and no output schema, the description carries the burden of describing the response, and it does so by listing the fields. The main residual gap is that it doesn't state that the call is a single-object read rather than a list, though 'the signed-in user' makes that clear enough in practice.

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 no parameters, so the baseline is 4. The description's field list (id, name, email, flags) is return-value information rather than parameter guidance, which is the right thing to spend words on for a zero-arg tool.

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

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

The description names a specific resource and scope — the signed-in user — and enumerates the returned attributes (id, name, email, superadmin/accountant flags), which implicitly separates it from bexio_list_users. It stops short of naming the sibling explicitly, so the differentiation is inferable 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?

Usage is implied by 'Its id is the default user_id of new records' — an agent can infer this is the tool to call before creating records that need an owner. There is no explicit when-to-use/when-not framing and no reference to the bexio_list_users alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuine value by disclosing the shape of the response (line items, taxes, totals, payments, remaining amount), but says nothing about behavior on an invalid or unknown invoice_id, or about data freshness.

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, and the payload contents are readable at a glance. It is a noun fragment rather than a complete statement of the operation, which slightly reduces clarity for a first-time reader.

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 get-by-id read tool with annotations and full schema coverage, the description supplies the one thing the structured fields do not: what the returned invoice object includes. Missing only edge-case behavior, which is minor at this complexity.

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

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

With a single parameter and 100% schema coverage — including a description that already says the id comes from bexio_list_invoices — the schema does the work. The description adds no meaning about the id beyond what is already structured, 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 description identifies a single invoice and enumerates exactly what the payload contains (positions, taxes, totals, payments, remaining amount), which lets an agent distinguish it from the list-style siblings. It falls short of a full verb+resource statement and never explicitly contrasts itself with bexio_list_invoices or bexio_get_quote, relying on the name/title for the verb.

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: 'One invoice' signals single-record retrieval versus the listing tools, and the schema's reference to bexio_list_invoices hints at the discovery-then-fetch flow. There is no explicit when-to-use/when-not or named alternative in the 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 the operation read-only and open-world, so the safety profile is covered. The description adds useful behavioral context by stating that the response includes positions, taxes, and totals, but it does not describe error behavior 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?

The description is a single, front-loaded sentence that directly states what the tool returns. It contains no boilerplate or repetition and is appropriately short for a simple one-parameter getter.

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 one-parameter read tool, the description covers the key return composition—positions, taxes, and totals—while annotations cover safety and the schema fully documents the input. It is adequate, though without an output schema it could say slightly more about the returned order structure.

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 is documented as the order id taken from bexio_list_orders. The description adds no additional parameter semantics beyond what the schema already provides, which is the baseline case for full 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 identifies the specific resource and scope: one sales order including its positions, taxes, and totals. It is clear what the tool retrieves, though it does not explicitly name the sibling bexio_list_orders as the alternative for multiple orders.

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 guidance on when to use this tool versus bexio_list_orders or other get tools. The schema mentions that the order id comes from bexio_list_orders, but the description itself gives no usage context or 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing what the payload contains (contact, state, type, dates, invoicing, budget settings), but says nothing about permission/scope requirements or how a missing or inaccessible project is handled.

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

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

A single compact sentence with no filler, and the key fact (one project, and which facets) is front-loaded. It is arguably under-specified rather than padded, but it does not waste words.

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-parameter read with annotations covering safety and no output schema, the description does moderately well by naming the returned facets. However, with no output schema it should say more about the return shape (format of dates, whether contact/invoicing/budget are nested objects or ids) and about error conditions.

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 project_id parameter is documented in-schema, including its provenance (from bexio_list_projects). The description adds no further semantics such as id scope/validity expectations, 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?

"One project with its contact, state, type, dates, invoicing and budget settings" clearly identifies the resource (a single project) and enumerates the returned facets, which implicitly distinguishes it from the sibling bexio_list_projects. It is a noun fragment rather than an explicit verb+resource statement, so it leans on the name/title for the 'get' action.

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 bexio_list_projects, no prerequisites (e.g. needing an id obtained from the list call, which is only mentioned in the schema), and no note on not-found behavior. The agent must infer all routing from the name 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful context about what is returned (positions, taxes, totals), but says nothing about not-found behavior or error handling for an invalid 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 tight sentence with zero waste. It is terse to the point of dropping the verb, but nothing is padded or redundant.

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

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

For a read-only single-record fetch with a fully described parameter and no output schema, the description outlines returned content adequately. It still leaves the agent without usage guidance or error-behavior context.

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 a single well-documented required parameter, so the schema does the heavy lifting. The description adds nothing beyond it, which is the baseline for a fully-covered schema.

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

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

States the specific resource and scope: a single quote including its positions, taxes and totals. An agent can distinguish it from bexio_list_quotes by the singular 'One quote' and the enumerated detail, though the description never names the sibling explicitly and omits a verb.

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 pointer to alternatives. The only routing hint lives in the schema ('from bexio_list_quotes'), not in the description text.

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 and openWorldHint=true, so the safety profile is covered. The description adds real interpretive value by decoding the type codes (1 earning, 2 expenditure, etc.), which is exactly the kind of context annotations cannot carry. It says nothing about pagination, result ordering, or total counts, though the schema partly covers paging.

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 a single compact sentence with no filler, but it is structured as a colon-delimited field glossary rather than being front-loaded with what the tool does. The reader learns the payload shape before learning the operation.

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, enumerating the returned fields is genuinely useful and partly compensates. However, a listing tool with zero required params still needs the action stated and some hint about scope or ordering; those gaps keep it at 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 description coverage is 100% — limit and offset are both fully documented including the next_offset hint — so the schema does all the work. The description adds nothing about parameters, which is the expected baseline when coverage is complete.

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 enumerates the resource's fields ('account number, name, type, default tax, active/locked flags') which makes clear this is the chart-of-accounts resource, but it never states the action — no verb like 'list' or 'retrieve'. Sibling bexio_list_bank_accounts is not contrasted, so an agent must infer the difference between chart-of-accounts and bank accounts from the noun alone.

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 alternatives, no mention of the closely-named bexio_list_bank_accounts, and no note about filtering or scoping. The agent is left to infer that this is an unfiltered enumeration of the chart of accounts.

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 and openWorldHint=true, so the safety profile is covered. The description adds value by naming the shape of the returned records (code, name, sale/purchase price, tax, unit, stock levels), which matters since there is no output schema, but it says nothing about result caps, paging behavior, currency/price formatting, or which fields may be null.

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

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

Two tight sentences, front-loaded with the verb and resource before the field list. The final clause about article_id is compact and useful as a cross-reference, though it reads as a fragment and could be stated more clearly.

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

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

With no output schema, the description does the necessary work of naming the returned fields, and the fully documented schema handles all six parameters. For a simple read-only list tool this is close to sufficient; only paging/limits context and explicit sibling disambiguation are absent.

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

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

Schema description coverage is 100%, with each of the six parameters documented in the schema (including next_offset guidance and the order_by enum), so the baseline is 3. The description only alludes to code/name as search keys and adds no syntax, casing, or partial-match nuance beyond what the schema already says.

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 or search items / products (Artikel)") and enumerates the fields the resource carries, plus the German domain term so an agent can match user vocabulary. The resource name alone distinguishes it from the other bexio_list_* siblings (invoices, contacts, taxes, etc.), though it never explicitly says which sibling to prefer.

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?

"List or search" plus the code/name filter semantics implies you pass filters to narrow results, and the trailing sentence says what to do with a returned id (use as article_id in a draft invoice). There is no explicit when-to-use vs. when-not, and no prerequisite or exclusion 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 and openWorldHint=true, so the safety profile is covered. The description adds useful context about what the payload contains (name, bank, IBAN/QR-IBAN, currency, linked ledger account, QR-invoice mode), but says nothing about ordering, completeness, or empty-state behavior.

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

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

A single compact fragment with zero filler, and the resource is front-loaded. It is efficient, though as a bare noun phrase it reads more like a caption than a tool description.

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, enumerating the returned fields is genuinely valuable and largely closes that gap for a simple read-only list tool. Pagination details are already in the schema, so nothing essential is missing.

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

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

Schema description coverage is 100% and both limit/offset are fully documented, so the schema does the heavy lifting. The description adds no pagination or filtering semantics of its own; 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 resource (bank accounts in bexio banking) and enumerates the fields returned, which implicitly separates it from the sibling bexio_list_accounts (ledger accounts). It stops short of a clear verb and never explicitly contrasts with that closely-named sibling, leaving the distinction to inference.

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 call this versus bexio_list_accounts or bexio_list_journal, nor any prerequisites or exclusions. The only hint is 'shown in bexio banking', which an agent must interpret to distinguish bank accounts from ledger accounts.

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 and openWorldHint=true, so the safety profile is covered. The description adds the returned field set (document number, vendor, gross/net, pending amount, overdue flag), which is meaningful given there is no output schema, but it says nothing about pagination ceilings, result volume, or account/permission scope.

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

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

Two dense sentences with the resource and its identity front-loaded, then the status vocabulary. The field enumeration is a list dump rather than prose, but every item is informative and there is no filler.

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

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

With 12 optional parameters and no output schema, the description usefully covers return contents and the status enum, but leaves the agent without sibling differentiation against bexio_list_invoices/orders and without any note on default paging behavior. Adequate, not complete, for a tool of this breadth.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely upgrades one parameter: it defines the ambiguous enum value TODO as 'booked, not fully paid' and gives DRAFTS/PAID/OVERDUE meaning that the schema's bare 'Bill status filter' string does not. It adds no comparable semantics for the date-range, vendor, or supplier_id filters.

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

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

The description names the resource precisely and disambiguates it from customer invoices via 'Supplier bills (Kreditoren / purchase bills)', then enumerates the fields returned. It never states an explicit verb ('list'), relying on the title/name, and it does not explicitly contrast itself with the sibling bexio_list_invoices.

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 when-to-use guidance, no exclusion, and no named alternative. An agent must infer from the resource name alone that this is the purchase-side counterpart to bexio_list_invoices rather than reading any routing instruction.

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 and openWorldHint=true, so the safety profile is covered. The description adds value by listing the key returned fields, but it does not mention pagination behavior, rate limits, or authentication requirements. With annotations present, this is an adequate but not rich 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?

The description is two short sentences with no wasted words, and it front-loads the resource and field list. 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 simple read-only list tool with no output schema, the description provides enough context: it tells the agent what the resource is, which fields matter, and why one would need it. The main gap is explicit routing relative to siblings, but the timesheet tie-in covers the primary use case.

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 fully documents limit, offset, order_by, and descending. The description adds no parameter-specific meaning beyond what the schema provides, making 3 the correct baseline.

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

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

The description names the resource (business activities / Tätigkeiten) and its context (time tracking), and enumerates the returned fields (id, name, billable default, hourly rate). It also ties the resource to timesheets, which implicitly separates it from list_timesheets, but does not explicitly name or contrast a sibling.

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

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

The phrase 'A timesheet needs one' implies that this list is used to obtain a business activity ID before creating a timesheet. However, there is no explicit when-to-use statement, no mention of alternatives, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the domain detail that status can be open, locked, or closed, which hints at whether a year is usable for posting, but it says nothing about ordering, pagination behavior, or whether locked years affect downstream writes.

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

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

A single compact sentence fragment that front-loads the resource and then the relevant fields. There is no waste, though the fragmentary style (colon list) sacrifices a little readability for brevity.

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

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

For a simple, read-only list tool with no output schema, the description usefully names the returned fields and the status vocabulary, which is the main thing an agent needs. Pagination and return shape are handled by the schema and annotations, so remaining gaps are minor.

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

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

Schema description coverage is 100% with only two optional pagination parameters, both fully documented in the schema including the next_offset hint. The description adds no extra parameter meaning, so the baseline of 3 applies.

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

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

The name plus description together clearly state the resource (accounting/fiscal business years) and the fields involved (start, end, status), so an agent knows what a call returns. It does not explicitly say 'list all' nor name a sibling it must be distinguished from, but the resource is narrow enough to be unambiguous against siblings like bexio_list_business_activities.

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, when not to, or which alternative to prefer. The agent must infer that it fetches fiscal periods rather than, say, filter them by other tools.

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

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

With readOnlyHint and openWorldHint already provided by annotations, the description adds meaningful filter semantics: unfiltered listing pages through all contacts while filtered listing uses a search where all filters must match. It does not discuss rate limits or detailed response shape, but it adds useful behavior beyond the annotations.

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

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

Two dense sentences with no wasted words; the list/search scope and filter behavior are front-loaded, and the name_1/name_2 clarification follows naturally.

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 13-parameter optional-filter list tool with no output schema, the description covers the most important behavioral split between unfiltered paging and filtered search. It leaves some details to the schema, such as archived default behavior and offset usage, which is reasonable given full schema coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by explaining the two name fields in business terms and by stating that filters are ANDed together. That AND behavior is not evident from the individual parameter descriptions alone.

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 clear verb and resource: it lists or searches contacts, and it names the entity subtypes (customers, suppliers, persons, companies). It implicitly distinguishes itself from bexio_get_contact by being a list/search operation, but it does not explicitly route single-record lookups to the sibling tool.

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

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

It gives concrete usage behavior: no filters means paging through contacts, filters invoke bexio's contact search with all filters required to match. It does not explicitly name alternatives such as bexio_get_contact, but the list-vs-get distinction is implied clearly enough.

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 and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the shape of each record (id, code, rounding) and that exchange rates are conditional on a validity date, but says nothing about pagination behavior, total counts, or error/empty cases.

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

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

Two short sentences, front-loaded with what the tool returns and followed by the one actionable hint about currency_id. No padding or redundant restatement of the title.

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

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

There is no output schema, so the description usefully names the fields the agent will receive, and all four parameters are documented in the schema. For a simple read-only list endpoint this is close to complete; only pagination/result-set guidance is absent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes slightly beyond it by tying the exchange rate to a date ('valid on a date'), clarifying the relationship between the date and with_exchange_rate parameters rather than treating them independently.

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

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

The description names the specific resource (currencies set up in bexio) and enumerates the returned fields (id, code such as CHF/EUR, rounding), which distinguishes it from sibling list tools like bexio_list_accounts or bexio_list_taxes. It is a noun phrase rather than an explicit verb, but combined with the title 'List currencies' the intent 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?

'Use an id as currency_id' gives useful cross-tool guidance on what to do with the returned id, and the optional exchange rate implies when to pass date/with_exchange_rate. However, there is no explicit statement of when to call this versus alternatives, and no mention of prerequisites or any case where you should not call 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description contributes the useful detail that results are per-payment records with date, amount, bank account and cash discount, but says nothing about ordering, volume, or pagination behavior.

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

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

A single compact sentence with zero waste, and the invoice scoping is front-loaded. It reads as a fragment rather than a full sentence, but nothing is padded.

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

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

No output schema exists, and the description compensates by enumerating the payment fields returned. For a simple paginated list this is largely sufficient; only ordering and result-size expectations are unstated.

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

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

Schema description coverage is 100%, so limit/offset/invoice_id semantics (including next_offset usage) are already fully documented. The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.

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

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

Names a specific resource (payments recorded on one invoice) plus the fields returned (date, amount, bank account, cash discount), which cleanly separates it from bexio_list_invoices and bexio_get_invoice. It lacks an explicit verb, but the scope 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?

No statement of when to use this versus alternatives such as bexio_get_invoice (which may also expose payment info) or bexio_list_invoices. The only chaining hint (invoice_id comes from bexio_list_invoices) lives in the schema, not the description.

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

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

With readOnlyHint/openWorldHint already declaring safety, the description adds real value: full-scan paging behavior without filters, strict AND matching when filters are present, and the business meaning behind each status value (pending = issued/open, partial = partially paid, unpaid = overdue reminder state). It omits return shape and page-size limits, but those live 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?

Two sentences, front-loaded with the core verb+resource and field list, followed by filter and status semantics. Every clause carries information an agent would otherwise have to guess.

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

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

For a 12-parameter, zero-required list tool with no output schema, the description compensates well by naming the returned fields and describing pagination and filter combination rules. What remains thin is the return envelope (e.g. what next_offset/total fields come back), though offset's schema text partly covers that.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns above that by expanding the status enum into business semantics and clarifying that multiple filters combine conjunctively rather than loosely. It adds no detail on ordering, date-range fields, or offset/limit, which the schema already covers.

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/search) and resource (sales invoices) and enumerates the fields returned (number, contact, totals, open amount, dates, status), which makes it distinguishable from bexio_get_invoice and from list_orders/list_quotes. It never explicitly contrasts with those siblings, 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 description explains filter behavior (no filters = page through everything, filters = AND semantics), which implies when the tool is appropriate for browsing vs. targeted lookup. It gives no explicit routing guidance such as 'use bexio_get_invoice for a single invoice' or 'use bexio_list_invoice_payments to see payments', so the agent must infer alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. With no output schema, the field enumeration does add value by telling the agent what a booking contains (including base-currency amount and ref_class/ref_id). It says nothing about ordering, volume, or how pagination behaves, so it is not richer than a 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?

A single compact sentence that front-loads the domain concept and wastes no words. It reads as a fragment rather than a complete statement, but nothing is padded or redundant.

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

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

Parameters are fully documented in the schema, and the description partially compensates for the missing output schema by naming the returned fields. However, for a paginated, filterable accounting-listing tool it omits any usage framing, ordering, or relationship to sibling listing tools, leaving real gaps.

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

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

Schema description coverage is 100%, with from/to, limit, offset, and account_uuid all documented in-schema, so the baseline of 3 applies. The description mentions 'date' and 'account ids' only as returned fields, not as filter inputs, and gives no additional semantics beyond the schema.

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

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

The description is a noun-phrase inventory of journal-booking fields ("Accounting journal bookings: date, debit and credit account ids, ...") rather than a statement that the tool lists journal entries; the verb comes only from the title. It does hint at the resource being accounting ledger bookings, which is distinguishable from bexio_list_bills or bexio_list_invoice_payments, but it never explicitly draws that line.

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, no prerequisites, and no pointer to alternatives such as bexio_list_accounts or bexio_list_invoice_payments, which an agent could easily confuse with a journal view. The only guidance lives in the schema's parameter descriptions, not the tool description.

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 and openWorldHint=true, so safety and external-scope unknowns are covered. The description adds the filter-conjunction behavior and the status vocabulary, but says nothing about pagination/deep paging limits despite limit<=2000 and offset<=10,000,000, nor about result ordering defaults.

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 no filler; the resource and returned field set are front-loaded and the filter semantics arrive second. Nothing in it is padding.

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

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

With 12 parameters, no output schema and no required fields, the description usefully enumerates what a result contains, which compensates for the absent return schema. Pagination behavior and sort defaults are left entirely to the schema, a small gap but not a blocking one.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description earns one step by adding the cross-parameter semantics ('all must match') that the schema does not state anywhere. It also restates the status enum values, which is redundant with the schema but harmless.

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+resource ('List or search sales orders (Aufträge)') and enumerates the fields returned (number, contact, totals, recurring flag, status), which separates it from the write and single-record siblings. It never explicitly contrasts itself with bexio_get_order or bexio_list_invoices/quotes, so an agent must infer that distinction from the resource name.

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 'With filters all must match' gives an implicit usage rule (AND semantics for combined filters), which is actionable. There is no statement of when to prefer this over bexio_get_order for a single order, or over the sibling list tools for invoices/quotes, so guidance remains inferred rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the genuinely useful conjunctive-filter rule, but says nothing about pagination defaults, ordering behavior, or maximum result sets — all of which matter for a listing 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 compact sentence, front-loaded with the core verb and resource. It loses a point because the field list includes attributes that don't correspond to any filter parameter, which is filler that can mislead.

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?

Read-only annotations and a fully documented 7-parameter schema carry most of the burden, and no output schema is declared. The description is adequate but silent on default result behavior (e.g. unfiltered listing capped by limit) that an agent would want before calling.

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 seven parameters are already self-documenting; baseline 3 applies. The one added value is the AND-combination rule, though the description also names 'type, dates, budget' which are not filter parameters in the schema, creating mild ambiguity about what can actually be filtered.

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 or search') and resource ('projects'), and enumerates the queryable attributes. It is clearly distinguishable from bexio_get_project (single-record fetch) by the 'List or search' phrasing, though it never names that sibling explicitly as the alternative.

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

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

'With filters all must match' gives a hint about how to combine criteria, but there is no explicit guidance on when to use this versus bexio_get_project, nor on what happens when no filters are supplied. Usage is implied rather than stated.

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

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

readOnlyHint=true and openWorldHint=true already declare the safety profile, so the description's added burden is modest. It contributes the filter-combination rule and the set of returned fields, but says nothing about pagination behavior (limit/offset interplay) or result ordering beyond what the schema states.

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

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

Two compact sentences, front-loaded with the verb and resource. Minor waste in re-listing the status enum values that already appear in the schema.

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

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

For a 12-parameter read-only list tool with full schema coverage and no output schema, the description covers what is returned (number, contact, totals, validity, status) and how filters combine. Only pagination expectations are left implicit, which the schema's next_offset note partially handles.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented in the schema; baseline 3 applies. The only semantic added beyond the schema is that filters combine with AND, which is genuinely useful but small.

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

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

States a specific verb+resource ('List or search quotes (Offerten)') and enumerates the returned facets (number, contact, totals, validity, status). It is clearly distinct from bexio_get_quote and the other list_* tools, though it doesn't explicitly name alternatives.

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?

'With filters all must match' gives useful AND-semantics guidance for combining filters, but there is no explicit when-to-use/when-not guidance or routing to bexio_get_quote for single-record retrieval. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds domain semantics about tax codes and validity, but says nothing about pagination behavior or rate limits beyond what the schema already provides.

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 with no wasted words, and the practical filter advice is front-loaded after the resource identification. The first sentence is a telegraphic fragment, which is efficient but slightly less readable.

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 a fully documented schema and read-only annotations, the description covers the resource, returned fields, and a key usage scenario. Missing pagination notes are covered by the schema's offset and limit descriptions.

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 five parameters are already documented in the schema. The description reinforces the types and scope filters with a concrete use case, but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

The description identifies the resource precisely as VAT (MWST) tax codes and enumerates the returned fields (id, code, rate, type, validity). It does not explicitly contrast with sibling list tools, but the resource is unmistakable.

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

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

It gives an explicit usage rule: for a draft invoice, use an active sales tax (types sales_tax, scope active). That is clear context for a common scenario, though it does not state when not to use the tool or name alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the genuinely useful AND-semantics of filter combination, but says nothing about pagination behavior, default result size, or ordering — all of which live 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?

Two compact sentences with the operation stated first and the filter-combination rule second; nothing is padded. The field list is the only part that could be trimmed or reframed as outputs rather than filters.

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 this is adequate, and the field list gives a hint of the response shape in the absence of an output schema. It still omits pagination expectations and the no-filter default behavior, which an agent calling with zero arguments would want to know.

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 are already documented, making the baseline 3. The description mentions user, contact, project, and business activity (matching real filters) but also lists date, duration, text, and billable flag, which are output fields with no corresponding filter parameter — a mild risk of an agent expecting date filtering that does not exist.

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

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

States a specific verb (list or search) and resource (time tracking entries), clearly distinguishing it from the write-side sibling bexio_create_timesheet. The trailing field enumeration mixes returned fields with filterable ones, slightly blurring what the tool actually does, but the core purpose 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?

The phrase 'List or search' implies retrieval usage and 'With filters all must match' signals AND-combination of filters, but there is no explicit guidance on when to use this versus other list tools or on what happens with no filters at all. There is no dedicated alternative timesheet-query sibling, so the routing burden is low, but the guidance remains implicit.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true). The description adds useful context that the returned ids serve as foreign keys elsewhere, but says nothing about pagination behavior, return size, or permissions beyond what the schema already declares.

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

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

Two short sentences, front-loaded with what is returned before the usage note. No filler, though the phrasing 'Use an id as user_id or owner of...' is slightly terse and grammatically compressed.

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-only list tool with full schema coverage and annotations, the essentials are present. The remaining gap is routing guidance against bexio_get_current_user and any note on what the list covers (active vs. all users).

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 both params (limit, offset) are fully documented in the schema, including the next_offset hint. The description adds no parameter detail, 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 (company's bexio users) and names the returned fields (id, name, email). It distinguishes itself from bexio_get_current_user by scope ('the company's' users vs. current user), though that distinction requires inference from the sibling name.

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 second sentence gives a downstream purpose for the returned ids ('Use an id as user_id or owner of contacts, documents and timesheets'), which implies when to fetch them. But it never explicitly says when to use this versus bexio_get_current_user, and there are no exclusions.

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