Collmex MCP by usefulapi

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

Adds substantial context beyond the annotations: no address number is supplied so Collmex assigns one, existing addresses are never overwritten, repeated calls create duplicates, and nothing is sent to the person (no mailings triggered). It also discloses the return value (new address number) despite there being 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?

Front-loads 'WRITE:' and the core action, then layers scope, duplicate risk, side effects, and validation in a tight paragraph. Every sentence carries distinct information with no repetition of schema or annotation content.

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

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

For a 16-parameter write tool with no output schema, the description covers the mutation model, idempotency behavior, minimum-viable input, side effects, and return value. Nothing an agent needs to invoke it safely 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 field-level meaning is already covered, but the description adds a genuine cross-parameter constraint absent from the schema (which declares zero required fields): at least a company or a last name must be given. That is real value beyond the structured data.

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 (create) and resource (Collmex address book entry) and pins down the exact record type and semantics (CMXADR, address type 3). It also distinguishes itself from the read path by naming collmex_list_addresses, so an agent can route without opening the schema.

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

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

Gives an explicit pre-condition workflow: check collmex_list_addresses first to avoid duplicates, and warns that every call creates another entry. The one gap is that it never contrasts with the sibling collmex_create_customer, which an agent could plausibly confuse for a person/company record.

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

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

Adds substantial context beyond annotations: no customer number means Collmex assigns the next number, existing customers are never overwritten, each call creates a new record, no message is sent to the customer, and the new customer number is returned. These details are consistent with the non-destructive, non-idempotent 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?

Four short sentences, front-loaded with the write/create intent, then key constraints, duplicate warning, and return value. Every sentence 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?

Covers the write nature, required business fields, duplicate-avoidance workflow, assignment behavior, and return value. Although no output schema exists, the description states the return value directly, leaving no critical gap 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 coverage is 100%, so the schema already documents all 18 parameters. The description adds a meaningful business rule not encoded in the schema's required fields: at least a company or last name must be supplied. It also clarifies that no customer number is passed, but most parameter meaning remains schema-driven.

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 (create), resource (customer), scope (NEW, record CMXKND), and explicitly distinguishes it from updating an existing customer. An agent can immediately tell this is a creation tool, not a read or update tool.

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

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

Explicitly instructs checking collmex_list_customers first to avoid duplicates, warns that each call creates another customer, and states the minimum business requirement (company or last name). This gives clear when-to-use and duplicate-avoidance guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuine behavioral nuance beyond structured data: supplying a customer or vendor causes the date filter to be ignored, which an agent would otherwise get wrong. Return format is partially described (account number, name, balance), but pagination behavior is left to the schema.

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

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

One front-loaded sentence covers what the tool returns and every filter, with the account-group legend parenthetically embedded. No filler, and the most important information (record, fiscal year, returned fields) 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?

With 10 parameters, 100% schema coverage, and annotations carrying the safety profile, the description supplies the missing semantic layer (account-group legend, date-override rule) and names the returned columns. No output schema exists, but the returned fields are listed, so nothing critical is absent.

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

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

Schema coverage is 100%, establishing a baseline of 3, but the description adds real meaning the schema lacks: it decodes the account_group values (1 other, 2 fixed assets, 3 bank/cash, … 14 non-deductible expenses) where the schema only says '1-14'. It also restates the customer/vendor-overrides-date interaction that affects parameter precedence.

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 ('Account balances from the Collmex accounting (record ACCBAL_GET) for a fiscal year') and enumerates the returned fields (account number, name, balance). The resource is clearly distinct from siblings like collmex_list_invoices or collmex_list_open_items, though it never explicitly contrasts with them.

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?

Enumerates the available filters (account, account group, cost centre, date, customer/vendor), which implies how to narrow results, and notes that customer/vendor cause the date to be ignored. However it never says when this tool is preferable to siblings such as collmex_list_accounting_documents or collmex_list_open_items, so routing still requires 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's job is to add semantics — and it does, by explaining the subtraction formula behind the number and warning that service products return NULL. That NULL caveat is exactly the kind of result-shape surprise an agent needs before interpreting data; only auth/rate-limit context is absent.

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

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

Two sentences, zero filler: the metric definition leads, the edge cases (NULL for service products, empty product_no) follow. Nothing is repeated from the title or schema.

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

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

With no output schema, the description usefully compensates by explaining what the returned stock figure means and how service products appear. For a small, all-optional-parameter read tool this is nearly sufficient; only ordering/pagination expectations for the result set are unaddressed.

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

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

Schema coverage is 100%, so limit, offset, company_no and product_no are all documented in the schema itself. The description only adds the empty-product_no-means-all clarification, which is helpful but marginal against an already complete schema — baseline 3 applies.

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

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

