ABRA Flexi MCP by usefulapi

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is partly covered; the description adds the meaningful nuance that it 'only adds a record; nothing is sent,' clarifying there are no downstream side effects. It stops short of saying what happens on validation failure (does it throw, or return errors in the dry_run response), which keeps it off a 5.

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

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

Three short sentences, front-loaded with the mutation warning and followed by the two most important pre-call habits. No filler, no restatement of 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 14-parameter create tool with no output schema, the description covers what is created, that nothing is sent downstream, and how to preview safely. The remaining gap is what a successful call returns (the new record id/code), which matters for chaining into update_contact or get_contact.

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 14 parameters including dry_run are already documented with types, patterns and lengths. The description's only parameter-related content is the dry_run guidance, which restates the schema's own wording, 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 verb+resource pair ('create a new address-book entry (customer or supplier)') and names the system, ABRA Flexi. It is trivially distinguishable from the sibling read tools (list_contacts, get_contact) and from abraflexi_update_contact.

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

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

It gives two concrete preconditions: run dry_run first to preview, and check abraflexi_list_contacts first to avoid duplicates. That names the alternative tool and the condition that selects it, so nothing is left to inference.

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

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

Annotations only declare write/non-destructive, and the description adds the material side effects: assignment of the next number in the series and possible automatic accounting by ABRA Flexi based on the invoice type. It also discloses the dry_run validation-only path, which is exactly the context an agent needs before a mutation.

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 tightly packed sentences, front-loaded with the WRITE marker and the resource, then side effects, then the dry_run recommendation, then prerequisite lookups. 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?

No output schema exists, and the description partially compensates by explaining that dry_run returns computed totals and validation errors. It could say a bit more about what a successful save returns (e.g. the created document code), but for a 10-parameter creation tool this is close to complete.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by naming the evidence (typ-faktury-vydane) for document_type_code and pointing to the contact lookup for customer_code, and by promoting dry_run as the recommended first call. It does not elaborate on item-level fields, but the schema already documents those fully.

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 and resource plus the Czech evidence name (faktura-vydana) and states the line-item dimension. It is clearly distinguishable from read-side siblings like abraflexi_list_issued_invoices and abraflexi_get_issued_invoice.

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

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

Explicitly recommends dry_run first, states what the tool does NOT do (send, mark paid, e-mail), and routes the agent to abraflexi_list_records and abraflexi_list_contacts to obtain the required codes. Both when-to-use and how-to-resolve-prerequisites are covered.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real context beyond that — that the result is scoped to the login's credentials and what fields come back — but says nothing about failure behavior when credentials are invalid, which is the core risk for a connection-check 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?

Two short sentences, zero waste; the resource and return fields come first and the use case follows. Nothing is padded or restated from 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?

With no output schema and no parameters, the description usefully compensates by naming the three returned fields. Behavioral edge cases (invalid login, empty state) remain undocumented, which keeps it just short of 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is required and instead spends its words on output content.

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 ('Show the ABRA Flexi company the login points to') and enumerates the returned fields (name, company id, state). No sibling returns company data, so it is naturally distinguishable, though the description never says so 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?

'Use it to check the connection' gives one concrete scenario, which is genuine usage guidance. It offers no when-not-to-use condition or comparison to any alternative, leaving the agent to infer the rest.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The phrase 'with all its fields' adds a little context about return breadth, but nothing is said about behavior on a missing or invalid id (error vs empty result), which is the main unknown for a single-record fetch.

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

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

Two short sentences, front-loaded with the verb and resource, followed by the one invocation detail that matters. No filler.

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

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

For a one-parameter read tool with annotations covering safety and no output schema, this is nearly complete: it says what comes back ('all its fields') and how to form the id. Only the not-found behavior is unaddressed.

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

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

Schema coverage is 100% and the schema already documents both the numeric id and the 'code:ABC' identifier form with a full pattern. The description's only addition is naming abraflexi_list_contacts as the id source, which is marginal against a schema that already carries the syntax.

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 address-book entry') and scopes it to a single record with all fields, which separates it from the plural abraflexi_list_contacts sibling. It does not, however, distinguish itself from abraflexi_get_record or abraflexi_get_company, which are also single-record retrievals.

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

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

