PHP Point of Sale MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces them with the concrete consequence: retrying creates a duplicate. It adds genuinely non-structured traits — the required API key scope, the fact that the store's 'new customer' webhook fires, and that balance/credit limit/loyalty points must be set elsewhere.

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?

Five compact sentences, each doing distinct work: write class, excluded fields, auth, idempotency hazard, side effect, and endpoint. The risk warning is front-loaded after the purpose statement, 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 15-parameter mutation with side effects and no output schema, the description covers auth, idempotency, webhook firing, and field exclusions well. The one real gap is the return value — with no output schema, the agent isn't told what comes back (e.g., the new customer ID) to chain into a follow-up 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?

Schema coverage is 100% and each of the 15 fields carries its own description, so the schema carries the parameter burden. The description's only parameter-adjacent content is a negative statement (balance, credit limit, loyalty points cannot be set), which is useful scoping but doesn't add syntax, defaults, or format semantics 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?

Opens with an explicit verb class ("WRITE: create") plus a concrete resource ("a customer in the store"), which separates it cleanly from the read-side siblings like phppos_get_customer and phppos_list_customers. It also bounds the scope by naming fields that are out of reach here, so the agent's mental model of the tool matches what it 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?

Gives a concrete precondition ("check phppos_list_customers first") tied to a specific failure mode, and states the auth requirement (Read/Write API key). It stops short of explicitly routing create-vs-update decisions to phppos_update_customer, so the alternative-selection guidance is strong but not complete.

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 destructiveHint=true and idempotentHint=false, but the description adds value the annotations cannot: the write propagates into expense and profit-and-loss reports, and the auth requirement is a Read/Write key. The duplicate-on-retry warning restates idempotentHint=false, so it is useful but partially redundant.

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, no filler, with the WRITE marker and the core purpose front-loaded before the side effects, the auth requirement, and the endpoint. Every sentence adds a distinct operational 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?

Covers purpose, auth, side effects, and duplicate risk for a ten-parameter mutation with no output schema, leaving the schema to document the remaining fields. Minor gap: it lists date among the core inputs even though expense_date is optional and defaults to now, and it says nothing about the optional category/location fields that shape reporting.

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 already explains every one of the ten parameters, including defaults for expense_date and the location_id cross-reference. The description only echoes description/amount/date and adds no constraints, formats, or mapping beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ("record an expense in the store's books") and names the core content inline (description, amount, date). The "WRITE:" prefix and the POST /expenses endpoint immediately separate it from the read siblings like phppos_list_expenses and phppos_get_sale.

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 a concrete prerequisite ("Needs a Read/Write API key") and routes the agent to phppos_list_expenses before retrying, which is real decision guidance. It stops short of stating when an expense should not be recorded or when a different creation tool applies, so it is strong but not exhaustive.

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 annotations (which already flag non-read-only, destructive, non-idempotent, open-world), the description adds non-obvious operational facts: a Read/Write API key is required, retrying creates a duplicate record, and configured item webhooks fire on success. Those are the exact side effects and preconditions an agent cannot infer from structured fields.

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

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

Six tight clauses, front-loaded with the WRITE marker and the resource, followed by scope, auth, idempotency, side effect, and endpoint. No sentence is filler and the ordering matches the decisions an agent makes before calling.

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 14-parameter mutation with no output schema, the description covers auth, side effects, idempotency, and duplicate avoidance. It does not indicate what is returned (e.g., the new item id) or how follow-up stock setup should be done, which is a modest gap for a creation tool.

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

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

Schema coverage is 100%, so parameter documentation is already handled and the baseline is 3. The description adds value by confirming the sole required field and, more importantly, by declaring that stock quantities are deliberately absent from this endpoint, preventing an agent from hunting for a quantity parameter that does not exist.

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 an explicit "WRITE: create an inventory item" verb+resource statement and scopes it ("name required", "Stock quantities are not set here"), which separates it cleanly from phppos_get_item, phppos_list_items, and phppos_update_item. An agent knows exactly what this tool does without opening the schema.

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

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

