Quaderno MCP by usefulapi

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

Annotations only declare readOnlyHint=true, but the description goes further: it names the underlying endpoint (GET /tax_rates/calculate), confirms no record is created, and enumerates the response fields including the status enum values (taxable|non_taxable|not_registered|reverse_charge). That is substantive behavioral context an agent cannot get from the annotations alone.

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 purpose and read-only status before the endpoint and return shape. The response-field enumeration is long but earns its place because there is no output schema; still, it is the densest part of an otherwise tight definition.

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 13 parameters, no output schema, and only a readOnlyHint annotation, the description compensates fully: it covers purpose, side-effect profile, endpoint, and the return contract including status values. 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 coverage is 100%, so the baseline is 3. The description adds framing beyond the schema by tying inputs to jurisdiction logic ('VAT / GST / US sales-tax rules per jurisdiction'), which implicitly explains why location fields (street, city, postal code) matter, though it does not document individual parameters.

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 ('Calculate the correct tax rate/amount for a sale') plus the inputs it depends on (customer location, product). It is unmistakably distinct from the CRUD siblings like quaderno_create_transaction, which merely record a sale rather than compute tax.

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 context of use ('for a sale given the customer's location and product') and explicitly clarifies 'READ-ONLY (no record is created)', which steers an agent away from the create_* siblings. It does not name a specific alternative tool, so it falls short of a full when/when-not 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 description explicitly flags 'MUTATES Quaderno data', which is consistent with the destructiveHint annotation and adds the endpoint (POST /contacts) and the return behavior ('Returns the created contact'). It doesn't cover auth requirements, rate limits, or duplicate-handling, so it stops short of the richest disclosure.

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

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

A single tight paragraph that front-loads the mutation warning, then the required-vs-optional split, then the endpoint and return. No redundant restating of the 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 create tool with 8 params, one required enum, and a nested object, it supplies the mutation flag, the required argument, the fields escape hatch, the endpoint, and the return value. Missing only edge-case behavior (duplicates, permission needs), which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by enumerating which additional attributes can go in the `fields` escape hatch (phone_1, region, postal_code, tax_status, discount, etc.), which the schema's generic nested-object definition does not spell out.

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 contact') and clarifies the scope ('customer or vendor'), making it clearly distinguishable from quaderno_get_contact, quaderno_list_contacts and quaderno_update_contact. An agent can identify this as the creation entry point without opening the schema.

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

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

It explains how to supply arguments ('Provide kind plus a name; use `fields` for any other attribute') but gives no explicit when-to-use guidance against siblings, e.g. no instruction to use quaderno_update_contact for existing contacts or to look up first. Usage context 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?

Opens with 'MUTATES Quaderno data', consistent with the destructiveHint=true annotation, and adds genuinely new context beyond it: the POST endpoint and the fact that the created invoice (with permalink and pdf) is returned. No contradiction with 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?

Front-loads the mutation warning and the required inputs, then endpoint and return value. Slightly redundant on the item shape, which the schema already documents, but overall dense and well-ordered.

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, and the description compensates by saying what is returned (created invoice incl. permalink, pdf). For a nested-object mutation tool with zero required params, it covers inputs, escape hatch, and response 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 already 100%, so baseline is 3, but the description adds value by enumerating the concrete attributes usable in `fields` (currency, issue_date, due_date, po_number, notes, tag_list, custom_metadata, payment_details) and sketching item keys with optional markers.

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 ('create an invoice for a contact') and gives the underlying endpoint POST /invoices, so the agent knows exactly what is produced. It never names a sibling to contrast with (e.g. create_transaction vs create_invoice), so it stops short of full sibling differentiation.

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

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

Clear invocation context: supply contact_id (or a full contact via `fields`) plus items, and use `fields` as the escape hatch for anything else. It doesn't state when to prefer this over alternatives such as create_transaction, but the prerequisites are 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?

Goes beyond the lone destructiveHint=true annotation by naming the exact API surface (POST /items) and stating that the new item is returned. It still omits duplicate-handling, required scopes, and whether the create is reversible, so it stops short of full 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?

Three dense sentences: mutation warning first, then required params and the escape hatch, then endpoint and return value. No filler and nothing buried late.

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

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

For a 7-parameter create tool with no output schema, it covers required inputs, optional-field routing, endpoint, and return value. The remaining gap is failure behavior (validation errors, duplicate items), which matters for a mutating call but is a modest omission.

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 value by enumerating attributes that can be passed through `fields` — description, tax_class, tax_type, country, stock — several of which are not typed properties in the schema. That makes the escape-hatch parameter actionable rather than abstract.

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 product/item in the catalog") and leads with the MUTATES marker, which separates it cleanly from the read siblings (quaderno_get_item, quaderno_list_items) and from the other create_* tools. An agent can identify it without opening the schema.

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

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

It tells the caller to supply name + unit_cost and to route other attributes through `fields`, which is practical calling guidance. It never says when to prefer this over a sibling such as quaderno_request or the update path, so tool selection is only implied.

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

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

Adds real context beyond the single destructiveHint annotation: the mutation profile ('MUTATES Quaderno data'), the side effect of automatic tax calculation and document generation, the underlying endpoint (POST /transactions), and the return shape (created invoice/credit-note). It does not cover idempotency or error behavior, but the annotation bar is already partly met.

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-loads the mutation warning before the mechanics, and each sentence carries a distinct piece of information (type semantics, required inputs, escape hatch, endpoint, return). The parenthetical field list is long but is the substantive payload of the escape-hatch guidance, not 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 six-parameter, nested-object mutation tool with no output schema, the description covers mutation semantics, required vs optional inputs, the escape hatch, the HTTP endpoint, and the return value. Nothing an agent needs in order 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 further by naming the non-typed attributes the `fields` escape hatch is intended for (date, currency, shipping_address, evidence, processor, exchange_rate, tags, custom_metadata), which the schema's generic 'additional raw Quaderno fields' does not spell out. It also clarifies that items are the required core and payment/customer are the expected companions.

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 ('record a sale or refund transaction'), names the type enum values, and discloses the downstream effect (Quaderno computes tax and produces the compliant document). An agent can distinguish this from quaderno_create_invoice or quaderno_calculate_tax 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?

Tells the caller what to supply ('Provide the customer, items, and payment') and routes any untyped attribute into `fields` with a concrete enumeration of examples. It does not explicitly state when to prefer this over quaderno_request or quaderno_create_invoice, so it falls short of full alternative routing.

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

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

readOnlyHint=true already declares the safety profile, so the description only needs to add context. It adds the underlying REST endpoint (GET /contacts/{id}), which is mildly useful for agents mapping to the API, but says nothing about return contents or 404 behavior for a missing id.

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

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

Two short sentences, front-loaded with the action and followed by the endpoint mapping. No filler, though the endpoint restatement is arguably 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 single-parameter read-only getter with an annotation covering safety, this is nearly sufficient. The remaining gap is that no output schema exists and the description doesn't say what a contact record contains or how missing ids are handled.

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 there is only one required parameter, so the schema already documents 'id' fully. The description's 'by id' restates rather than extends 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+resource: 'Fetch a single contact by id.' The word 'single' implicitly distinguishes it from quaderno_list_contacts and the create/update siblings, 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?

Usage is only implied: the agent can infer this is the tool for retrieving one known contact versus listing all contacts. There is no explicit statement of when to use this over quaderno_request or list_contacts, and no mention of prerequisites or what happens when the id is unknown.

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 underlying endpoint (GET /credit_notes/{id}), which usefully signals a direct read with no side effects. It says nothing about 404/error behavior, auth requirements, or rate limits, so it adds only modest context 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 short sentences, front-loaded with the action and resource, zero filler. The endpoint mapping is compact and 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 single-parameter read tool with a fully described schema and a readOnly annotation, this is nearly complete. The only minor gap is that no output schema exists and the description does not hint at the shape of the returned credit note.

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% for the single `id` parameter, so the schema already fully documents it. The description's 'by id' adds no format, source, or constraint detail beyond what the schema states.

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

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

States a specific verb and resource ('Fetch a single credit note') with an explicit scope qualifier ('by id') that separates it from quaderno_list_credit_notes. It does not name the sibling outright, but the singular/ID framing makes the distinction inferable.

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

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

Usage is only implied: fetch one record when you have its id. There is no explicit statement of when to prefer this over quaderno_list_credit_notes or quaderno_request, and no prerequisites or failure conditions 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 the underlying endpoint mapping, which helps correlate with API docs, but says nothing about failure behavior (e.g., unknown id) or what the response contains.

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

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

Two short sentences with the operation front-loaded and no filler. The endpoint sentence is marginally redundant but compact and does add lookup 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?

For a one-parameter read tool with annotations covering safety, this is nearly sufficient, but with no output schema the description gives no hint of the returned expense's shape or fields, leaving a small but real gap.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already defines it. The description's 'by id' adds no syntax, format, or sourcing detail 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 ('Fetch a single expense by id') and pins the exact API route, so it is clearly distinct from quaderno_list_expenses. It stops short of naming the sibling it contrasts with, which is what a 5 would require.

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

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

Usage is only implied: an agent infers this is for retrieving one known expense id versus listing or creating expenses. There is no explicit guidance on when to prefer this over quaderno_list_expenses, or how to obtain a valid id.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds useful context by disclosing the shape of the returned object (items, taxes, payments, permalink, pdf) and the underlying endpoint, but says nothing about not-found behavior or error semantics.

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, and the core action plus scope is front-loaded ahead of the return-payload and endpoint 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 one-parameter read tool with annotations covering safety, this is nearly complete: the return contents are enumerated even though no output schema exists. Only retrieval failure behavior is left unstated, 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?

The schema documents the single parameter at 100% coverage ('The resource id.'), so the baseline is 3. The description's 'by id' confirms it is the invoice id rather than any generic resource id, but adds no format, prefix, or sourcing detail beyond that.

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 (Fetch) and resource (a single invoice by id), and the word 'single' separates it from the sibling quaderno_list_invoices without needing to name it. It also enumerates what the returned object contains, so the agent knows exactly what it gets back.

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 id' signals a retrieval-after-you-know-the-id pattern, and 'full object' hints it is the place to get details. It never states when to prefer this over quaderno_list_invoices or quaderno_request, and gives no preconditions 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?

readOnlyHint=true already declares this is a safe read, so the description's main added value is exposing the underlying REST path. It says nothing about failure behavior (e.g., unknown id), rate limits, or what the returned item contains; with annotations covering safety, this 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?

Two terse sentences with zero filler, and the core action is front-loaded before the endpoint reference. 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?

For a single-parameter read tool with full schema coverage, a readOnly annotation, and no output schema, the definition gives everything needed to invoke it correctly. Only a note on not-found behavior would improve 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?

Only one parameter exists and the schema documents it at 100% coverage ('The resource id.'). The description's 'by id' adds no format or sourcing detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Fetch') and resource ('a single product/item by id'), and the underlying endpoint GET /items/{id} removes ambiguity. The word 'single' implicitly distinguishes it from list_items, 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 'by id' phrasing implies you call this when you already have an identifier, but there is no explicit when-to-use, when-not, or named alternative such as quaderno_list_items for retrieval without an id. Usage is inferable rather than stated.

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

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