The description implies usage by pointing to abraflexi_list_contacts as the source of the id, which is a helpful sequencing hint. It never states when to prefer this over abraflexi_get_record or abraflexi_get_company, so the agent must infer the choice.

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 earns credit for disclosing the return shape – all fields plus line items – which the agent needs to know before deciding to call it, though it says nothing about error behavior for missing ids.

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 filler, with the primary behavior stated first and the invocation hint second. Every sentence 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 a single fully documented parameter, readOnly annotations, and no output schema, the description covers what an agent needs. The only soft gap is no guidance on how non-numeric identifiers other than code: behave, which the schema only gestures at.

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 already enumerates the identifier prefixes and pattern. The description restates 'numeric id' and 'code:<number>' but adds no meaning 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: retrieve one issued invoice, including all fields and line items. The word 'one' implicitly contrasts with the list variants, and '(from the list)' points at the sibling source, so an agent can separate it from list_issued_invoices without opening a schema, though the sibling is never named.

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

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

Provides a partial routing hint by saying the numeric id comes 'from the list', which tells the agent to enumerate first. It does not explicitly name the list tool, state when not to use this one, or contrast it with abraflexi_get_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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely new behavioral context by promising the full field set plus line items in the response. It does not say what happens when the id is unknown (error vs empty) or whether related records are expanded, which keeps it from a 5.

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

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

Two sentences, zero waste, with the resource and payload description front-loaded ahead of the parameter hint. Nothing is repeated from the schema or 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?

For a one-parameter read with no output schema, the description covers resource, payload shape, and id sourcing, which is most of what an agent needs. Missing only failure behavior and a clearer statement of what "all its fields" contains.

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

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

Schema coverage is 100% and the schema already documents the numeric id and the code:ABC form, so the baseline would be 3. The description adds a sourcing hint the schema lacks — that ids come from the list tool — which is real value for an agent picking an id.

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 received invoice") and explicitly scopes the payload ("all its fields and its line items"). The singular "one" cleanly separates it from the sibling abraflexi_list_received_invoices without needing to name it.

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

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

Tells the agent where the id comes from ("from the list"), implicitly routing to abraflexi_list_received_invoices. It gives no explicit when-not guidance or mention of a bulk-fetch alternative, so it stops just short of a full routing statement.

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

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

The readOnlyHint annotation already establishes the safe read-only nature. The description adds useful behavioral context that the default response is detail full and that a fields parameter can return a subset, plus the caveat that field names are Czech vendor property names. It does not describe not-found behavior, but for a simple read tool this is acceptable given the annotation coverage.

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

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

The description is two sentences with no wasted language. The core action and id forms are front-loaded, and the field-name caveat 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 simple single-record read with fully described parameters and a readOnly annotation, the description covers the essentials: what is returned by default, how to identify the record, and the vendor-specific field naming. It does not explain error behavior or exact output structure, but no output schema exists and the description still communicates the default full-detail return.

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 three parameters are already documented in the schema. The description reinforces the id forms and Czech field naming, but does not add syntax or constraints beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: get one record of any business evidence, with full detail, by numeric id or identifier. It clearly separates this from list-style tools by emphasizing retrieval of a single record, but it does not explicitly name the more specific get_* siblings as 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?

Usage is implied by the ability to fetch one record by id, and the evidence parameter points to abraflexi_list_evidences for discovering valid values. However, there is no explicit guidance on when to use this generic getter versus the dedicated get_contact/get_issued_invoice tools or when to use list_records for searching.

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

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

Annotations only declare readOnlyHint=true; the description adds the non-obvious default ordering ('newest first by default') and explains the two key result fields (sumCelkem = amount, typPohybuK = direction), which matters because there is no output schema. Pagination and rate/auth behavior are left unstated.

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 identity of the tool and followed by behavior and field semantics. No filler or repetition of schema detail.

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, the description covers identity, default ordering, filtering and result-field meaning. Only pagination behavior is absent, and that is adequately handled in 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 the schema already documents every parameter including formats and limits. The description only restates the filter axes in prose and adds no syntax or edge-case guidance 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 and pins down the domain (banka: bank statement lines, incoming and outgoing payments), which cleanly separates it from abraflexi_list_cash_movements and abraflexi_list_stock_movements. It does not name a sibling explicitly, so it falls just short of a 5.

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

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

The list of filter axes (dates, bank account, variable symbol, text) implies when the tool is appropriate, but there is no explicit when-to-use/when-not statement and no pointer to the related cash-movement or generic list_records 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?