States a specific verb and resource ('Currently available stock per product') and pins down the metric precisely: on-hand stock of available stock types minus demand due today or earlier. That definition separates it from collmex_list_products, which would otherwise look like the obvious sibling for product queries.

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?

'Leave product_no empty for every product' gives usage guidance for the all-products case, which is the main calling decision. However, it never says when to prefer this over collmex_list_products or how it relates to other stock views, so the choice between siblings is left to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds genuinely new behaviour: row-per-position granularity, the 0/1 debit-credit encoding, and that cancellations are filtered out by default. 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?

Three tight sentences; the record identifier and row granularity come first, then filters, then the exclusion rule. The field enumeration is a bit list-like but each item conveys the shape of the result for a tool with 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 14 optional parameters and no output schema, the description compensates well by naming the returned fields, the debit-credit encoding, and the default cancellation filter. An agent has enough to call this correctly and interpret the reply.

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

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

Schema description coverage is 100%, so every parameter is already documented with ranges, patterns and defaults. The description only restates the filter set in prose, adding no format or syntax detail beyond the schema. Baseline 3 applies.

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

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

States the specific resource (accounting postings, record ACCDOC_GET) and the exact granularity ('one row per posting position'), plus enumerates returned fields. An agent can distinguish this from collmex_get_account_balances or collmex_list_invoices without opening a schema.

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

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

Gives concrete filtering axes (fiscal year, account, cost centre, customer, vendor, invoice, document date range) and a default-behaviour rule ('Cancelled postings are excluded unless asked for'). It lacks explicit routing against siblings such as get_account_balances, which is why it falls short of 5.

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

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

Annotations already declare readOnlyHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond that — that entries link to the invoice that billed them and how billing status drives filtering — but says nothing about pagination defaults, volume, or result ordering that would matter when pulling large activity sets.

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, both load-bearing: the first establishes the record type and returned fields, the second enumerates filters. It is dense but front-loaded and free of filler, though the parenthetical '(needs company)' is slightly terse.

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

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

With no output schema, the description usefully compensates by listing the fields each activity carries (project, employee, times, breaks, description, billing invoice). Combined with a fully documented schema and read-only annotations, an agent has enough to call it correctly; only pagination and result-ordering expectations are unaddressed.

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

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

Schema description coverage is 100%, so all nine parameters are already documented in the schema, including the employee_no/company_no dependency and the billable_only customer-project nuance. The description only restates the filter set at a coarser level, adding no syntax or edge-case detail beyond the schema.

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

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

The description names the resource precisely (recorded time-tracking activities, record ACTIVITIES_GET) and enumerates the returned fields, so an agent knows this is a read of time entries rather than projects or invoices. It stops short of explicitly saying 'list' or contrasting with sibling list tools such as collmex_list_projects.

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

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

Usage is only implied through the filter list ('Filter by project, employee (needs company), date range, only not-yet-billed...'), which hints at retrieval scenarios but never states when to prefer this tool over collmex_list_projects or collmex_list_invoices. The note that employee filtering requires a company is a real prerequisite, but no exclusions or alternatives are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety and reach are covered externally. The description adds that contact persons require an opt-in and that the underlying Collmex record is ADDRESS_GET, but says nothing about result volume, pagination behavior, or what happens with large address books.

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, no filler. The trailing address_type enumeration is somewhat redundant with the schema but is short and directly usable.

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 11 optional parameters and no output schema, the description should say more about the returned record shape or pagination expectations. Parameter behavior is well covered by the schema, but the return-side and result-size picture is absent.

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

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

Schema description coverage is 100%, so all 11 parameters including the address_type mapping are already documented. The description restates the address_type codes verbatim rather than adding interpretation (e.g. how text search interacts with address_no or address_group), so it earns only 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?

States a specific verb and resource ('Search the Collmex address book, record ADDRESS_GET') and clarifies that customers, vendors and address-book entries come back 'in one list', which implicitly distinguishes it from the narrower collmex_list_customers / collmex_list_vendors siblings. It stops short of naming those siblings outright.

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 tool aggregates all three address categories and can include contacts, so an agent can infer it should be preferred when a combined view is needed. There is no explicit statement of when to use this versus collmex_list_customers, collmex_list_vendors, or collmex_create_address's counterpart lookups.

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, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds non-obvious behavior beyond that: the default filtering-out of inactive records and the set of field groups returned, which an agent cannot infer from 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?

Two sentences, front-loaded with the verb and record type, then filters, then returns, then the one non-obvious exclusion rule. No filler or repetition of schema details.

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 nine optional parameters and no output schema, the description does the important work: it scopes the search dimensions and describes the returned fields. It omits pagination behavior and default limit, which live in the schema, leaving a small gap for a search endpoint.

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 still adds meaning by expanding what 'text' searches ('name, city, e-mail ...') and by naming the returned field groups (address, bank, VAT id, payment terms), connecting filters to outcomes rather than restating the schema.

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

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

