SalesBinder MCP by usefulapi

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds value beyond them by disclosing the required scope (customers:read) and that only 'visible' customers are reachable, which an agent cannot infer from 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?

One sentence, front-loaded with verb and resource, followed by return scope and permission requirement. No redundant restatement of the title.

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

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

For a single-parameter read with no output schema, the description is nearly complete: it names the identifier format, the fields returned (contact and account summary), and the auth requirement. Only edge cases such as not-found or invisible customers 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 0%, but the single parameter carries a UUID regex pattern. The description compensates by naming the parameter's format ('by UUID'), which is useful, but adds nothing about error behavior for malformed or unknown IDs.

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 (Read) and resource (customer) plus the identifier type (UUID) and the field scope it returns. It is clearly distinguishable from salesbinder_list_customers, though it never names that sibling explicitly.

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

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

'Requires customers:read' gives a concrete prerequisite, which is real guidance. However, it never states when to prefer this over salesbinder_list_customers or what happens for a non-visible/inaccessible customer.

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 readOnly, idempotent and non-destructive, so the description adds real value by disclosing what is returned ('stock and pricing summary'), what is omitted ('photo galleries and custom fields'), and the required scope ('items:read'). It does not describe not-found behavior, but the disclosure beyond annotations is substantive.

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: purpose first, then return scope and limits, then the auth requirement. Every sentence adds information with no repetition of 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, describing the return contents and omissions is necessary and done here, and the auth scope is stated. For a single-parameter read tool this is nearly complete, missing only error/not-found semantics.

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

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

With one parameter at 0% schema description coverage, the description carries the burden and does clarify that item_id is a UUID, consistent with the schema's UUID pattern. It adds no other detail about the identifier's origin, so it only partially compensates for the coverage gap.

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 ('Read one inventory item by UUID') and adds scope ('including archived or sold items visible to the API user'). This clearly distinguishes it from salesbinder_list_items, which returns many items without a UUID.

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 'one item by UUID' framing clearly signals when this tool applies versus the list_* siblings, and the note about archived/sold visibility clarifies useful edge-case coverage. It stops short of explicitly naming salesbinder_list_items as the alternative when only a name/filter is known.

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 four behavioral facts not present in the annotations: the required scope (customers:read), that only 'visible' customers are returned, that pagination is manual via next_page rather than automatic, and that totals are expensive and omitted unless requested. Annotations already cover the read-only/idempotent safety profile, and the description builds on top of that rather than restating 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?

Four short sentences, each carrying a distinct fact (scope, search semantics, auth, pagination/totals), with the core capability front-loaded. No filler or restatement of 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?

A read-only, non-destructive tool with no output schema and no nested objects; the description covers everything an agent needs to call it correctly except the limit cap and defaults. Adequate-to-strong given the tool's low complexity.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does for the two non-obvious ones: q's accepted search shapes (name, office email, exact numeric number) and include_total's default behavior. Page is implied by the next_page instruction, but limit is never mentioned and the page parameter's 1-1,000,000 range and defaults go undocumented.

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 concrete verb and resource ('Read one visible customer page') and immediately narrows what can be searched (name, office email, exact numeric customer number). This is clearly a paged customer list/search, implicitly distinct from salesbinder_get_customer and the list_invoices/list_items siblings, though no sibling is named explicitly.

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

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