The annotations already declare readOnlyHint=true, so the safety profile is clear. The description adds useful behavior beyond the annotations: it discloses the default newest-first ordering and explains what the returned fields sumCelkem and typPohybuK mean. It does not cover pagination or permission requirements, but the annotation reduces the burden.

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 waste. The primary purpose is front-loaded, followed by a compact note on default ordering and key output-field meanings.

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 whose parameters are fully described in the schema, the description is largely complete: it covers scope, default sort order, and important output fields. Pagination behavior is not described in prose, though limit/start are documented in the schema, and no output schema exists.

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

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

Schema coverage is 100%, so the schema already documents all nine parameters in detail. The description adds some semantic context by naming the filter categories and the amount/direction fields, but it does not materially extend the meaning of individual parameters beyond the schema.

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

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

States a specific verb and resource: list cash desk movements, with the Czech evidence name pokladni-pohyb and a clear scope of cash receipts and payouts. This distinguishes it from sibling movement-list tools such as abraflexi_list_bank_movements and abraflexi_list_stock_movements.

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 useful filtering context (dates, cash desk, variable symbol, text), so intended usage is implied. However, it does not explicitly say when to choose this tool over alternatives like abraflexi_list_bank_movements or abraflexi_list_records, nor does it state 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 already tells the agent this is a safe read, so the description's job is domain context – which it supplies by naming the Czech address-book concept ('adresar') and enumerating the default returned fields (kod, name, ic, dic, e-mail, phone, address). It omits pagination/result-count behavior, but the entry that 'kod' links to invoices is genuinely useful cross-tool 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?

Two sentences, front-loaded with the core action and resource, and the second sentence carries a non-obvious workflow link rather than filler. The field enumeration is dense but each item is informative.

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 six-parameter, zero-required read tool with no output schema, the description covers what the tool searches, what fields come back, and how the returned code is reused. Only paging/result-count expectations are left implicit, which the schema largely 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 coverage is 100%, with limit/start/order/search/fields/city all documented in the schema itself. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('List or search') and resource ('the address book (adresar): customers and suppliers'), and names the domain fields available. It is clearly distinguishable from abraflexi_get_contact (single record) and from the invoice list siblings, though it never explicitly names those 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?

Usage is implied by 'List or search' and the note that 'the code from here identifies the customer in invoices' hints at the follow-up workflow. There is no explicit when-to-use/when-not guidance versus abraflexi_get_contact, abraflexi_list_records, or abraflexi_create_contact.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds the useful behavioral facts that results are Czech paths plus names and that paths are consumable by the record tools. It does not cover result volume, ordering, or whether non-business tables are included in output, which are minor gaps given annotations carry the safety profile.

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

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

Two sentences, front-loaded with the action and return shape, then the follow-on usage note. The Czech examples earn their place by anchoring an otherwise opaque domain term.

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

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

With no output schema, the description correctly states what comes back (Czech path and name), and it explains the downstream contract with list_records/get_record. For a simple one-parameter discovery tool this is nearly complete; only output breadth/ordering is unstated.

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

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

The single 'search' parameter is fully documented in the schema (100% coverage, including case-insensitivity and length bounds) and the description adds nothing about it. Baseline 3 applies because the schema does all the semantic work.

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

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

States a specific verb and resource ('List the evidences (tables) of the company') plus the returned fields (Czech path and name), and grounds the abstract term with concrete examples (faktura-vydana, adresar, cenik). An agent can distinguish this discovery tool from the concrete listing siblings without opening any schema.

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

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

Explicitly routes the agent forward: use a path from here as 'evidence' in abraflexi_list_records / abraflexi_get_record. The 'only business evidences are readable there' note sets a real constraint. It does not explain why an agent would pick this generic route over the dedicated siblings (abraflexi_list_issued_invoices, abraflexi_list_contacts), which is the one remaining ambiguity.

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: default sort order, paging contract ('Returns total, next_start for paging'), and the meaning of the money fields including the currency distinction between sumCelkem/zbyvaUhradit and the *Men fields. That is real behavioral information not present in annotations.

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

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

Three sentences, front-loaded with what the tool lists and its default ordering, followed by field semantics and the paging contract. Dense but every clause carries information; the money-fields sentence is the only one that could be tightened.

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 10 optional parameters, no output schema, and readOnly annotations, the description covers the missing pieces: return shape (total, next_start), pagination workflow, default ordering, and how to widen the returned field set. An agent has everything needed to call this 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 baseline is 3. The description does add genuine value by explaining the money-field semantics and the purpose of 'fields' for retrieving non-default properties, but it does not clarify the date filters, status enum, or search behavior beyond what the schema already documents.

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 issued invoices') and disambiguates with the parenthetical 'sales invoices to customers', which separates it from abraflexi_list_received_invoices. It also declares the default ordering. It stops short of naming the sibling outright, so it is clear but not maximally differentiated.

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?