States a specific verb and resource ('Search Collmex customers') and anchors it to the underlying record CUSTOMER_GET, then enumerates the filter dimensions (customer number, free text, postal code, country). It never explicitly says how it differs from sibling list_addresses or list_vendors, so an agent must infer the customer-vs-address split.

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 last sentence gives a real usage rule: inactive customers are excluded unless include_inactive is set. However, there is no guidance on when to call this versus collmex_list_addresses or collmex_create_customer, and no mention of prerequisites or pagination workflow.

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 readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real value beyond that: it states no PDF/XML export, that results include both header and position lines, and it decodes the status codes (0 new, 10 to be posted, 20 open, 30 dunned, 40 settled, 100 deleted), which is behavioral detail absent from 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?

Three sentences, each earning its place: the first covers scope and filters, the second the returned shape, the third the read-only/no-export boundary. Front-loaded with the identifying verb and resource.

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 present, the description compensates by describing the return shape (header with address, dates, payment terms, status code; positions with quantities, prices, values) and status code semantics. For a 10-parameter filter tool with fully documented schema, nothing material 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 adds meaning by mapping its filter list onto the parameters and by explaining what the returned status code values mean for interpretation. Minor deduction because it does not itself clarify the limit/offset pagination caveat that lives only in the schema.

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

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

States a specific verb (Search) plus the exact resource (Collmex customer invoices and credit notes, record INVOICE_GET) and enumerates the filterable dimensions. This clearly separates it from siblings like collmex_list_open_items and collmex_list_sales_orders without needing to open 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?

The filter enumeration ('by invoice number, customer, invoice date range, customer order or product') plus 'Reads only; no PDF/XML export' gives a clear sense of when this tool applies and where its boundary lies. It does not explicitly name an alternative tool for document export, so it stops short of full when-not 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 cover safety (readOnly, non-destructive, openWorld), so the description's job is lighter. It adds useful behavior: the returned fields (invoice no, document/due date, days overdue, dunning level, amount, paid, outstanding) and the optional as-of key date, which tells the agent what results look like without an 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?

Two dense sentences with the core purpose front-loaded, followed by the field list and the optional key-date note. No filler.

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

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

With no output schema, the description helpfully enumerates the returned fields and clarifies the customer/vendor split and default. Pagination is left to the schema, which is fine given its 100% coverage; a note on when to use this vs list_invoices 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 parameters are already documented with defaults and constraints. The description only restates 'customers ... default' and 'optionally as of a key date,' adding no syntax or semantics beyond the schema—baseline 3.

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

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

States a specific verb and resource ('Open items (unpaid invoices)') and names the underlying record type (OPEN_ITEMS_GET), and clarifies the scope as receivables (default) or payables. It also disambiguates from collmex_list_invoices by defining the items as *unpaid* 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?

Gives implied usage via 'for customers (receivables, default) or vendors (payables)' and 'Optionally as of a key date,' but never says when to prefer this over collmex_list_invoices or collmex_list_accounting_documents, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the underlying API record (TERMS_OF_PAYMENT_GET) and the field set returned, but says nothing about volume, pagination behaviour, or response shape — which the schema partially covers for paging.

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

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

Two short sentences with no filler; the field list is front-loaded and the semantic note about 'number' is genuinely useful. Slightly compressed into a colon-list rather than a clean statement, but nothing is wasted.

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

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

With no output schema, the description carries the burden of describing return values and does so by naming the four fields. For a simple two-parameter read, nothing critical is missing, though the response envelope and whether results are paged are left to the schema.

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

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

Schema description coverage is 100%, with limit and offset fully documented including the next_offset pattern, so the baseline is 3. The description adds no parameter meaning 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?

Identifies the resource precisely (Collmex payment terms, TERMS_OF_PAYMENT_GET) and enumerates the returned fields, so the agent knows exactly what a call yields. The verb comes from the title/name rather than the description, and no sibling overlap exists to disambiguate, so a 4 rather than a 5.

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

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

Usage is implied rather than stated: the note that 'the number is what customers, vendors and invoices refer to as payment_terms' hints this is the lookup for resolving that field, but there is no explicit when-to-use, no prerequisites, and no named alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real context beyond them: the Collmex record type used and the set of returned fields (description, unit, tax class, sales price, purchase data, stock settings). Pagination behavior is left to the schema rather than the description, which keeps this just short of a 5.

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

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

Two dense sentences: the first front-loads purpose and filter options, the second covers the return payload. No filler, no repetition of schema constraints.

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, all-optional read tool with no output schema, the description covers what can be filtered and what comes back. Minor gaps: no statement that an unfiltered call returns all products up to the limit, and no note that offset/limit drive pagination.

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 meaning the schema lacks: free text is stated to match number, description, remark, GTIN and manufacturer, and price_group is framed as selecting which price is returned. That is genuine semantic enrichment over 'Free-text search (max 80 characters)'.

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

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