readOnlyHint=true already declares the read-only profile, so the description carries a lighter burden. It adds the underlying REST mapping (GET /receipts/{id}), which helps with error/404 reasoning, but says nothing about what happens on a missing or malformed 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?

Two short sentences, verb-and-resource first, endpoint detail second. No filler and nothing buried.

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

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

For a one-parameter read tool with readOnlyHint and full schema coverage, this is close to sufficient. The only real gap is that no output schema exists and the description does not characterize the returned receipt object.

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?

Single required id parameter with 100% schema description coverage, so the schema already documents it. The phrase 'by id' adds no format, source, or lookup guidance beyond that, which is the baseline case.

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 ('Fetch a single receipt by id'), which clearly separates it from quaderno_list_receipts by scope (single vs. list). It does not explicitly name the list sibling, but the singular framing 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?

There is no explicit when-to-use, when-not-to-use, or named alternative; the agent must infer that this applies when a receipt id is already known and that list_receipts is the lookup path otherwise. 'by id' implies a precondition but nothing more.

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 genuinely useful context beyond the annotation: default ordering (newest first), the underlying endpoint GET /contacts, the returned field set, and the fact that results become an envelope { data, pagination } once more pages exist. It does not disclose authentication requirements, rate limits, or the default page size 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: what it lists and default ordering first, then endpoint and return shape. Nothing is redundant or padded, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description carries the burden of describing return values, and it does so concretely by listing key fields and the pagination envelope. What remains unstated — auth requirements and whether filtering is server-side — is minor for a simple read-only 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 description coverage is 100%, so all four parameters (q, page, per_page, created_before) are already documented in the schema, including the preference for created_before over legacy page. The description adds nothing about parameter syntax or semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('List contacts') and adds the domain gloss '(customers/vendors)' plus default ordering 'newest first', which orients an agent immediately. It does not explicitly distinguish itself from quaderno_get_contact or the search-style sibling, so sibling differentiation is left 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?