Filter semantics ('filtered by payment status, customer/supplier code, dates or text') imply when the tool is appropriate, and the status enum values are explained. However, there is no explicit guidance on when to prefer abraflexi_get_issued_invoice for a single record or abraflexi_list_received_invoices for the purchase side.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, and the description adds two behaviours the annotations don't: the default direction and the default sort order ('newest first'). It doesn't mention pagination behaviour (though start/limit are schema-documented), so it's strong rather than exhaustive.

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 zero filler; the direction mapping is front-loaded and the default-sort note follows compactly. Nothing repeats the tool name or title.

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

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

For a read-only, fully documented 9-parameter list tool, the description supplies the two facts an agent can't infer cheaply: which direction values map to which business concept and that results default to newest first. Return shape is undocumented (no output schema), but the field/pagination params cover the essentials.

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 with pattern, range and defaults. The description restates the direction semantics and the default sort that the schema also carries, adding little beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List orders') and immediately splits it into the two order types with their underlying Czech evidence names ('objednavka-prijata' for customer orders, 'objednavka-vydana' for purchase orders). That distinction lets an agent separate this from the invoice and contact listers in the sibling set 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?

Gives concrete selection guidance: direction 'received' means customer orders and is the default, 'issued' means purchase orders to suppliers. It lacks an explicit 'when not to use this' or a named alternative tool (e.g. the invoice listers), so it stops short of 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds the substantive detail that no output schema provides – exactly which product attributes come back, including both VAT-inclusive and VAT-exclusive prices. It omits any mention of paging behavior (the default 20 / next_start convention), which is left entirely to 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 front-loaded sentence with the resource and returned fields stated up front; the parenthetical field list is long but every item carries information an agent needs given there is no output 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?

With no output schema, the description usefully compensates by describing the returned attributes, and the read-only nature is covered by annotations plus the 'List or search' framing. The remaining gap is that it never mentions the paged/next_start nature of results or routes the agent away from the similarly named stock-card listing 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 all five parameters (limit, order, start, fields, search) are already documented with formats and examples in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (list/search) and resource (price list / cenik of products and services), and enumerates the attributes returned (code, name, EAN, prices with and without VAT, purchase price, stocked flag). It does not explicitly differentiate itself from abraflexi_list_stock_cards, which an agent could plausibly confuse with a 'stocked' product listing.

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 'List or search' – the agent can infer that the search parameter narrows results, but there is no statement of when to prefer this over abraflexi_list_stock_cards or abraflexi_get_record, and no exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds genuinely useful behavior: default sort order, paging via total/next_start, and the distinction between company-currency (sumCelkem, zbyvaUhradit) and document-currency (*Men) money fields. It stops short of describing the default field set or result size limits.

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

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

Three dense sentences, front-loaded with purpose and ordering, then filtering scope, then return/semantics. No filler, though the money-field sentence is packed tightly enough that it reads as a glossary dump rather than prose.

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 responsibly states what comes back (total, next_start). All 10 parameters are documented in the schema, so the burden is light; the only gap is not stating which fields are returned by default, which matters for an agent deciding whether to pass 'fields'.

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 semantic meaning the schema lacks: the money-field name mapping and the instruction to pass 'fields' for other properties. It doesn't clarify the default field set that 'fields' overrides, which is the main remaining ambiguity.

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 received invoices') and disambiguates with the parenthetical 'bills from suppliers', which separates it from the sibling abraflexi_list_issued_invoices. Default ordering ('newest first by default') is stated up front.

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 (filtering by status, code, dates, text) but never names an alternative or an exclusion — e.g. it doesn't say to use abraflexi_get_received_invoice for a single bill or abraflexi_list_issued_invoices for outgoing invoices. 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?

The readOnlyHint=true annotation already establishes safety, and the description adds useful behavioral context: default summary fields are returned when 'fields' is omitted, and filtering uses ABRA Flexi's filter language with specific operators and date format. It does not discuss pagination, authentication, rate limits, or error behavior, so it is adequate but not rich.

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

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