It gives a concrete pre-call flow ("search with phppos_list_items first") and names the sibling to use, plus a scope exclusion (stock quantities aren't set here). It stops short of stating the when-not case explicitly (e.g., use phppos_update_item to change an existing item) or how to set stock afterwards.

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 genuine value beyond that by listing the data a caller gets back (balance, credit limit, points, custom fields), which matters because there is no output schema. It does not mention behavior on a missing/unknown person_id, so it stops 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 sentences, zero filler, with the identifying scope front-loaded and the returned fields following. Every clause earns its place.

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

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

For a single-parameter read-only lookup with full schema coverage, the description covers what the tool returns and which identifier it keys on. Only edge-case behavior such as not-found handling is absent, and that is a minor gap rather than a blocker.

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 schema already explains that person_id is the customer person id and how to obtain it. The description only restates 'by person id' with no added format or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('One customer by person id') and enumerates exactly what the call returns (contact details, tier, tax settings, balance, credit limit, points, notes, custom fields). That distinguishes it cleanly from phppos_list_customers without opening either 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 single-customer phrasing implies a detail-lookup use case, but the description never says when to use this instead of phppos_list_customers or phppos_update_customer. The only routing hint (how to find person_id) lives in the schema description, not here.

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 goes beyond them by disclosing what the response contains (remaining value, customer, status) and the underlying endpoint, which matters because there is no output schema. It omits lookup-failure behavior, but the value-add over annotations is real.

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 short sentence front-loads the resource and identifier before listing useful return fields, with the endpoint appended last. There is no filler, though the endpoint path is arguably redundant for an agent.

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

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

For a single-parameter read tool with annotations and no output schema, the description covers purpose, identifier, and the salient returned fields. Only edge behavior (not-found handling) and an explicit pointer to the list tool are 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 description coverage is 100% and the single parameter already documents that it accepts a "Gift card number or id." The description repeats that same dual-acceptance point plus the endpoint path, adding little beyond the structured field, so baseline 3 applies.

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

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

"One gift card by its card number (or id)" names a specific verb and resource, and the word "one" plus the fields returned makes it distinguishable from phppos_list_gift_cards without opening the schema. It stops short of explicitly naming the sibling, so it is clear but not maximally differentiating.

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 singular retrieval is implied by "One gift card" and the required card number, which suggests use this when the identifier is known rather than for browsing. There is no explicit statement of when to prefer this over phppos_list_gift_cards or what to do if the number is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the field-level scope of what comes back but says nothing about not-found behavior, error modes, or cost/latency for a single-record fetch — modest value on top of annotations, hence a 3.

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

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

One dense clause followed by the REST route; the returned-field inventory is front-loaded and every token carries information. No filler, no restatement of the name or title.

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

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

With no output schema, enumerating the returned groups is exactly the right compensation for a read-only single-record fetch. Only gaps are what happens when the id doesn't exist and any note about completeness of the per-location/variation nesting — minor for a lookup tool.

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

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

Schema description coverage is 100% and the single item_id parameter is fully documented in the schema, including how to discover it. The description adds no format, range, or edge-case guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('One inventory item by id') and enumerates the payload it covers (prices, tax settings, category, supplier, tags, attributes, variations, tier pricing, per-location settings). The 'by id' framing plus the concrete field list clearly separates it from the sibling list tools (phppos_list_items) and the mutation sibling (phppos_update_item) without needing to open either 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?

Usage is implied rather than stated: fetch a single item when you already have its id. There is no explicit when-to-use/when-not or named alternative in the description — the routing hint to phppos_list_items lives only in the item_id schema description, not the prose.

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 the safety profile is covered. The description adds useful behavioral context by enumerating what the payload contains (supplier, items, quantities, costs, payments) and giving the underlying endpoint, though it says nothing about permissions, pagination or missing-id behavior.

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

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

Two compact sentences: the resource and returned fields come first, the endpoint last. Nothing is redundant or padded.

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

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

There is no output schema, so the description carries the burden of describing the return value, and it does so at a reasonable level of detail. It stops short of describing envelope/error shape or not-found behavior, but for a simple single-record read it is largely sufficient.

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 receiving_id parameter is documented there, including how to obtain it via phppos_list_receivings. The description adds no further meaning about the identifier, so the baseline 3 applies.

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

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

It names a specific verb (get) and resource (one receiving) and scopes it by id, plus advertises the returned content (supplier, items, quantities, costs, payments). It implicitly separates itself from phppos_list_receivings via 'one ... by id' but never states the contrast 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?

Fetch-a-single-record usage is implied by 'one receiving by id', but there is no explicit when-to-use or when-not, and no alternative named in the description (the pointer to phppos_list_receivings lives in the schema, not here).

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 (readOnly, non-destructive, open world), and the description adds genuinely new context: the composition of the returned object (line items, payments, taxes, customer, employee) and that verbosity defaults to full. It doesn't cover error behavior for a missing id, which keeps it from a 5.

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

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

Two tight sentences, return contents front-loaded, endpoint appended as a trailing reference. 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 does the necessary work of naming the nested entities returned, and both parameters are fully documented in the schema. It lacks guidance on what happens for an invalid or unknown sale id, the one remaining gap.

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

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

Schema coverage is 100% and the sale_id description already explains it is the receipt number findable via phppos_list_sales. The description only restates that verbosity defaults to full, which the enum schema also declares, so it adds little 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 ('get') and resource ('one sale by id') and enumerates what the payload contains (line items, payments, taxes, customer, employee). It does not explicitly name phppos_list_sales as the alternative, but the singular scope makes the distinction inferable.

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

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

Usage is only implied: 'one sale by id' signals a single-record lookup versus a list, but the description never says when to prefer this over phppos_list_sales. The pointer to phppos_list_sales for finding the id lives in the schema, not the description.

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 the safety profile is covered. The description adds only the REST endpoint mapping, saying nothing about not-found behavior, permissions, or what a returned supplier contains.

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

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

Two terse fragments with the key fact (single supplier, person id) front-loaded. Minimal waste, though the raw endpoint path earns little space given it duplicates the schema parameter.

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

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

There is no output schema, so the description is the only place the return contents could be described — and it says nothing about which supplier fields come back or what happens if the id doesn't exist. For a simple single-record read that gap is tolerable but real.

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 schema already tells the agent to find the id with phppos_list_suppliers. The description merely restates 'by person id', adding no format or lookup detail beyond the structured field.

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 retrieval verb and resource: one supplier, by person id, plus the underlying endpoint path. It implicitly contrasts with phppos_list_suppliers (singular vs plural), so an agent can distinguish it, though that contrast is never made explicit.

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 no when-to-use guidance, no prerequisites, and no named alternative — the only pointer to phppos_list_suppliers lives in the schema, not the description. Usage is inferable from 'by person id' but nothing is stated.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds the returned field set, which is useful, but says nothing about ordering, default result volume, or paging behavior beyond 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?

A single tight sentence that front-loads the verb and the returned content, with the optional time-window clause last. 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?

With no output schema, the description compensates by naming the returned fields, and pagination is fully documented in the schema. Only ordering/default result behavior is left unstated, a minor gap for a read-only list tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's 'within a time window' correctly frames the start_time/end_time pair, but adds no format or boundary semantics beyond what the schema already documents.

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 appointments/bookings) and enumerates what each row contains (customer, employee, service, start and end time), plus the underlying endpoint. Distinguishable from the many create_/get_/list_ siblings, though it does not explicitly contrast with any list_* 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?