The listing intent is clear from the name and description, but there is no explicit guidance on when to prefer this over quaderno_get_contact (single record) or how to narrow results with q. 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?

With readOnlyHint already declaring this a safe read, the description earns credit for adding real behavioral facts: newest-first ordering, the underlying endpoint (GET /credit_notes), and the fact that the response becomes { data, pagination } when more pages exist.

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, ordering stated up front, no filler. Every clause carries information an agent can use.

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 listing tool with full schema coverage, the description supplies the missing pieces: ordering, response envelope, and pagination behavior (there is no output schema, so the envelope note is important). It stops short of explaining pagination strategy end-to-end, but the schema covers the cursor mechanics.

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%, including notable details like the comma-separated date format and the cursor semantics of created_before, so the baseline 3 applies. The description repeats no parameter semantics and adds nothing beyond the schema here.

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

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

The description gives a specific verb and resource ('List credit notes'), clarifies the domain term with '(refund documents)', and states ordering ('newest first'). The list vs get distinction from quaderno_get_credit_note is implicit in the name and verb rather than explicitly 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 rather than spelled out: it's a read-listing tool with newest-first ordering, but there is no explicit when-to-use, when-not-to-use, or routing to alternatives such as quaderno_get_credit_note or the generic quaderno_request.

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 on top: newest-first ordering and the fact that responses are wrapped as { data, pagination } when more pages exist. That envelope detail is behavior an agent cannot get from the schema, since there is no output schema. Missing are rate-limit or auth hints, 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?