The purpose is front-loaded in the first clause, followed by relevant filter details. The long operator enumeration and evidence examples are somewhat dense, but they earn their place by clarifying a non-obvious query language.

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?

Given six parameters, a large evidence enum, full schema description coverage, and a read-only annotation, the description covers the essential purpose and filtering behavior. It is slightly incomplete on sibling-tool routing and does not mention pagination, but pagination is documented in 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 the baseline is 3. The description adds meaning beyond the schema for the most complex parameter by documenting filter operators, like-similar behavior, begins/ends/between/in, and date format, plus the default return-field behavior.

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 records of any business evidence,' and gives examples of evidence types. It is clear what the tool does, but it does not explicitly distinguish itself from the many dedicated list_* sibling tools such as abraflexi_list_issued_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?

The description explains filtering syntax but gives no explicit guidance on when to use this generic tool versus the dedicated sibling tools, nor any exclusions. An agent must infer that this is the fallback/general listing tool.

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

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

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description adds the useful fact that results are per period and what measures are aggregated, but says nothing about pagination behavior, default result shape, or what happens when accounting_period is omitted (that caveat 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 dense sentence with the resource front-loaded and zero filler. It is well-sized for the amount of information conveyed, though it could have spent one more clause routing to the sibling.

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 8-parameter read tool with full schema coverage and no output schema, the description plus schema cover the filters, the fields returned, and period scoping. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains every parameter, including the important accounting_period default. The description introduces Czech field names (stavMJ, rezervMJ, dostupMj) that are not mapped back to parameters, so it adds little beyond the schema baseline.

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

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

States a specific verb and resource ('List stock cards') and enumerates the returned measures (stavMJ, rezervMJ, dostupMj per product/warehouse). It does not, however, distinguish itself from the nearby sibling abraflexi_list_stock_movements, leaving the agent to infer which one it wants.

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 through the filter parameters (product_code, warehouse_code, max_on_hand); there is no explicit statement of when to pick this over list_stock_movements or list_products. No 'when not to use' or prerequisite guidance is given.

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

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

readOnlyHint=true already establishes the safe-read profile, and the description adds the useful default sort ('newest first by default'). It says nothing about volume limits, pagination behavior, or what a returned movement record looks like, so it goes only slightly 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?

A single dense sentence with the resource and default ordering front-loaded and zero filler. 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 read-only, zero-required-parameter list tool with a fully documented schema and safe annotations, this is close to sufficient. The main omission is any hint of the return shape (which fields exist without 'fields') since no output schema is provided.

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 seven parameters fully documented (date bounds, limit, start, order pattern, fields, warehouse_code). The description only echoes the warehouse and date filters, adding no syntax or behavior 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 and even enumerates the movement subtypes (receipts, issues, transfers) with the vendor's Czech term 'skladovy-pohyb'. That is enough to separate it from list_stock_cards, list_bank_movements and list_cash_movements, though no sibling is named explicitly.

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

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

The sentence describes capabilities ('filtered by warehouse or dates') rather than when to select this tool over alternatives. There is no mention of when not to use it, nor of list_stock_cards or list_records as the choice for inventory levels or other record types.

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 mark this as a destructive write, and the description adds important behavior beyond them: partial update semantics, required pre-existence, error on wrong id, overwriting current values, and a recommended dry-run validation step. This is exactly the kind of mutation context an agent needs before invoking the 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?

The description is four short sentences, front-loads the write operation, and every sentence contributes useful information about existence requirements, patch behavior, overwrite behavior, or dry_run. There is no wasted text.

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

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

For a 15-parameter destructive update with full schema coverage and no output schema, the description covers the essential invocation context: existing record required, partial update, destructive overwrite, and dry-run validation. It could add a note about what happens on success or how to verify the result, but nothing critical for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful semantics about how optional parameters behave: only the fields passed are changed. It also reinforces dry_run as a validation-only mode, which helps the agent reason about the parameter set as a whole.

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: change fields of an existing address-book entry. It also distinguishes this from create operations by explicitly saying a wrong id is an error and nothing is created, so an agent can tell it apart from abraflexi_create_contact without inspecting either schema.

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

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

It gives clear usage context: the entry must already exist, only passed fields are changed, and dry_run should be used first to check. It does not explicitly name alternatives such as using abraflexi_get_contact to obtain the id or abraflexi_create_contact when the entry is missing, so it falls short of full when/when-not/alternative guidance.

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