'Optionally within a time window' implies the filtering use case, but there is no explicit guidance on when to use this versus a specific-record lookup or how it relates to siblings. Adequate implied usage, no exclusions or alternatives named.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The description adds the mapping to the underlying endpoint (GET /categories) but says nothing about pagination behavior or result shape beyond "ids"; with annotations carrying the safety profile, this is adequate but not rich.

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

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

Two short sentences, zero filler, with the core purpose front-loaded before the practical follow-on. Every clause 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 read-only list tool with full schema coverage and complete annotations, the description is nearly sufficient; only return-shape details (whether categories include more than id, e.g. name/parent) are left implicit. No output schema exists, but the surface is small enough that this is a minor gap.

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

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

Schema description coverage is 100%, so limit, offset and search are fully documented in the schema itself. The description adds no additional meaning about these parameters, which is the correct baseline-3 case 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?

"List item categories with their ids" states a specific verb and resource, and "categories" is clearly distinct from siblings such as phppos_list_items and phppos_list_item_kits. It stops short of explicitly contrasting with those siblings, but the resource noun does the disambiguation work.

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 second sentence gives downstream intent ("Use the ids to filter items or to file a new item"), which implies when this tool is useful, but it never says when to prefer it over alternatives or what the limits are. No exclusions or prerequisites are named, leaving usage 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond that by naming the fields returned and the underlying endpoint (GET /customers), which matters because no output schema 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?