Three short sentences, front-loaded with the resource definition and sort order, then the response shape. The "Quaderno API: GET /expenses" line is the weakest part — it doesn't change agent behavior — but it is a single clause and not enough to call the description 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 six-filter list tool with a fully described schema, the essential gaps are covered: what the resource is, ordering, and the pagination envelope in the absence of an output schema. Nothing needed to invoke it correctly is missing, though a word on picking between filters and on the get_expense sibling 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%, so all six parameters (q, date, contact, page, per_page, created_before) are already documented, including the note that page is legacy and created_before is preferred. The description adds nothing further about parameter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ("List expenses") and disambiguates the domain term by glossing expenses as "bills you received," which separates them from invoices/receipts in the sibling set. Sort order (newest first) is also given. It doesn't explicitly route against quaderno_get_expense for single-record retrieval, but the list/get distinction is self-evident.

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

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

Usage is only implied: an agent can infer this is the collection endpoint and that filters live in the schema, but there is no explicit when-to-use, no mention of the single-record alternative, and no guidance on which filter to reach for (e.g. q vs contact). Adequate but with clear gaps.

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 establish readOnlyHint=true, and the description adds useful behavioral context: it names the underlying API endpoint, ordering, returned invoice fields, and the { data, pagination } wrapper for multi-page results. It does not contradict the read-only 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?

The description is compact and front-loaded: purpose and ordering first, then endpoint and return shape. The field list and pagination note earn their place because 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?

Given the lack of an output schema, the description compensates by naming the returned invoice fields and pagination wrapper. Combined with the fully documented schema and read-only annotation, an agent has enough to invoke and interpret the tool 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 all seven parameters are already documented in the input schema. The description mentions 'optional filters' and pagination wrapping but does not add meaningful parameter-level semantics beyond what the schema provides.

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

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

States a specific verb and resource ('List invoices'), adds ordering ('newest first'), and clarifies that filters are optional. This clearly distinguishes it from single-invoice siblings such as quaderno_get_invoice and mutation siblings such as quaderno_create_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?

The description implies the tool is used for browsing invoices with optional filters and newest-first ordering. However, it does not explicitly say when to use this versus quaderno_get_invoice or other list tools, nor does it state any exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered; the description adds that this is GET /items, returns newest first, enumerates returned item fields, and wraps results as { data, pagination } when more pages exist. It still omits auth or rate-limit details, so it falls short of a full 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, front-loaded with purpose and ordering, then return shape. Every clause adds useful information with no repetition or filler.

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

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

