Vyfakturuj MCP by usefulapi

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

The destructiveHint=true annotation already signals a mutating operation, so 'WRITE.' is mostly redundant, but 'nothing is sent' meaningfully disambiguates a non-obvious naming risk and the description discloses the return shape ('Returns the new contact with its id'). It stops short of permissions, duplicate handling, or idempotency 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?

Four tight fragments, front-loaded with the operation type, then purpose, then the input constraint, then the return and endpoint. Every sentence carries unique information with no repetition of schema or annotation content.

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, all-optional mutation with no output schema, the description supplies the critical missing piece (the effective required-field rule) and the return value. It leaves secondary behavior such as duplicate detection or field-conflict resolution unaddressed, which is a minor gap 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: it identifies 'name' as the address-book label and states a cross-field requirement (at least one of name/company/lastname) that is invisible in a schema where 0 parameters are required.

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 ('Adds a contact to the address book') and preempts the most likely confusion by noting it is not a customer message and sends nothing. That distinction lets an agent separate it from vyfakturuj_create_invoice and the messaging-style siblings without opening a schema.

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

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

Provides a concrete precondition for use ('Give at least a name ... or company or last name') and clarifies the negative case (nothing is sent). It does not, however, point to any alternative sibling tool or describe when to prefer lookups or list tools instead.

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

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

The destructiveHint annotation signals a mutation, but the description goes far beyond it: no draft state, immediate issuance, consumption of the next number in the series, and a remediation path ('delete or cancel it in Vyfakturuj if wrong'). It further discloses that reminders and paid notices are disabled, which is non-obvious behavioral context an agent could not infer from the annotation.

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

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

Front-loaded with the critical 'WRITE' and no-draft warning, then organized into behavior, customer, items, and defaults. Dense with parenthetical cross-references but virtually no waste; slightly heavy for a single description block.

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 25-parameter mutation tool with no output schema, the description covers consequences, prerequisites, and sibling dependencies thoroughly. The one residual gap is that it never says what is returned (e.g., the new document id), which matters more given there is no output schema, but the behavioral coverage is otherwise strong.

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 integrative meaning the schema does not: the either/or choice between id_customer and the customer_* fields, the minimum viable item shape (text + unit_price), and the net-vs-gross rule tied to calculate_vat. It does not explain every field, but the added cross-field guidance is real value.

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 ('Creates a document in Vyfakturuj') and clearly distinguishes itself from read-side siblings like vyfakturuj_get_invoice and vyfakturuj_list_invoices by starting with 'WRITE.' The title and description together make the operation 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?

Explicitly routes the agent to sibling lookups ('id_customer ... from vyfakturuj_list_contacts', 'id_number_series / id_payment_method come from vyfakturuj_list_number_series / vyfakturuj_list_payment_methods') and states when defaults apply otherwise. It also fences off adjacent concerns by stating what the tool does NOT do (no e-mail, no payment marking, no money movement).

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 this is a safe read. The description adds useful context by enumerating the returned field set and citing the underlying endpoint, but says nothing about auth requirements, error behavior for missing ids, or rate limits.

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

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

A single front-loaded sentence that leads with what is returned and follows with the field inventory. The trailing 'GET /contact/{id}/' is mildly redundant with the tool name but costs little.

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

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

With no output schema, the description carries the burden of describing return values and does so adequately via the field list. For a one-parameter read tool this is close to sufficient, though it omits failure modes and any note that the id must come from the list 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 coverage is 100% and the single id parameter is fully documented in the schema, including its provenance ('from vyfakturuj_list_contacts'). The description adds no parameter-level detail 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?

The description names a specific verb and resource ('One address-book contact') and enumerates the returned field groups (billing/delivery address, ICO/DIC, e-mails, default texts, days_due), so the agent knows exactly what this fetches. It does not explicitly contrast itself with the sibling vyfakturuj_list_contacts, so it falls short of a 5.

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

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

Usage is implied by the singular-resource framing and the id parameter, but the description never states when to use this versus vyfakturuj_list_contacts or that the id must come from a prior listing. 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds that the response is complete ('all fields', enumerating blocks), which is useful, but it says nothing about auth requirements, not-found/error behavior, or id provenance beyond the endpoint path. Adequate but not rich against the annotation 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?