States a specific verb and resource ('Search Collmex products'), names the underlying Collmex record (PRODUCT_GET), and enumerates the filter dimensions. The resource is unique among the siblings (all list_* tools target other entities), so an agent can route to it 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 enumeration of filter dimensions ('by product number, product group, free text ... or price group') implies how to narrow a search, but there is no explicit when-to-use/when-not guidance, no mention that all parameters are optional (i.e., calling with no filters lists everything), and no named alternative 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. Because there is no output schema, the description's enumeration of returned fields (budget, activity value, completion state, per-project rate number/description/product/hourly-or-daily rate) supplies context the agent could not otherwise obtain. It stops short of describing pagination flow or failure behavior, but the schema covers the paging parameters.

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

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

A single dense sentence with no filler, front-loaded on the resource and immediately followed by the returned fields. Minor deduction for internal jargon ('record PROJECT_GET') that consumes early attention without helping selection.

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

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

For a read-only, zero-required-parameter list tool with full schema coverage and no output schema, the description covers what the agent needs: the resource and the shape of the results. The remaining gap is routing guidance (when this beats list_activities/list_customers) and confirmation that filters compose, neither of which is stated.

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

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

Schema description coverage is 100%, with limit/offset/status/company_no/project_no/customer_no all documented in the schema, so parameter semantics are fully carried there. The description only implicitly echoes a few of them ('customer', 'completion state') and adds no format or interaction detail. Baseline 3 applies 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 names the resource (Collmex projects, PROJECT_GET record) and enumerates the payload contents — customer, budget, activity value, completion state, rates — which lets an agent distinguish it from siblings like list_activities or list_customers. It is a noun phrase rather than a verb+resource statement, but the title ('List projects') and the field enumeration make the operation 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 statement of when to use this tool, when not to, or which sibling to prefer for an adjacent need (e.g. activities or customers). The filtering options (status, project_no, customer_no) exist in the schema but the description never suggests the common retrieval scenarios or that all filters are optional.

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 this as a safe read operation, but the description adds meaningful behavioral context: the order status code map (0 new through 1000 cancelled), the distinction between header and positions, and the explicit note that no PDF export is performed. These are details an agent would not get from 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?

The description is front-loaded with the core action and filters, then adds the return shape and status codes in a compact form. The status enumeration is dense but useful; no sentence is merely filler, though the response-shape sentence could be tightened slightly.

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

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

With no output schema, the description does the important work of explaining that results include a header (address, dates, payment terms, status) and positions. Combined with annotations covering the safety profile and the schema covering pagination parameters, this is nearly complete, though it could briefly mention that empty results are normal or how status codes relate to filtering.

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 already 100%, so every parameter is documented in the schema. The description restates the filter categories in prose (order number, customer, date range, customer's purchase order number) but does not add syntax, edge-case behavior, or filtering rules 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 gives a specific verb and resource ('Search Collmex customer orders') and identifies the underlying record type ('SALES_ORDER_GET'), which clearly separates it from siblings such as collmex_list_invoices and collmex_list_products. It also names the exact filter dimensions, so the agent knows precisely what is being searched.

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 'customer orders' and by the explicit 'Reads only; no PDF export' limitation, but the description never names a sibling alternative or says when to choose this tool over collmex_list_invoices or collmex_list_open_items. It gives enough context to understand the tool's domain, but not explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value by disclosing what a result contains (address, contact, bank, VAT id, payment terms, expense account) even though no output schema exists. Pagination behavior and default result size are only in the schema, not the description.

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

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

Two dense sentences, front-loaded with the action and record type, then the filter axes, then return contents. Nothing is redundant or padding.

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

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

With no output schema, the return-field summary is exactly what an agent needs to decide whether this tool answers its question. The remaining gaps (paging, default limit, empty-result behavior) are adequately covered by the 100%-covered schema rather than the description.

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

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

Schema coverage is 100%, with limits, ranges and even the offset-chaining hint documented inline, so the baseline is 3. The description only restates the filter categories already covered by parameter descriptions, adding no syntax or format detail beyond the schema.

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

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

States a specific verb plus resource ('Search Collmex vendors/suppliers') and even names the underlying record type (VENDOR_GET), which makes the domain unambiguous. It does not explicitly route against similar siblings such as collmex_list_addresses or collmex_list_customers, 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 enumerated filter dimensions (vendor number, free text, postal code, country) imply how to constrain a search, and that all are optional is visible in the schema. There is no explicit when-to-use / when-not guidance and no named alternative for overlapping lookups like address or customer lists.

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