For a simple read-only list tool with full schema coverage, the description supplies the missing return-shape and pagination context even though there is no output schema. It could be slightly more complete by routing agents to quaderno_get_item for single-record retrieval, but the core call is well supported.

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

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

Schema description coverage is 100%, so page, per_page, and created_before are already documented in the schema. The description adds no parameter-specific syntax, defaults, or selection guidance beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description uses a specific verb, 'List', and resource, 'products/items in the catalog', plus the ordering scope 'newest first'. It is naturally distinct from quaderno_get_item and quaderno_create_item, which fetch one item or create an item rather than enumerate the catalog.

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 context, 'List products/items in the catalog', which implies using it when enumerating catalog entries, but it does not explicitly say when to choose this over quaderno_get_item for a single item or when not to use it. No exclusions or alternatives are named.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's marginal burden is lower. It adds useful scope ('where the account is registered to collect tax'), the returned field set, and the backing endpoint, but says nothing about pagination, ordering, or result size for accounts with many jurisdictions.

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 resource and scope, with the endpoint reference trailing as supporting detail. No filler or redundancy; 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 zero-parameter read tool with no output schema, the description compensates well by enumerating the returned fields and clarifying the registration scope. Only the absence of any volume/pagination note keeps it from being fully complete.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate – baseline 4 applies. The parenthetical field list describes the response shape rather than inputs, which is accurate but not 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?

States a specific verb and resource ('List the tax jurisdictions') and scopes it precisely to jurisdictions 'where the account is registered to collect tax', which distinguishes it conceptually from quaderno_list_tax_codes. It does not explicitly name or contrast with that sibling, but the resource definition 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?

Usage is only implied by the verb 'list' – an agent can infer this is the read path for jurisdiction data, but there is no statement of when to prefer it over quaderno_list_tax_codes or quaderno_calculate_tax, and no prerequisites or exclusions 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context beyond annotations: results are newest first, the endpoint is GET /receipts, and responses are wrapped as { data, pagination } when more pages exist. It does not mention auth or rate limits, but those are not essential here.

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 three short sentences with zero waste. It is front-loaded with the core action and ordering, then adds endpoint and response-shape details only where they are useful.

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

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

For a read-only list tool with six optional, fully documented parameters, the description supplies the important context missing from structured fields: ordering and the shape of paginated responses. Output schema is absent, and the wrapper note helps compensate for that. Auth and rate-limit details are omitted but are not critical for correct invocation.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the input schema. The description adds no parameter-specific meaning beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'List receipts'. It also adds ordering ('newest first') and the underlying endpoint, making the operation clear. It does not explicitly differentiate this tool from related siblings like quaderno_get_receipt or other list tools, so it falls short of a 5.

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

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

The description describes what the tool does but gives no explicit guidance on when to use it versus alternatives such as quaderno_get_receipt for a single receipt. There are no exclusions, prerequisites, or routing cues for the many sibling list_* 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?

readOnlyHint=true is consistent with "List"; the description adds the underlying API call (GET /tax_codes) and the exact return fields, which annotations don't convey. It does not state whether the catalog is paginated or cached, so it is good but not fully transparent.

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 delivers purpose, return fields, and downstream use, followed by a one-line API reference. 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?

With no output schema, the description carries the burden of describing returns and does so by naming the three fields. It omits any mention of result ordering or whether the list is static, a minor gap for a trivial zero-param read.

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 helpfully documents the response shape (id, name, description) in place of any parameter discussion, adding value rather than repeating schema 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 ("List the product tax codes Quaderno supports") and even enumerates the returned fields (id, name, description), so the agent knows exactly what comes back. No sibling lists tax codes, so differentiation is implicit but 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 clause "used as the tax_code on products / tax calculations" tells the agent when this tool is relevant — before creating items or running tax calculations. It stops short of explicitly naming a prerequisite sequence or alternative, but the use 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that results are scoped to 'the account's' webhooks and enumerates the fields returned, which is useful context, but says nothing about ordering, pagination, or empty-account behavior.

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

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