Two tight sentences, front-loaded with the capability and returned data, then the search modes, then the endpoint. Nothing is redundant.

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

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

With 7 optional parameters, no output schema and no nested objects, the description covers purpose, return attributes and search semantics well enough to call the tool. Minor gaps remain around how sort_col/sort_dir and location_id interact with search, but the schema already carries those details.

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

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

Schema description coverage is 100%, so limit, offset, sort_col, sort_dir, location_id and search_field are all documented in the schema. The description only restates the search_field enum values already present in the schema and says nothing new about sort, location scoping, or the search/search_field interaction, so it sits at 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 ('List or search customers') and enumerates the returned attributes (contact details, tier, store-account balance, credit limit, loyalty points), which makes the tool's scope concrete. It is distinguishable from the singular phppos_get_customer by the plural 'list/search' framing, 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?

'Search by text or by one field' gives real guidance on the two mutually exclusive search modes and lists the exact fields valid for search_field. It stops short of routing the agent between list vs. get_customer vs. update_customer, but the operating context is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing that passwords and permission maps are never returned — a data-exposure boundary an agent cannot learn from the schema. It stops short of describing pagination or ordering beyond what the offset parameter already says.

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 returned-field inventory first, then the exclusions, then the endpoint. Every clause carries information and nothing is repeated from the schema or annotations.

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 enumerates the returned fields and the withheld ones, which is exactly what an agent needs to judge whether this call answers its question. It could still say something about result ordering or the pagination envelope, but for a simple four-parameter list tool it is close to 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%, with all four parameters (limit, offset, search, location_id) documented including ranges and the next_offset paging hint. The description adds no parameter-level meaning beyond that, so the baseline of 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 (List) and resource (employees) and enumerates the returned fields — name, contact details, username, hire date, manager, commission, pay rate, locations — plus the HTTP route. This is well beyond a tautology, though it does not explicitly distinguish itself from list siblings (e.g. phppos_list_customers) or note any scope limits.

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 endpoint line 'GET /employees' and the field enumeration suggest a read-only roster lookup. There is no explicit when-to-use guidance, no note on when to prefer filtering by location_id versus free-text search, and no mention of alternatives.

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 the safety profile is covered. The description adds the returned field set, which is genuinely useful since there is no output schema, but says nothing about pagination behavior or result volume.

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

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

Two short sentences, front-loaded with the action and the payload shape, with no filler. The field enumeration is long but each item conveys real information about the response.

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

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

With no output schema, the field list compensates well for describing what comes back, and annotations cover safety. The main gap is that the description never mentions the paging/next_offset contract, which only appears buried in the offset parameter.

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 all six filters (limit, offset, search, sort_col, sort_dir, location_id) are documented in the schema, including the next_offset paging hint. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ("List recorded expenses") and enumerates the fields returned, plus the backing endpoint GET /expenses. It clearly separates this from phppos_create_expense, though it never names any 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?

The description gives no when-to-use, no when-not-to-use, and no alternative (e.g. phppos_list_reports or phppos_list_locations for cross-cutting queries). Only the verb "List" implies it is a read operation; everything else must be inferred.

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 the safety profile is covered. The description adds genuinely new behavioral context by naming the underlying endpoint (GET /giftcards) and the shape of the response fields, which matters because no output schema 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?

Two compact sentences with zero filler; the field enumeration is front-loaded and the endpoint is a terse trailing reference. Nothing could be removed without losing information.

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

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

With no output schema, the description usefully compensates by listing returned fields, and annotations handle safety. The remaining gap is that it never mentions pagination behavior or the default page size, 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 100%, so limit, offset and search are fully documented in the schema, including the paging.next_offset convention. The description says nothing about parameters, so it adds no meaning beyond the schema and the baseline 3 applies.

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

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

States a specific verb (List) and resource (gift cards) and enumerates the fields returned, which lets an agent distinguish it from phppos_get_gift_card. It does not explicitly name the sibling, but the list/get distinction is clear enough from the tool set.

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: use this to enumerate gift cards, versus phppos_get_gift_card for a single record. There is no explicit 'use this when…' statement, no mention of paging through with offset, and no note about reaching for search to narrow results.

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 the safety profile is covered. The description adds the underlying endpoints (GET /invoices/customer or /invoices/supplier), which is modest extra context, but says nothing about pagination behavior, defaults, or what the rows contain beyond four named fields.

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

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