Gives usable selection context: search by name or office email for fuzzy matching versus exact numeric customer number, plus an operational instruction to follow next_page manually. It lacks an explicit 'use get_customer instead when you have an ID' routing statement, which is the only meaningful gap.

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, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds genuinely non-redundant context: result ordering, that line items are omitted from results, and the required scope 'invoices:read' — useful for auth planning and for understanding output shape.

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: behavior/sort first, then filters, then constraints and scope. No filler, and the most important operational facts are 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 tool with no output schema, it conveys what comes back (status and decimal amount summaries, no line items) and the auth requirement. The only material gap is silence on the q, page, and limit parameters, which an agent must infer from the schema alone.

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 0% across 8 parameters, so the description carries the burden. It explains customer_id (UUID), status_id, and the issue_date_from/to pair, but never mentions the free-text q, page, or limit parameters, leaving three undocumented in both places.

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 ('Read one visible invoice page') plus scope details: sort order (newest invoice number first), the summary fields returned, and that line items are omitted. Siblings are all different resources (customers, items, locations, sales orders), so the resource noun alone differentiates it clearly.

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 clear usage context ('Read one visible invoice page', filter by customer UUID / status ID / issue date) and explicitly excludes adjacent operations ('no sending or payment operations'). It doesn't name an alternative tool for invoices, but no sibling overlaps on this resource.

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 this is read-only, idempotent, and non-destructive. The description adds useful behavior beyond annotations: it names the required items:read permission, says results are permission-visible, and clarifies that no stock changes occur.

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: it begins with the core read operation, then adds search scope, permission, and safety context. Every sentence contributes useful information without repetition.

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 eight-parameter, no-output-schema tool with 0% schema description coverage, the description is not complete enough to guide correct invocation. It covers the main search and permission model but omits essential parameter semantics and pagination/filtering behavior.

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 0% across eight parameters, but the description only explains q and partially explains location_id. It leaves key parameters such as type, archived, category_id, page, limit, and include_total semantically undefined, so an agent must infer their behavior from names alone.

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 that this reads a visible inventory page and lists retrievable fields, so the verb and resource are specific. It does not explicitly contrast with the sibling salesbinder_get_item, which is the main nearby alternative for item retrieval.

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 implies use for searching inventory by name, SKU, barcode, serial, or numeric item number, and notes that location filtering changes the result. However, it does not say when to use this tool versus salesbinder_get_item or how to choose among search modes.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: results are paged ('one page'), only 'active' locations are returned, visibility is scoped to assigned locations, and an items:read scope is required. It stops short of explaining pagination mechanics or the exact shape of the visibility restriction.

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 purpose is front-loaded and the permission prerequisite follows. Every sentence contributes a distinct fact.

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

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

For a simple read-only list tool with no output schema, the description covers purpose, scope, visibility restriction, and auth requirement. The only real gap is the undocumented pagination parameters, which the schema types alone leave ambiguous.

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 0%, so the description must carry parameter meaning, and it does not: page, limit, and include_total are never mentioned or explained. The phrase 'one page' only vaguely hints that pagination exists without clarifying defaults, bounds, or what include_total toggles.

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 ('Read one page of active inventory locations and their UUIDs'), which is clearly distinct from the sibling list tools for customers, items, invoices, and sales orders. The title's 'warehouses' vs. the description's 'locations' creates minor terminology drift, but the intent remains unambiguous.

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

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

The prerequisite 'Requires items:read' and the note that 'assigned-location visibility applies' give useful context for whether a call will succeed and what it will return. However, there is no explicit when-to-use guidance, no mention of when not to call, and no reference to alternative tools for related 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 readOnly/idempotent/non-destructive, but the description adds real value: page-at-a-time retrieval, the 'visible' scope (permission-filtered results), omitted line items, and the required sales_orders:read scope. It does not explain paging bounds or how to detect the last page, which are the remaining unknowns.

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, each doing distinct work: what is returned, how to narrow, and what is excluded/required. Front-loaded with the resource and the payload summary.

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 9-parameter read tool with no output schema, the description covers return shape, exclusions, auth scope, and safety profile. The gaps are pagination limits and the include_total/q parameters, which matter 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 0% across 9 parameters, so the description carries the load and only partially does so: it names customer, status, warehouse (location_id) and issue date filters. It never mentions q, page, limit, or the non-obvious include_total flag, leaving four parameters with no semantic guidance anywhere.

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?

Names a specific verb and resource ('Read one visible sales-order page') and immediately characterizes the payload ('status, amount and invoiced/packed/shipped progress'). The 'Line items are omitted' clause plus the filter list cleanly separates it from siblings like salesbinder_list_invoices and would-be detail tools.

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?

'Search or filter by customer, status, warehouse or issue date' tells the agent exactly which selection modes exist, and 'no fulfillment changes' rules out using it as a mutation path. It stops short of explicitly routing to a sibling when the caller needs line items or full order detail.

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