Two short clauses with zero waste: purpose and returned fields first, then the underlying API endpoint. Nothing to trim.

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

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

With no parameters and no output schema, the description carries the burden of describing the return value and does so by listing id, url, and events. It stops short of noting pagination or response envelope details, but is sufficient to call the tool 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?

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies no filtering or options are accepted.

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 account's configured webhooks') and names the returned fields (id, url, events). It is unambiguous against all siblings, none of which deal with webhooks, though it does not explicitly differentiate itself.

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 verb and resource (inspect configured webhook endpoints), but there is no explicit guidance on when to prefer this over other tools or what prerequisites exist. For a simple, no-parameter listing call this is acceptable but minimal.

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 that this is a safe, non-mutating call, and the description's mention of GET /ping reinforces that. It adds a little beyond annotations by saying it returns account/authentication status, but is silent on error behavior — whether an invalid key yields an error, a false flag, or a thrown exception.

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 action and result, then the raw endpoint as a reference detail. Nothing is padded or repeated.

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

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

For a zero-param, read-only ping with no output schema, the description gives enough: what it does and what it returns. The one meaningful omission is how failure surfaces to the caller, which matters specifically for an auth-verification 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 there is nothing to disambiguate; baseline 4 applies. The description correctly implies no inputs are needed to perform the check.

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 — verify the API key and connection by pinging Quaderno — and is unmistakably distinct from every sibling, which are all data CRUD/list operations. An agent can tell at a glance this is the credential check.

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 purpose implies the usage (check credentials before/after setup), but the description never states when to call it — e.g. before a first call, after a key rotation, or on auth errors — nor does it warn against using it as a health probe in a loop. Usage is inferred rather than declared.

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 known; the description reinforces it ('READ-ONLY — only GET is allowed') and adds the /api path convention. It does not describe rate limits, auth requirements, or the shape/format of the raw response, which matters for a raw passthrough. Useful but not rich beyond 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?

Three short sentences, front-loaded with the escape-hatch framing, followed by the constraint and the path format. The trailing 'Quaderno API: GET {path}.' is mildly redundant but harmless.

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

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

For a raw read passthrough with no output schema, the description covers what the tool does, the constraint, and the path format, leaving the agent able to call it correctly. It could say more about the raw return payload, but the API-passthrough nature makes that largely implied.

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 both the required 'path' and optional 'query' are already documented in the schema. The description restates the path convention ('taken after /api') consistently with the schema but adds no syntax detail beyond it, so baseline 3 applies.

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

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

States a specific verb (GET) and the exact resource scope (any Quaderno API path after /api), and explicitly frames itself as an escape hatch for paths 'not wrapped by a dedicated tool'. This distinguishes it cleanly from the many dedicated siblings like get_contact and 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?

The phrase 'not wrapped by a dedicated tool' establishes when to reach for this tool versus the dedicated siblings, and the example paths ('/tax_ids', '/evidence') show it targets the long tail. It stops short of an explicit 'prefer the dedicated tool when one exists' instruction, so it is clear context rather than full when/when-not routing.

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

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

Annotations only declare destructiveHint=true, so the description carries most of the burden and does so well: it confirms the mutation, discloses partial-update semantics (non-passed fields are preserved), gives the underlying endpoint PUT /contacts/{id}, and states the return value. It does not say what happens if the id doesn't exist or what errors look like.

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

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

Three short sentences, zero filler, with the mutation warning and verb+resource leading. The escape-hatch hint is placed exactly where an agent would look for it.

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 partial-update tool with a nested `fields` object and no output schema, the description covers mutation semantics, the raw-field escape hatch, and the return value ('the updated contact'). Only failure/not-found behavior is unaddressed, a minor gap given the 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 every parameter including `fields` is already documented in the schema. The description's partial-update sentence adds real meaning about optional parameters, but its `fields` explanation largely restates the schema's own description. 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?

States a specific verb and resource ('update an existing contact') and front-loads the mutation nature with 'MUTATES Quaderno data'. It is trivially distinguishable from siblings like quaderno_create_contact and quaderno_get_contact 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?

Clearly frames this as a partial update ('Only the fields you pass are changed') and points to `fields` as the escape hatch for untyped attributes, which tells the agent when this tool suffices. It stops short of naming alternatives or exclusions (e.g., use quaderno_create_contact when the contact doesn't exist yet).

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