Two compact sentences, front-loaded with the resource and subtype distinction, with the endpoint detail appended rather than buried. No filler, though the endpoint sentence is of limited use to an agent that does not construct HTTP calls.

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 list tool with 6 fully documented parameters and no output schema; the description covers what is listed, both record categories, and the returned fields (date, due date, status, amount). Remaining gaps around paging and default sort are largely handled by the schema itself.

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 including enum meanings, limit bounds and offset paging advice is already documented in the schema. The description's only added semantics is restating the customer/supplier distinction at a conceptual level, so the baseline 3 applies.

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

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

States a specific verb (list) and resource (invoices) and disambiguates the two subtypes by explaining that customer invoices are money owed to the store while supplier invoices are money the store owes. That clarifies the domain meaning of the `type` enum, though it never contrasts itself with neighboring list tools such as phppos_list_sales or phppos_list_receivings.

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 when to use it (whenever you need invoice records) and pins down the two type values, but gives no explicit when-to-use guidance, no exclusions, and no mention of alternatives in a 25-sibling toolset where list_sales/list_receivings could be confused with invoices.

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 the safety profile is covered. The description adds that results include prices, which is genuine return-content context, but says nothing about result size, ordering, or what happens with large catalogs.

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

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

Two short sentences with the purpose front-loaded and the concept gloss immediately adjacent. The trailing 'GET /item_kits' is mildly redundant but adds endpoint context at negligible cost.

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 fully documented params and annotations covering safety, the description covers the essentials. Absence of an output schema is partly mitigated by the offset field referencing next_offset, though the shape of a kit record is only hinted at by 'with their prices'.

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 four well-documented parameters (limit, offset, search, category_id), so the schema already carries the semantic burden. The description adds no parameter-specific meaning beyond what is in the schema, which is the expected 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 (list item kits) and clarifies the domain concept with a parenthetical: 'bundles of items sold together'. It also discloses the underlying GET /item_kits endpoint. It does not explicitly contrast with the close sibling phppos_list_items, leaving the kit-vs-item distinction to be inferred from the noun.

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 versus phppos_list_items or phppos_list_categories, and no guidance on when filtering by category_id is appropriate. The only usage-relevant information (paging) lives in the schema, not the description.

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 the safety profile is covered. The description adds the returned field list, the search-mode semantics and the GET /items endpoint, but says nothing about pagination defaults, result caps (limit max 1000) or result volume — details an agent querying a large inventory would want.

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

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

Three short sentences, front-loaded with purpose and returned fields, with no filler. The trailing '...' in the field list is slightly sloppy for an enum that the schema enumerates fully.

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 7 optional params and no output schema, the description usefully compensates by naming the item attributes returned. Paging behavior is delegated to the well-documented schema, so nothing critical for a correct call 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 description coverage is 100%, so every parameter is already documented in structured fields, and the description largely restates them ('search by text, or by one field' mirrors search/search_field). Baseline 3 is appropriate; the description adds no format or example values 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 pair (list/search) and resource (inventory items), and enumerates the fields returned, so the agent knows what comes back. It stops short of explicitly distinguishing itself from phppos_get_item or phppos_list_item_kits, leaving that inference to the agent.

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 sentence 'Search by text, or by one field' communicates the two query modes and implies they are mutually exclusive, which is genuine usage guidance. However, there is no statement of when to prefer this over phppos_get_item for a single lookup, or over phppos_list_categories for taxonomy data.

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/non-destructive/openWorld, so the safety profile is covered. The description adds non-obvious behavioral facts: payment-processor credentials and device settings are withheld from the response, and the underlying endpoint is GET /locations. Return shape is disclosed field-by-field, which annotations cannot convey.

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

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

Front-loaded with the resource and its fields, followed by the actionable id-filtering tip and the credential exclusion. Only the bare 'GET /locations' tag is low value; otherwise every clause 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?