Front-loaded with the key fact ('One document with all fields') followed by a compact field enumeration and endpoint. Dense but every clause carries information, especially since no output schema exists to carry the field list.

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 field enumeration (supplier/customer blocks, items, totals, flags, URLs) does the heavy lifting of describing the return value, which is genuinely valuable. For a low-complexity single-id read tool this is nearly complete, though it omits error/not-found 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% and the single id parameter is already fully documented in the schema (including its origin from list_invoices). The 'GET /invoice/{id}/' fragment only re-confirms that id is a path parameter, adding little 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 conveys that the tool returns a single full invoice document ('One document with all fields'), which implicitly distinguishes it from the list siblings. However, it never states the action explicitly (e.g. 'retrieve a single invoice by id') and instead reads as a field inventory, so the purpose is inferred rather than stated.

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

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

There is no when-to-use guidance and no mention of alternatives, even though vyfakturuj_list_invoices exists as the obvious alternative for multiple invoices. The agent must infer that this is for fetching one invoice by id.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely non-obvious context: the absence of a template list endpoint and the origin of the id. It stops short of describing response shape or error behavior, but the added constraint is meaningful.

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: the first establishes scope and return content, the second states the constraint and endpoint. Nothing is redundant and the most decision-relevant fact is easy to find.

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

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

For a single-parameter read tool with no output schema, the description covers the resource, the payload contents and the id-provenance constraint. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema's terse 'The template id.' by telling the agent where the id physically comes from (the number in the template's URL in Vyfakturuj), which is the practical semantic an agent needs.

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 template/recurring invoice by id) and enumerates the returned payload (items, customer, schedule, settings), plus the underlying endpoint GET /template/{id}/. It also gives local-language aliases (sablona, pravidelna faktura) that help an agent match user phrasing.

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 explains the precondition for use: there is no list endpoint for templates, so the id must come from the user. This tells an agent not to hunt for a list tool, which is the key routing decision. It doesn't name a competing sibling explicitly, but the guidance is clear 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, so the safety profile is covered, and the description adds the GET /contact/ endpoint and pagination via rows_limit/rows_offset. It does not describe return ordering, total counts, or empty-result behavior, so it is adequate but not rich beyond the structured fields.

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?

Tight and front-loaded: the search verb and resource lead, followed by return fields, filters, pagination, and endpoint, with no filler sentences. The dense field listing is efficient rather than padded.

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

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

For a read-only list tool with 100% schema coverage, no required params, and no output schema, the description covers filters, pagination, returned fields, and the HTTP endpoint. Nothing critical is missing, though it could clarify the 'tel' vs 'phone' naming and result semantics.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, making 3 the baseline. The description merely restates the filters (though it says 'phone' where the schema param is 'tel') and adds no syntax or format detail 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 ('Search the address book'), and enumerates the returned fields (id, name, company, ICO, DIC, address, e-mail, phone, days_due), so the agent knows exactly what it retrieves. It does not explicitly name a sibling to distinguish itself from, but list-vs-get is inherent in the 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 description says which attributes can be filtered (q, ICO, DIC, name, e-mail, phone), which implies usage context, but it never states when to use this versus vyfakturuj_get_contact or other list tools, nor any exclusions. Usage is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description still adds real context by enumerating the returned row fields (id, number, type, VS, currency, total, flags/flags_decoded with decoded meanings, public/PDF URLs) and confirming paging. It omits rate limits, auth requirements, and total-result counting 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?

One dense paragraph, front-loaded with purpose, the sibling alternative, and the high-frequency sort hint before the longer return-field enumeration. Each clause carries information, though it runs long and could be split for scanability.

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

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

No output schema exists, so the description correctly carries the burden of describing the row shape (including decoded flags and URL fields) and paging. Combined with a fully documented 11-parameter schema, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds a small amount of meaning by consolidating the filter set (q, customer id, type, number, VS, currency, creation date range) and by giving a default sort example. It does not add new syntax beyond what the schema documents for sort, type codes, or date formats.

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 (search/list) plus the resource family in local terms (faktury, zalohove faktury, proformy, objednavky) and explicitly distinguishes itself from vyfakturuj_get_invoice. An agent can tell what this tool returns 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?

