quaderno

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

Beyond the readOnlyHint annotation, the description explicitly states the operation is READ-ONLY, names the HTTP method (GET), and details the response fields including the status enum values. This gives the agent useful behavioral expectations without requiring it to infer from the schema or 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?

The description is three tight sentences with no filler. It front-loads the core purpose, then adds the safety-relevant read-only note, the API endpoint, and the return shape. 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?

Given the rich input schema and the absence of an output schema, the description compensates well by specifying the response structure and status values. It also covers the key behavioral concern (read-only) and identifies the endpoint, making it complete for a 13-parameter 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 input schema already has 100% parameter coverage with clear descriptions for all 13 parameters, so the baseline is 3. The description adds conceptual context by mapping 'customer's location' and 'product' to relevant parameters and listing response fields, but it does not add meaning beyond what the schema already provides.

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

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

The description clearly states a specific verb ('calculate') and resource ('tax rate/amount for a sale'), and identifies the inputs (customer's location and product). It is unmistakably distinct from the sibling tools, which are create/get/list operations for contacts, invoices, and items.

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

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

The description gives clear context: this tool is for computing tax on a sale based on location and product, and labels it as Quaderno's flagship endpoint. It does not explicitly name alternatives or say when not to use it, but the sibling list contains no competing tax-calculation tool, so the usage context is sufficient.

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 destructiveHint=true already signaling mutation, the description reinforces this with 'MUTATES Quaderno data,' specifies the endpoint (POST /contacts), and states that it returns the created contact. It adds useful context without contradicting 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?

The description is compact and front-loaded: purpose first, then required/optional inputs, the escape-hatch mechanism, the endpoint, and the return value. Every sentence contributes useful information with no filler.

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

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

For a mutation tool with no output schema, it covers creation, required inputs, optional attributes, endpoint, and return value. The main gap is that 'customer or vendor' is not explicitly tied to a schema field or explained via `fields`, leaving some ambiguity about how to express that contact role.

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 meaningful guidance: it tells the agent to provide 'kind plus a name' and explains that `fields` is an escape hatch for additional Quaderno attributes, listing concrete examples such as phone_1, region, and postal_code.

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 specifies a concrete verb and resource: 'create a contact,' with the added detail that the contact is a customer or vendor. This differentiates it clearly from sibling creation tools like create_invoice, create_item, and create_transaction.

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 to create a contact and outlines core inputs, but it does not explicitly say when to prefer this over update_contact, get_contact, or list_contacts. Usage is implied rather than articulated as a clear decision rule or set of 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?

The annotations only provide destructiveHint: true, while the description adds 'MUTATES Quaderno data', the HTTP endpoint, and the return value ('Returns the created invoice incl. permalink, pdf'). This meaningfully goes beyond the annotation by describing the mutation's external effect and response, without contradicting it.

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 with the core mutation signal, then moves to required inputs, optional field routing, item structure, and return behavior. The long parenthetical list makes it a little dense, but every sentence contributes useful information and there is no filler.

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

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

For a create tool with no output schema, the description covers the essential call contract: required input relationship, optional attributes, item structure, endpoint, and return value. It does not discuss error conditions or what happens if a contact_id is invalid, but it is sufficient for an agent to invoke the tool correctly in the common case.

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

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

Although schema description coverage is 100%, the description adds real value: it clarifies the either/or relationship between contact_id and a contact object passed via fields, enumerates the attributes that can go through fields, and provides an explicit line-item shape ({ description, quantity, unit_price, tax_1_name?, tax_1_rate?, discount_rate?, … }) that the schema leaves underspecified. This materially helps an agent construct valid 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?

The description names the exact action ('create an invoice') and resource ('Quaderno data', 'for a contact'), using a specific verb that separates it from sibling tools like list_invoices, create_contact, and create_transaction. It also states the API endpoint (POST /invoices), further pinning down what the tool does.

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

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

The description gives clear invocation guidance: provide contact_id (or a contact via fields) and items, and use fields for any other attribute. It does not explicitly explain when to prefer create_invoice over create_transaction or when not to use it, so it misses the strongest form of alternative routing, but the usage context is clear enough for correct selection.

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?

Beyond the destructiveHint annotation, the description explicitly says 'MUTATES Quaderno data,' which reinforces the state-changing nature, and adds useful behavior details: the HTTP method/resource is POST /items and the tool returns the created item. This is valuable context that annotations alone do not provide.

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

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

Three compact sentences with no filler. The mutation warning is front-loaded, followed by required parameters, the escape-hatch guidance, the endpoint, and the return value. 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 7-parameter tool with nested objects and no output schema, the description covers the essential calling information: required fields, the fields escape hatch, the API endpoint, and the return value. It is slightly lean on what the returned item contains, but that is not necessary to invoke the tool correctly given the schema covers parameters.

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 value by clarifying that `fields` is the mechanism for any attribute not explicitly typed (code, description, tax_class, tax_type, currency, country, stock) and by emphasizing the required parameters name + unit_cost. This goes beyond the schema's property descriptions.

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 action and resource: 'create a product/item in the catalog' and explicitly names the API endpoint (POST /items). This clearly distinguishes it from sibling create tools like create_contact and 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 gives concrete usage guidance: 'Provide name + unit_cost; use `fields` for any other attribute.' It also clarifies that extra attributes go through the fields escape hatch. It does not explicitly discuss when not to use it or mention alternatives, but the context is clear enough for a create action.

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 indicate destructiveHint=true, and the description reinforces this by starting with 'MUTATES Quaderno data'. It adds useful behavioral context: tax computation, compliant document generation, the POST /transactions endpoint, and the return type. 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?

The description is three sentences and front-loads the mutation warning before details. The long list of field names is useful despite adding length, and there is no redundant 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?

The description covers the return type, which is important since there is no output schema. However, it overstates requirements by saying to provide customer, items, and payment while the schema only requires items, and the currency-in-fields guidance is inconsistent with the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable examples for items, payment, customer, and lists many attribute names that can go through fields. However, it tells users to put currency into fields even though currency is already a top-level typed parameter, which is mildly misleading.

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 clearly states the action: record a sale or refund transaction in Quaderno. It also adds distinct context by explaining that Quaderno computes tax and produces a compliant document, which sets it apart from generic CRUD tools, though it does not explicitly differentiate from sibling 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 usage for sale/refund transactions and tells the agent what to provide (customer, items, payment). However, it does not explicitly say when to prefer this over create_invoice or other siblings, and the mention that it returns an invoice/credit-note object could blur the line with create_invoice.

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 provide readOnlyHint=true, so the description's safety impact is low. It adds the HTTP GET method and endpoint path, but does not disclose behavior such as 404 handling, return shape, or auth requirements. That is acceptable but not rich for a fetch tool.

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

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

Two short sentences, no filler. The core action is front-loaded and the API endpoint reference is useful context that 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 one-parameter read-only fetch tool, the description plus schema fully covers what an agent needs to call it correctly. The endpoint is explicit, and no response details are strictly necessary.

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

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

Schema description coverage is 100% and the only parameter 'id' is documented as 'The resource id.' The description merely restates that the contact is fetched by id, adding no extra semantic meaning 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 uses a specific verb ('Fetch') with a specific resource ('a single contact by id'), which clearly distinguishes it from list_contacts, create_contact, and update_contact. It also names the exact API endpoint.

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

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

The phrase 'a single contact by id' gives clear context: use this when you already know the contact id and need exactly one contact. It does not explicitly mention alternatives or when-not-to-use, so it misses the top score.

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

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

The annotations already declare `readOnlyHint: true`, so the safe read behavior is covered. The description adds the HTTP GET endpoint but no additional behavioral context such as error cases or response format. It is consistent with annotations and does not contradict them.

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, front-loaded sentences with no filler. The first sentence states the operation; the second provides the exact API endpoint. Every word 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 simple one-parameter read operation, the combination of description, schema, and annotations is complete. The agent knows the resource, the lookup key, and the read-only nature. No output schema exists, but the return value is implied by the resource name and a simple GET operation.

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%: the `id` parameter already has a description ('The resource id.'). The tool description only repeats 'by id' and adds no new meaning, so the schema carries the 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 a specific verb ('Fetch'), a specific resource ('a single credit note'), and the lookup criterion ('by id'). This clearly distinguishes it from `list_credit_notes` and the other `get_*` siblings, so an agent can identify what this tool does without opening schemas.

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 clearly implies usage when the agent has a specific credit note id and needs one record. However, it does not explicitly contrast with `list_credit_notes` or mention when not to use it, so it stops short of a 5.

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

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

The annotations already declare readOnlyHint=true, and the description aligns with that by saying 'Fetch' and specifying GET /expenses/{id}. The endpoint adds mild operational context, but no extra behavior such as error handling or response shape is disclosed.

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 crisp sentences with no fluff. The core action is front-loaded, and the API endpoint is a helpful, non-redundant addition.

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, the description covers the essential selection and invocation details. However, there is no mention of potential error responses or what the returned expense object contains, which would be more important given there is no output schema.

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

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

Schema coverage is 100% and the id parameter is described, but the description adds the useful fact that the id is used as a path parameter in GET /expenses/{id}. This goes slightly beyond the schema's generic 'resource id' wording.

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

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

The description uses a specific verb and resource ('Fetch a single expense by id') and clearly distinguishes this from list-oriented siblings like list_expenses. The API endpoint reinforces the exact operation.

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

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

The description implies usage when a single expense ID is known, but it does not explicitly contrast with list_expenses or other alternatives. There is no 'use this instead of X when...' guidance, leaving sibling differentiation to inference.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces a safe GET operation with the Quaderno API endpoint. It adds useful behavioral context by disclosing the full response scope (items, taxes, payments, permalink, pdf), which goes beyond the minimal read-only signal. No contradiction exists.

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

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

The description is a single sentence that front-loads the core purpose, then efficiently adds response-content detail and an API reference. Every word earns its place with no redundancy.

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

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

For a simple single-invoice fetch with one required parameter and readOnlyHint=true, the description provides all necessary context: the target resource, the identifier, and the expected response contents. No output schema exists, so the explicit mention of included fields is especially valuable.

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

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

Schema description coverage is 100%, so the single 'id' parameter is already documented as 'The resource id.' The description confirms retrieval by id but adds little semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Fetch'), a clear resource ('a single invoice by id'), and adds detail about what the full object includes (items, taxes, payments, permalink, pdf). This clearly distinguishes it from sibling list operations like list_invoices and other single-resource getters like get_credit_note.

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

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

The phrase 'a single invoice by id' clearly communicates when this tool is appropriate: retrieving one specific invoice rather than listing invoices. It does not explicitly mention alternatives or exclusion conditions, but the context is clear enough for an agent to select it correctly among related tools.

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

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

The readOnlyHint annotation already communicates that this is a safe read operation. The description adds the HTTP GET method and endpoint, which reinforces that behavior but does not disclose additional traits such as error semantics, 404 behavior, or response format. 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?

The description is a single sentence that front-loads the core purpose and then gives a useful API endpoint reference. There is no filler, repetition, or extraneous 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 simple single-resource fetch tool with one required parameter and a read-only annotation, the description is nearly complete. The main gap is the absence of an output schema or a brief note on the return shape and possible errors, but the expected behavior is still clear enough for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the id parameter is already documented in the input schema. The description says 'by id' and gives the URL path with {id}, confirming that id is the product/item identifier, but it adds no further semantic detail beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Fetch a single product/item by id.' This clearly names the action and object, and the endpoint 'GET /items/{id}' further pins down the operation. It is easily distinguishable from siblings like list_items (listing many) and create_item (creating a new one).

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 intended use case: call this when you have an id and want exactly one item. However, it does not explicitly mention when not to use it or suggest alternatives like list_items for searching or retrieving multiple records, so the routing guidance is left mostly to inference.

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

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

Annotations already carry readOnlyHint=true, so the description does not need to restate read-only safety. The GET /receipts/{id} endpoint reinforces the HTTP method but adds no behavioral detail beyond the annotation, such as error behavior or response format.

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-load the action and scope, and the endpoint reference is useful context. Every word earns its place; there is no fluff or restatement of the schema.

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

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

For a one-parameter, read-only retrieval tool with no output schema, the description plus the input schema is sufficient. An agent knows the resource, the identifier, the HTTP endpoint, and the safe/read-only nature.

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 one parameter is already documented as 'The resource id.' The description's 'by id' repeats this without adding validation rules, format, or source guidance, so it meets but does not exceed the baseline.

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

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

The description uses a specific verb ('Fetch'), a single resource ('a single receipt'), and the selection key ('by id'). This clearly distinguishes it from list_receipts and the other get_* siblings that target different resources.

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

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

'Fetch a single receipt by id' establishes the clear condition for use: when an agent has a receipt ID and needs exactly one receipt. It doesn't explicitly contrast with list_receipts or other alternatives, but the singular scope gives clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, and the description adds meaningful behavioral context: the exact endpoint, newest-first ordering, the shape of returned contact objects, and the pagination wrapper. This goes beyond the structured annotation without contradicting it.

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 defines purpose and ordering, the second gives endpoint and output shape. Every clause adds value, and the most important 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?

For a read-only list operation with no output schema, the description sufficiently explains what is returned, the pagination envelope, and the ordering. Combined with fully described parameters and readOnlyHint, an agent has enough information to call 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 the schema fully documents q, page, per_page, and created_before. The description adds context about pagination and response wrapping, but it does not need to repeat parameter-level details; the baseline of 3 is appropriate.

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

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

The description states a clear verb and resource: 'List contacts', plus clarifies the scope as customers/vendors and the ordering as newest first. This distinguishes it from sibling tools like get_contact, create_contact, and update_contact without ambiguity.

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 this is the tool for enumerating/searching contacts, and the annotation readOnlyHint=true clarifies it is a safe read operation. However, it does not explicitly state when to prefer list_contacts over get_contact or mention any exclusions, leaving some inference to the agent.

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

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

The annotations already declare readOnlyHint=true, and the description adds useful behavioral context beyond that: the exact API endpoint, the newest-first ordering, and the pagination wrapper shape. It does not cover rate limits, authentication, or the internal structure of the returned credit-note items, but for a read-only list operation this is reasonably 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?

The description is three short clauses, each serving a clear purpose: identifying the resource, giving the API endpoint, and describing the response envelope. The main verb and object are front-loaded, and there is no redundant or filler 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 read-only list operation with six fully documented optional parameters and no output schema, the description gives the essential invocation context: endpoint, default ordering, and pagination format. It does not enumerate the fields inside the returned credit-note objects, but that is a minor gap given that the tool's purpose is to list known entities and the schema fully documents the request parameters.

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 input schema has 100% description coverage, documenting all six parameters including q, date, contact, pagination cursors, and per_page. The description adds no parameter-level information beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'credit notes,' clarifies that they are refund documents, and specifies the default ordering (newest first). It is distinct from sibling tools like list_invoices and get_credit_note by naming the exact resource and scope.

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 tool's purpose is clear enough that an agent can infer when to use it, but the description gives no explicit guidance about when to prefer it over alternatives such as get_credit_note for single records or list_invoices for invoices. It also does not mention any exclusions or conditions that would route the agent to a different tool.

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

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

Annotations already mark this as readOnly=true, and the description adds behavioral detail beyond that: it specifies the sort order ('newest first'), the exact HTTP endpoint, and the response wrapper ('{ data,pagination } when more pages exist'). This is useful context for understanding how the tool behaves at runtime without contradicting the read-only hint.

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

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

The description is extremely concise, with three short sentences that front-load the core purpose and then add the API endpoint and response wrapper. Every clause adds information and no filler is present. The structure makes it easy to scan quickly.

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 no output schema and six parameters, the description covers the key behavior: entity, ordering, endpoint, and response shape. It does not describe the individual fields of an expense or go into pagination mechanics, but those are largely covered by the schema's parameter descriptions. The response wrapper is a helpful addition that compensates for the absent output schema.

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

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

The input schema covers 100% of the parameters with descriptions, so the description does not need to explain them. The description does not add any parameter-specific meaning beyond the schema, which is acceptable given the high schema coverage. Baseline of 3 is appropriate.

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

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

The description clearly states a specific action and resource: 'List expenses (bills you received), newest first.' It also provides the API endpoint (GET /expenses), eliminating ambiguity about what the tool operates on. The parenthetical distinguishes expenses from related siblings like list_invoices or list_receipts.

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 '(bills you received)' gives clear context that this tool is for incoming bills, implying a distinction from invoice or receipt listing tools. It also communicates ordering behavior ('newest first') and the pagination wrapper, which helps an agent know when to use pagination parameters. However, it does not explicitly name alternative tools or state when not to use this one, so it stops short of a 5.

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

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

The readOnlyHint annotation already establishes safety, but the description adds meaningful behavioral detail beyond that: the newest-first ordering, the exact API path, the pagination envelope ({ data, pagination } when more pages exist), and the full set of returned fields. This transparency is strong given the simple read-only nature of the tool.

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

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

Two sentences front-load the core purpose and ordering, then deliver the endpoint and return format without filler. The field enumeration is dense but directly useful since there is no output schema.

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

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

With no output schema, the description fully specifies what the tool returns: the invoice object fields and the pagination wrapper. Combined with the schema's exhaustive parameter descriptions and the readOnlyHint annotation, an agent has everything needed to invoke the tool correctly and interpret its results.

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

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

Schema description coverage is 100%, and every one of the seven parameters already has a clear, specific description with formats, enums, defaults, and pagination semantics. The phrase 'optional filters' in the tool description adds no parameter-specific meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb, resource, and ordering: 'List invoices, newest first, with optional filters.' It also names the underlying API endpoint (GET /invoices) and enumerates the returned invoice object fields, making the tool's scope unambiguous among the many list_* siblings.

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

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

The description clearly conveys what the tool does and the context for using it (list invoices with optional filters, newest first). However, it does not explicitly contrast this with alternatives like get_invoice for single-record retrieval or create_invoice for writes, so it stops short of full exclusionary guidance.

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

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

Annotations already provide readOnlyHint=true, so the safe read-only nature is known. The description adds valuable behavioral context beyond that: newest-first ordering, the endpoint, the returned item fields, and the pagination wrapper shape when multiple pages exist. No contradictions 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 sentences with no filler. The core action and resource are front-loaded, and the API endpoint, ordering, return fields, and pagination behavior each earn their place. The description is compact yet information-dense.

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 operation with no output schema, the description covers the essential return shape and pagination behavior, which is the main thing an agent needs beyond the schema. It could be slightly more explicit about the exact response format when no pagination is needed, but the overall context is sufficiently 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 every parameter (page, per_page, created_before) is already documented in the schema. The description adds no additional parameter-level meaning, but it does reinforce the pagination concept by mentioning the { data, pagination } wrapper, which supports but does not extend 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 states a specific verb ('List'), a specific resource ('products/items in the catalog'), and ordering ('newest first'). It also names the exact API endpoint (GET /items), which distinguishes it clearly from sibling tools like get_item, create_item, and list_contacts.

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 clearly implies collection retrieval from the catalog and provides pagination context, so an agent can tell when listing is appropriate. It does not explicitly name alternatives or state when not to use this tool, but the purpose is unambiguous enough that no exclusion is truly necessary.

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

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

The annotations already declare readOnlyHint=true, and the description's verb 'List' reinforces the read-only nature. It adds the API endpoint 'GET /jurisdictions' and specifies the data elements returned, which is useful given the absence of an output schema. No contradictory behavioral claims are made.

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

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

The description is two short sentences with no filler. The main purpose and return fields are front-loaded, and the API endpoint is presented as a separate, compact detail that does not distract from the core description.

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

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

For a no-parameter, read-only list operation, the description is complete: it identifies the resource, its scope, the returned fields, and the HTTP endpoint. Since there is no output schema, the explicit field list compensates; no critical information 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?

The tool has zero parameters, so there is nothing to document; the schema coverage is trivially 100%. The description still adds value by explaining the output fields rather than parameters, which is the relevant semantic content 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 starts with a specific verb 'List', names the resource 'tax jurisdictions', enumerates the returned fields (id, name, country, region), and defines the scope 'where the account is registered to collect tax'. This clearly differentiates it from sibling list_* tools such as list_tax_codes.

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 states a clear context for use: when the account's registered tax jurisdictions are needed. It does not explicitly contrast with alternatives like list_tax_codes, but the scope statement gives enough guidance to select this tool over generic list operations.

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 mark readOnlyHint=true, and the description adds meaningful behavioral detail: the tool wraps results as { data, pagination } when more pages exist, and it lists receipts newest first. This goes beyond the schema and annotations, though it does not enumerate rate limits or authentication expectations.

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

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

Three short sentences with no filler: the core behavior, the API endpoint, and the response wrapper are each stated once. Every sentence earns its place and the most important info comes first.

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 listing tool with 100% schema coverage, the description covers ordering, pagination wrapper, and the endpoint. The only notable omission is that it does not explain what each receipt object contains, but with no output schema and six optional params, that is a minor gap; an agent can still decide 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 description coverage is 100% and every parameter has a clear description, including the legacy pagination note on 'page'. The tool description itself doesn't add parameter meaning beyond schema, but it does mention response wrapping that helps interpret pagination parameters. 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 ('List receipts'), adds ordering behavior ('newest first'), identifies the underlying API endpoint (GET /receipts), and clarifies the wrapped response shape. This clearly distinguishes it from siblings like get_receipt (single resource) and list_invoices (different resource).

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

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

The description implicitly indicates this is for listing receipts and mentions legacy vs. preferred pagination via the page parameter schema ('prefer created_before'), giving the agent clear context for how to paginate. It does not explicitly exclude alternatives or state when-not-to-use, but the API endpoint and response wrapper give enough context.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces the read-only nature with 'Quaderno API: GET /tax_codes.' It also adds the returned field list, which is useful behavioral context given there is no output schema.

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

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

One compact sentence plus an API endpoint reference: no filler or redundancy. The core purpose and usage context are front-loaded, and the technical detail is appended cleanly.

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-only list operation, the description provides the resource, returned fields, intended use, and API endpoint. It is complete enough for an agent to select and invoke the tool correctly without additional documentation.

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 has zero parameters and schema coverage is 100%, so there is no parameter ambiguity to resolve. The description adds purpose context, but parameters require no additional semantic explanation.

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') with a clear resource ('product tax codes Quaderno supports') and enumerates the returned fields (id, name, description). It also clarifies the resource's role as the tax_code for products/tax calculations, which distinguishes it from sibling tools like list_jurisdictions and calculate_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?

The description gives clear context: the codes are 'used as the tax_code on products / tax calculations,' so an agent knows when fetching them is relevant. It does not explicitly name alternatives or when-not conditions, but the practical context is strong enough to guide selection.

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 marks this as a read operation, and the description reinforces that by saying 'List' rather than implying mutation. It adds useful behavioral context by naming the returned fields (id, url, events) and the API endpoint, which is more than the annotation provides.

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

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

The description is two short sentences with no filler. The verb, resource, and scope are front-loaded, and the API endpoint is clearly referenced without unnecessary 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 parameterless, read-only list operation, the description covers the key facts: what is listed, the returned fields, and the API endpoint. Pagination or ordering details are not essential here, and the readOnly annotation covers the safety profile.

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 has zero parameters and the schema coverage is 100%, so there are no parameter details for the description to add. It still provides helpful context about the API endpoint and the fields returned, which compensates for the absence of an output 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 uses a specific verb ('List'), names the exact resource ('webhooks'), and scopes it to the account's configured webhooks with returned fields (id, url, events). This makes it immediately distinguishable from sibling list_* tools that target different resources.

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

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

The intended use is clear: call this when you need to see the account's configured webhooks. It does not explicitly contrast with sibling list tools, but the resource-specific wording makes the correct selection obvious and no exclusion conditions are needed.

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=true already declaring a safe read, the description adds that the call returns account/authentication status and uses GET /ping. It does not describe error behavior for an invalid key, but for a zero-parameter connectivity check that is a minor omission.

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 cover purpose, return value, and endpoint with no filler. The main purpose is front-loaded and 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 no-parameter, read-only ping tool, the description supplies purpose, return value, and endpoint. With no output schema, 'returns account/authentication status' is enough for an agent to invoke and interpret the call.

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 input schema has no properties, and schema description coverage is 100%, so there are no parameters requiring clarification. Baseline for zero-parameter tools is 4, and no further parameter burden falls on the description.

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 (verify) and resource (API key/connection to Quaderno), and pinpoints the exact endpoint GET /ping. This clearly distinguishes ping from the sibling list_*/get_* tools and the generic quaderno_request.

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 a clear usage context: use this tool to verify that the API key and connection work. It does not explicitly discuss when not to use it or name an alternative, but the tool's narrow purpose makes the guidance sufficient.

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

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

The readOnlyHint annotation already establishes the read-only nature; the description adds that only GET is allowed and that paths are taken after /api. It does not cover response format, error behavior, or rate limits, but the annotation lowers the burden and there is no contradiction.

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

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

The description is three short sentences with no filler. Purpose, restriction, and path convention are all front-loaded and immediately actionable.

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 raw GET tool with complete parameter coverage and a readOnlyHint annotation, the description is sufficient to guide invocation. The only minor gap is not explicitly describing the response shape, but no output schema exists and the 'raw read request' framing largely implies it.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the path format with examples and the GET {path} pattern, but it does not add substantial meaning beyond the schema for the query parameter.

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 operation: GET any Quaderno API path not wrapped by a dedicated tool. It clearly identifies itself as an escape hatch and distinguishes itself from the many sibling tools by scoping to paths without a dedicated wrapper.

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 explicitly says when to use this tool: when a path is 'not wrapped by a dedicated tool.' It also labels itself a 'power-user escape hatch,' implying dedicated siblings should be preferred for covered paths, and reinforces that only GET is allowed.

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 says 'MUTATES,' which aligns with the destructiveHint annotation. It adds valuable behavior beyond the annotation: only passed fields are changed (partial update semantics), the fields parameter acts as a merge/escape hatch, and the API endpoint is PUT /contacts/{id}, and it returns the updated contact. This is strong behavioral context for a mutating 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?

Three tight sentences, front-loaded with the mutating intent and primary operation. Every sentence earns its place: purpose, partial-update semantics, escape-hatch guidance, API mapping, and return value. No filler.

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

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

For a mutation tool with no output schema, the description covers the key missing pieces: endpoint, partial update behavior, the generic fields escape hatch, and the return value. It does not detail authorization or error cases, but these are not strongly required given the annotations and simple schema.

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

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

The schema covers 100% of parameters, so the baseline is 3. The description adds meaning beyond the schema by clarifying that only provided fields are changed and that 'fields' is the escape hatch for any untyped attribute. This helps an agent understand the update merge behavior and when to use the fields object.

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 ('update'), a clear resource ('an existing contact'), and the exact API operation (PUT /contacts/{id}). This unambiguously differentiates it from siblings like create_contact, get_contact, and list_contacts.

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 'update an existing contact' clearly implies this is for modifying already-created contacts rather than creating new ones. It does not explicitly name create_contact as the alternative, but the context is clear enough for an agent to select this tool correctly.

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