With no output schema, the description compensates well by enumerating returned fields and the nested registers array, and it flags excluded sensitive data. Paging is left to the schema, which handles it, so nothing critical 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 limit, offset and search are fully documented in the schema, including the next_offset paging tip. The description adds no meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('List the store's locations') and enumerates exactly what each record contains, including nested registers. This clearly separates it from the get_* tools and from list_* siblings over other 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?

'Use the location ids to filter sales, expenses, customers and reports' establishes the downstream purpose and makes this the clear starting point. It does not state when NOT to use it or name an alternative tool, so it stops just short of explicit routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value beyond them by disclosing what the payload contains (supplier, totals, items) and that this maps to GET /receivings, which matters 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?

A single front-loaded sentence that defines the resource, its scope and its contents, with the endpoint noted at the end. No filler, no restatement of the title, nothing an agent must skip over.

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 summarizes the returned fields, and annotations cover the safety profile while the schema covers paging. The remaining gap is behavior when start_date/end_date are omitted (unbounded vs. default window), which an agent calling with zero required parameters would want to know.

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

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

Schema description coverage is 100%, so all four parameters already carry their own documentation including paging semantics. The description only restates the date-range filtering concept and adds nothing about date format or default range, so the baseline 3 applies.

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

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

States a specific verb and resource ('List receivings') and then defines the domain term — stock received from suppliers, purchase orders, transfers — plus which related data comes back (supplier, totals, items). An agent can distinguish this from phppos_get_receiving (single record) by implication, though it never names the 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?

The 'by date range' clause implies the natural use case, but there is no explicit guidance on when to pick this over phppos_get_receiving, no mention of paging strategy, and no statement about what happens when no date filter is supplied. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real value by disclosing the two distinct return shapes (keys only vs. reports with inputs) and the underlying GET /reports endpoint. It does not mention volume/pagination behavior for a 138-item catalog, which is a minor remaining gap.

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 the count, then the critical behavioral fork between search and no-search. The parenthetical taxonomy of report types is long but earns its place by helping an agent judge whether a needed report exists.

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

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

With no output schema and only one optional parameter, the description does the necessary work by describing both return shapes and the endpoint. The only meaningful omission is not naming phppos_run_report as the follow-up tool for a discovered report key.

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 baseline is 3, but the description adds concrete example search terms ('inventory', 'profit') and, more importantly, explains that search changes the response shape, not just filtering. That is meaning beyond the schema's own 'contain this text' 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?

States a specific verb and resource ('catalog of the store's reports') and enumerates the report families covered, which tells an agent exactly what is returned. It stops short of explicitly distinguishing itself from the sibling phppos_run_report, so the list-vs-execute split must be inferred from 'with the inputs each accepts'.

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 explains the behavior of the search parameter ('without search only the report keys are returned'), which implies the browse-then-filter workflow. It never states when to call this versus phppos_run_report, even though that sibling is the obvious next step after finding a report key.

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 the safety profile is covered. The description adds genuinely useful behavior: what each verbosity level returns (headline fields vs. line items/payments/tax) and that suspended_type switches the result set entirely. It stops short of describing pagination behavior or result ordering, which matters for a paged list endpoint.

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

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

Three dense sentences, front-loaded with the resource and filters before the verbosity detail. The trailing 'GET /sales' is minor but informative for endpoint mapping; nothing else is 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 9-parameter, all-optional list tool with no output schema and full schema coverage, the description supplies what structured fields cannot: payload-size tradeoffs between verbosity levels and the suspended-vs-completed distinction. Pagination semantics live in the schema, so nothing critical 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 description coverage is 100%, so every parameter is already documented, making 3 the baseline. The description does add a little beyond the enum – it explains what minimal, medium and full actually contain – but it repeats the verbosity options and the customer-id-or-email idea rather than expanding on limit/offset or date formats.

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

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

States a specific verb (list/search) and resource (completed sales), then enumerates the three filter axes: date range, customer (id or email), location. It also carves out the suspended-sale case, so an agent can immediately tell this apart from phppos_get_sale (single record) and from the other 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?

Gives clear routing context: use suspended_type for layaways/estimates rather than completed sales, and states that medium is the default verbosity. It does not explicitly name phppos_get_sale as the alternative for retrieving one sale, which is the only obvious inference left 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the underlying GET endpoint, but says nothing about pagination behavior, response size caps, or auth requirements beyond what the schema already implies.

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

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

Two short sentences, front-loaded with the resource and returned fields. The trailing "GET /suppliers." is mildly redundant for an agent but does hint at the REST shape, so it is not wasted enough to drop below a 4.

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 enumerates what comes back (contact details, company, account number, balance), and all six params are fully documented in the schema. It is close to complete for a filtered-list tool; only paging semantics and any supplier-specific filters 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% with enums for sort_dir and search_field, so the schema carries the parameter burden. The description adds no extra meaning such as search matching semantics or how search interacts with search_field, so the baseline of 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 (list/search) and resource (suppliers) plus the fields returned, so an agent can tell it is a collection read. It does not explicitly contrast with phppos_get_supplier for the single-record case, leaving that differentiation to be inferred from the name.

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

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

"List or search" implies the two usage modes, and the search/sort parameters support them, but there is no explicit when-to-use guidance or naming of alternatives such as phppos_get_supplier. Usage is implied rather than stated.

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

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

Goes beyond the readOnly/openWorld annotations by disclosing pagination behavior (paging.next_offset set when rows remain) and scoping permissions (Reports module plus per-report view permission). Doesn't detail rate limits or error behavior for an openWorld 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?

Front-loads purpose and return shape, then pagination, then parameter guidance efficiently in a few dense sentences. The trailing list of typical inputs is slightly long but earns its place given the dynamic params object.

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 paginated, permission-gated read tool with a nested freeform params object and full schema coverage, the definition covers return shape, pagination, permissions, and parameter sourcing. Missing only error/failure handling and explicit when-not guidance.

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 already documents all four parameters including limit/offset and params. The description reinforces the params contents (start_date, end_date, sale_type, location_ids, etc.) but adds little syntax beyond what's in the schema. Baseline 3 applies.

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

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

States a specific verb ('Run'), resource ('one of the store's reports'), and the return shape (title, summary, detail rows). It clearly points to phppos_list_reports as the source of report keys, distinguishing it from the sibling list 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 directs the agent to phppos_list_reports for valid report keys and inputs, and lists typical report examples. It explains permission requirements but doesn't state when-not to use it or offer competing alternatives beyond the list 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?

Goes well past the annotations: discloses partial-update semantics ('only the fields you pass are sent'), that passed values overwrite existing ones, the API-key requirement, the 'edit customer' webhook side effect, and the underlying HTTP verb/path. Annotations already flag destructive/idempotent; the description adds the operational consequences.

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?

Five compact clauses, front-loaded with the WRITE marker and the core semantics before auth and side-effect details. No filler sentences.

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 what matters for a 16-parameter mutation: partial-update behavior, auth, overwrite risk, and side effects, with all parameters documented in the schema. It does not say what the response contains (no output schema exists), which is the one remaining gap.

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

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

Schema description coverage is 100% across all 16 parameters, and the schema itself points to phppos_list_customers for person_id, so the schema carries the parameter burden. The description only generalizes that supplied fields are sent, adding no per-field 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?

States a specific verb and resource ('change fields of an existing customer') and pins the target with the endpoint POST /customers/{person_id}. The 'WRITE:' prefix and 'existing customer' wording separate it cleanly from phppos_create_customer and phppos_get_customer without needing 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 clear conditions for use: only the supplied fields are sent, so it is a partial update, and a Read/Write API key is required. It does not name alternatives (e.g. use phppos_create_customer for new records, phppos_get_customer to inspect before editing), so the bar for a 5 is not met.

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

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

Goes well beyond the annotations: discloses that values are overwritten, that a price change takes effect on the next sale, that a Read/Write API key is required, that the 'edit item' webhook fires, and gives the endpoint. The overwrite and side-effect disclosure meaningfully enriches the destructiveHint=true and openWorldHint=true flags.

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

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

Front-loaded with 'WRITE:', then packs semantics, side effects, auth, and endpoint into a few dense clauses with no filler. Every sentence carries information an agent needs.

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

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

For a 15-parameter mutation tool with no output schema, it covers the mutation model, side effects, and auth. Minor gaps remain: no mention of behavior when item_id is invalid or whether partial updates can conflict with webhook/propagation timing.

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 per-field meanings are already documented; the description's real contribution is the PATCH-style semantics that only supplied fields are sent, plus the concrete field examples. It doesn't restate parameter-level detail, which is appropriate 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?

States a specific verb and resource ('change fields of an existing item') and immediately scopes it as a partial update, which cleanly separates it from phppos_create_item and phppos_get_item. The examples of changeable fields (price, category, active state) make the operation concrete.

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?

'Change fields of an existing item' plus 'only the fields you pass are sent' tells the agent this is the edit path for records that already exist, implying creation belongs elsewhere. It does not explicitly name a when-not alternative, but the existing-vs-new distinction is clear from the phrasing.

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