Routes the agent to the correct sibling: 'use vyfakturuj_get_invoice for the whole document with items', and gives a concrete usage hint ('pass sort=date_created~desc for the newest first'). No explicit when-not guidance (e.g. interaction with list_contacts or other list tools) beyond the single 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?

readOnlyHint=true already declares this as a safe read, so the description carries a lower burden. It adds the GET endpoint and the shape of the returned data, but says nothing about auth requirements, pagination, or scoping, which leaves minor gaps for a settings-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?

Two compact sentences plus an endpoint reference; the returned fields are front-loaded before the usage hint. No filler, though the '(ciselne rady)' gloss is slightly decorative.

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 describing the returned fields is genuinely necessary and done here. Combined with the readOnly annotation and the create_invoice link, an agent has enough to call and use this correctly, barring pagination details.

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

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

The tool takes zero parameters, so there is nothing to document and the baseline is 4. The description correctly does not invent parameter semantics.

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 the resource (numbering series of the account) and enumerates the returned fields (id_number_series, document type, name, number pattern), so an agent knows exactly what this returns. It lacks an explicit verb but the title 'List number series' and the GET endpoint make the action unambiguous.

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

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

It gives concrete downstream guidance: 'Use the id in vyfakturuj_create_invoice,' which tells the agent why and when to call this relative to a sibling. There is no explicit when-not or exclusion, but the workflow context is clear.

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

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

readOnlyHint=true already declares the safety profile, so the bar is lower; the description still adds the REST endpoint (GET /settings/payment-method/) and explains the semantics of the returned type codes (1 bank transfer, 2 cash, 4 cash on delivery, 8 card). It does not state whether the type list is exhaustive (trailing '...' implies more codes exist) or mention pagination/empty-list behavior.

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

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

Two compact sentences that front-load the returned structure and end with the actionable id-usage hint and endpoint. The enum expansion is dense but useful; the trailing 'GET /settings/payment-method/.' is the only mildly extraneous element.

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

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

With no output schema, the description carries the burden of describing returns and does so for the key fields (id, name, type) plus the enum mapping, which is the minimum an agent needs to pick a payment method id. The incomplete enum ('...') and absence of ordering/empty-state notes are the only gaps for a simple zero-param list 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?

The tool takes zero parameters, so the baseline is 4; the empty input schema is consistent with the description, which implies an account-scoped listing with no filtering inputs.

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 ('The payment methods of the account') and enumerates the returned fields (id_payment_method, name, type) with the type enum mapping, so an agent knows exactly what comes back. It is clearly distinct from sibling list tools such as list_tags or list_number_series, though it never states the verb 'list' explicitly and leans on the title for that.

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

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

It gives explicit downstream guidance: 'Use the id in vyfakturuj_create_invoice', which tells the agent why and when this call matters in the workflow. It does not name any alternative or exclusion condition, but for a unique read-only settings lookup there is no competing sibling to route away from.

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

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

The readOnlyHint annotation already declares this as a safe read, lowering the disclosure bar. The description adds useful context (the endpoint GET /settings/tags/ and the shape of returned records) but says nothing about pagination, ordering, or rate limits. Adequate, 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?

Two short sentences with the resource definition front-loaded and the endpoint trailing. No filler, though the parenthetical '(stitky)' and bare endpoint add only marginal value.

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 enumerates the returned fields (id_tag, name, colour) and clarifies that id_tag links to invoices. For a simple read-only list endpoint this covers what an agent needs.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The schema is trivially complete at 100% 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 names the specific resource ('the tags (stitky) of the account') and enumerates the returned fields (id_tag, name, colour), which distinguishes it from the sibling list_contacts/list_invoices/list_number_series tools. It never states the verb 'list' explicitly, but the GET endpoint and the resource scope make the purpose 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?

There is no explicit when-to-use, when-not-to-use, or alternative guidance. The note 'Invoices carry an id_tag' hints at why the data matters (correlating tags with invoices), but it does not tell an agent when this tool should be selected over its siblings.

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