MarketTime MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=true, and openWorldHint=true. The description adds valuable behavioral detail beyond those flags: duplicate creation risk on repeat calls, no automatic invitation, and the underlying endpoint. It does not explain the destructive implication or auth requirements, but it meaningfully supplements the annotations.

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

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

Three short sentences, front-loaded with 'WRITE' and the core action. Every sentence carries useful information: mutation type, idempotency warning with alternative tool, invitation caveat, and endpoint. 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 13-parameter write tool with no output schema, the description covers the most important behavioral risks (duplicate creation, no invitation) but omits what the response returns and how to identify the created customer. It also leaves the status default and external_id linkage unexplained. Adequate but with clear gaps given the tool's complexity.

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

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

The tool has 13 parameters with only 31% schema description coverage, so the description should compensate by explaining required or important fields. Instead, it provides no parameter-specific guidance at all — not for the required name/email/phone, nor for the status enum or external_id linking. The schema does constrain required fields, but the low coverage gap is unaddressed.

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

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

States a specific verb and resource: 'create a new customer (retailer) account record.' The 'WRITE' prefix and endpoint make the mutation nature immediately clear, and naming markettime_list_customers distinguishes it from the sibling read 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 tells the agent to search with markettime_list_customers by name before calling, because the operation is not idempotent. It also clarifies that no invitation is sent automatically, which is useful context. It lacks broader 'when not to use' guidance, but the deduplication prerequisite is the key selection condition.

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 non-idempotent and destructive, but the description adds consequences beyond them: each call creates a new record, a duplicate results from a second call, and MarketTime may notify the customer of tracking details. That side-effect disclosure is genuinely useful; the one gap is no mention of failure modes or auth requirements beyond the account-scope note.

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 compact clauses, all front-loaded with the WRITE classification first, the side-effect risk second, the precondition third, and the endpoint last. No redundant 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?

Behavioral risk for a destructive, open-world mutation is well covered and no output schema exists to explain, but with 8 parameters at 50% description coverage the definition leaves half the input surface unexplained. Adequate for safe invocation, incomplete for correct parameterization.

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 only 50%, so the description is expected to compensate for undocumented fields — and it adds nothing. Four parameters (notes, invoice_amount, invoice_number, tracking_number) are undefined in both schema and description, and the description only gestures at 'tracking' generally.

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

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

States the exact verb ('add a shipment with tracking to an order'), the target resource, and the account scope ('manufacturer accounts only'). It also implicitly distinguishes itself from the read-only sibling markettime_list_order_shipments by calling itself the write counterpart.

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 routes the agent: 'Check markettime_list_order_shipments first' names the alternative tool with a clear precondition, and 'manufacturer accounts only' gives an exclusion condition. The duplicate-creation warning ('calling it twice makes a duplicate') reinforces when not to re-call.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's real contribution is the note that the customer's API key is never returned — a concrete disclosure about what the response omits. No auth or rate-limit context is given, keeping it off 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?

One tight sentence plus the endpoint, with the highest-value information (single record, id form, what's included) front-loaded. Every clause carries distinct information and nothing is repeated.

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

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

With no output schema, the description compensates by naming the returned fields and the one omitted field (API key), which is enough for an agent to know what it will receive. It does not cover error behavior or what happens when rep_group_id is supplied but irrelevant, a minor gap.

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

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

Schema coverage is 100%, so both parameters are already documented. The '(like B123)' example adds a small amount of format guidance for customer_id, but rep_group_id's manufacturer-account scoping is only in the schema, not the description. Baseline 3 is appropriate.

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

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

States a specific verb (get) and resource (customer's full record) and enumerates the record contents: addresses, contacts, ship-to locations, terms, pricing method. Adds the endpoint and id format, so it is clearly distinguishable from markettime_list_customers.

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 id-based retrieval and the enumerated contents make it clear this is the single-record fetch versus the sibling list tool. There is no explicit 'use X instead when' statement or note about how rep_group_id scoping changes the lookup, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying GET endpoint, reinforcing read-only semantics, but says nothing about behavior on a missing/invalid id or about rate/visibility constraints.

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 identifier meaning, ending with the endpoint. 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?

With no output schema, the agent gets no indication of what an item record contains or its shape, and no error/not-found behavior is described. For a simple single-record getter the essentials are present, but the return-side context 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 0%, so the description must carry the load, and it does: it identifies the single parameter as a numeric record id and ties it explicitly to the recordID/itemID values seen in item lists. It still does not state what happens if a non-existent id is supplied.

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 (retrieve a single catalog item) and pins it down with the exact endpoint GET /items/{itemID}. It is implicitly distinct from the list_* siblings, but never names them, so the differentiation is left to inference.

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

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

The phrase 'the recordID/itemID in item lists' implies the workflow (list first, then fetch by id), which is useful implied guidance. There is no explicit when-to-use/when-not statement nor a named alternative such as markettime_list_items or markettime_list_item_pricing.

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 underlying endpoint, GET /manufacturers/{id}, which conveys read semantics already given; it says nothing about not-found behavior or response 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?

Two short clauses with zero waste; the resource and lookup key are front-loaded before the endpoint detail. 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?

For a one-parameter read tool with full schema coverage and read-only annotations, the description is nearly sufficient. The minor gap is the absence of any statement about failure when the id does not exist, and no output schema exists to cover the return value.

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% for the single parameter, so the baseline is 3. The description's example (M123) mildly supplements the schema's pattern constraint but adds no new constraint or formatting rule beyond it.

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 resource (one manufacturer) and the selection key (its id), with an example id format (M123). The singular form implicitly contrasts with markettime_list_manufacturers, but that sibling is never named, so differentiation is left to inference.

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: you call this when you already have a manufacturer id (e.g., from markettime_list_manufacturers). There is no explicit when-to-use or when-not-to-use guidance, nor any mention of what to do if the id is unknown.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so "read-only search" is largely redundant. The one piece of genuinely new behavioral context is the Rep Group account scoping note, which is left unexplained; nothing is said about how large or how paginated the trail typically is. Note the POST endpoint is consistent with a read-only search, so no contradiction.

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

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

Two short sentences, zero waste, with the identity of the resource front-loaded ahead of the endpoint detail. 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 3-parameter read with no output schema, the description conveys the essence of the return content (who/what/when). It stops short of describing the record shape or fields, which would matter more given the absence of an output schema, but the core is covered.

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 offset, page_size and order_id all documented including defaults and ranges, so the schema does the work. The description adds no parameter-level meaning beyond the implicit single-order scope.

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+scope: the audit trail of a single order, returning who changed what and when. No sibling tool offers order change history, so it is unambiguously distinguishable from markettime_list_order_details and the list_* family.

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?

Implies usage ("audit trail of one order", "a read-only search") but never states when to reach for this versus order details, nor any exclusion. The parenthetical "(Rep Group accounts)" hints at a scope restriction without explaining what it means for the caller.

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 beyond them: card tokens and card data are never returned (a redaction guarantee), and results are paged by page number. It does not discuss rate limits or ordering of results, keeping it 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?

One dense paragraph, front-loaded with the resource definition, then filters, then the security guarantee, then paging. Every clause carries information; the trailing endpoint string is the only piece that could be dropped without loss for most callers.

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 most of the work: it defines record content, lists the filterable field names, discloses redaction and paging. The remaining gap is that the full reply record shape is never described, so an agent inferring custom filter fields is working from the allowed-field list 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 coverage is 100%, so the baseline is 3. The description exceeds that by enumerating the concrete allowed custom-filter fields (orderID, checkLogID, invoiceNumber, type, commissionPayDate, salespersonPaidID, dateAdded, dateModified), which the schema only gestures at with generic examples like 'orderDate, name'.

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

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

The description names a concrete resource (order payment and commission records) and enumerates the content of each record ('what was paid on which order, commission percent'), which is far more specific than the title alone. It also scopes the tool to 'Rep Group accounts only'. It stops short of naming a sibling for contrast, but no sibling in the list covers payments/commissions, so confusion risk is low.

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 scope restriction ('Rep Group accounts only') and the available filter routes (order_id, modified_since, or custom filters) give implied usage context, but there is no explicit statement of when to reach for this tool versus alternatives such as list_order_details or list_order_changes_history, and no when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds only the return field set. It says nothing about pagination behavior, empty-result handling, or result ordering, which are the behaviors an agent would still need to reason about.

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 fragments with zero filler and the key resource stated first. Slightly telegraphic but nothing wasted.

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

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

For a read-only per-customer list with a fully documented schema and no output schema, the description covers purpose and returned fields adequately. A brief note on pagination iteration would close the remaining gap, but the schema already documents it.

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

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

Schema coverage is 100% and the parameter descriptions already explain offset, page_size ranges and the next_offset chaining. The description adds no parameter meaning beyond the schema — 'one customer' merely restates that customer_id is required.

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 resource ('contact people of one customer') and enumerates the returned fields (name, email, phone, title), plus the underlying endpoint. It is distinguishable from siblings like get_customer or list_customer_ship_to_locations, though the verb 'list' comes only from the title rather than the description body.

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 scope ('of one customer') implies you need a customer id and that this is per-customer lookup, but there is no explicit when-to-use versus get_customer or list_customer_ship_to_locations, and no stated precondition or exclusion. Usage 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds two genuinely useful facts beyond that: customer API keys are never returned (sensitive-data scoping) and the underlying call is POST /customers/get, which explains why a write-shaped HTTP verb is used for a read. Pagination behavior is left entirely to the schema.

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

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

Two tight sentences: purpose plus returned fields first, then filter keys, then the security caveat and endpoint. No filler, and the most decision-relevant information is front-loaded.

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

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

With no output schema, the description compensates by listing the fields a reply contains, which is the right call for a 10-parameter list tool. It is slightly incomplete in not mentioning the paging contract (offset from next_offset, page_size cap) that matters for actually retrieving all customers.

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 90%, so the schema already documents parameters well, setting the baseline at 3. The description's filter sentence only restates what the schema says ('name (contains)') rather than adding format or interaction rules, and it omits offset/page_size entirely.

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 customers') and enumerates the returned fields (name, email, address, status, customer number, salesperson), which is much richer than the title. It implicitly separates itself from get_customer via 'List', but 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 filter list (name contains, state, status, modified_since) implies a browse/filter use case, but there is no statement of when to prefer this over markettime_get_customer for a single record, or over markettime_list_customer_contacts for nested data. Usage is inferable but not prescribed.

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 endpoint and the returned field set, but says nothing beyond what the schema already documents (via offset/next_offset) about pagination behavior or result ordering. No contradiction with annotations.

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

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

Two short sentences, front-loaded with what is returned and followed by the endpoint. Efficient, though the first sentence is a bare noun phrase whose list action is only implied by 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 read-only paginated list with a fully documented schema and no output schema, the description usefully names the returned fields (name, address, account number), which substitutes for the missing output schema. Only minor gaps remain, such as default ordering or whether inactive locations are included.

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 offset, page_size and customer_id each documented including defaults and limits, so the schema does the heavy lifting. The description only reinforces that exactly one customer is targeted; it adds no syntax or format detail about the parameters.

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

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

States a specific resource (ship-to locations) scoped to one customer and names the returned fields, which lets an agent distinguish it from markettime_list_customer_contacts and markettime_get_customer. It stops short of explicitly contrasting with those siblings, but the verb+resource and scope are unambiguous.

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

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

Usage is implied by the scoping to a single customer id and the sibling list of per-customer tools. There is no explicit statement of when to reach for this versus list_customer_contacts or list_order_shipments, and no preconditions or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint (GET /items/inventory) and the response field set, but says nothing about result volume, pagination expectations, or whether stock is per-warehouse, which would be useful for a read of this kind.

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 clauses, front-loaded with the resource and followed by the response fields and sort keys, then the endpoint. No filler, though the endpoint path is arguably redundant and the sort-key list duplicates the enum.

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, four-optional-parameter list tool with no output schema, the description covers what is returned and how it can be sorted, while the schema carries pagination. The main gap is the absence of any statement about scope or filtering (all items vs. a subset).

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 75%, with offset, page_size and sort_direction documented in the schema itself; only 'sort' lacks a description. The description's list of sort fields merely repeats the enum values rather than explaining their meaning or ordering behavior, so it adds little beyond structured data. Baseline 3 is appropriate.

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

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

The fragment "Stock levels per item: quantity available, quantity on the water, next available date, availability flag" names a specific resource and enumerates the returned fields, which is more than a restated title. It is reasonably distinguishable from markettime_get_item and markettime_list_item_pricing, though it never explicitly says how it differs from them.

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

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

Usage is only implied — an agent can infer you call this to check stock/availability, but there is no explicit when-to-use statement, no exclusion of siblings like get_item or list_item_pricing, and no mention of whether it requires an item filter or returns everything.

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

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

Annotations already establish that this is a read-only, non-destructive, open-world operation. The description adds useful context about the pricing fields exposed and the endpoint, but does not describe pagination behavior, auth requirements, or result structure beyond the listed 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?

The description is very short and front-loads the relevant subject matter plus returned fields. It wastes no words, though it reads as terse fragments rather than a structured usage-oriented description.

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

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

For a simple paginated list tool with two well-documented parameters and annotations covering safety, the description provides the key returned fields. No output schema exists, but the listed fields give an adequate sense of the response payload.

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 both offset and page_size are fully documented in the schema. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description states the resource is item pricing and names the key fields returned (unit price, retail price, price codes, discounts), with the underlying GET endpoint. This distinguishes it from sibling inventory and item lookup tools, though it does not explicitly use a verb like 'list'.

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 guidance on when to use this tool versus alternatives such as markettime_get_item or markettime_list_item_inventory. It describes the data but leaves selection entirely 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 the safety profile is covered. The description adds the returned field set and the underlying POST /items/get endpoint, but says nothing about result size, rate limits, or pagination behavior beyond what the schema already documents.

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 fragments with the resource and return fields front-loaded, followed by filters and endpoint. Dense and waste-free, though the telegraphic phrasing slightly reduces readability.

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 partially compensates by listing the fields returned (item number, prices, stock, UPC, categories, images). For a 9-parameter read tool whose schema is well documented, the only real gap is explicit pagination guidance in prose.

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 89%, so the schema already carries most parameter meaning and the baseline is 3. The description reinforces 'name (contains)' and names four filter shortcuts, but omits offset, page_size, sort_field/sort_direction and the generic filters array, which the schema documents anyway.

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

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

States a specific verb and resource ('Search the product catalog') and enumerates the returned fields, so the agent knows this is the list/search counterpart to markettime_get_item. It does not explicitly name the sibling it replaces, keeping it just short of a 5.

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

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

The filter list implies when this tool is appropriate (bulk catalog lookup by name/number/manufacturer/modified date), but there is no explicit when-to-use or when-not-to-use guidance versus markettime_get_item or markettime_list_item_pricing. 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that — the exact returned field set, the default sort (name), and the endpoint — but says nothing about pagination limits or response envelope, which matter for a 250-row-capped paged list.

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: the resource and returned fields first, then sorting options and the endpoint. Dense and front-loaded 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?

With no output schema, the description correctly compensates by listing the returned fields, and the schema covers filtering and paging. Slight gap: the description doesn't mention that results are paged and that next_offset drives the next call, leaving that entirely to the schema.

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

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

Schema description coverage is 100%, so all five parameters are already documented, and baseline 3 applies. The description adds minor value by enumerating the accepted sort fields and stating the name default, which the schema only conveys through examples.

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?

Specific verb+resource (list manufacturers/brands) plus the exact fields returned and the underlying endpoint GET /manufacturers. It clearly contrasts with get_manufacturer by being a collection read, though that sibling is never named explicitly.

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

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

Usage is only implied: the name and 'connected to this account' scope suggest listing all brands, with get_manufacturer as the obvious per-record alternative. There is no explicit when-to-use, when-not, or prerequisite statement, and no mention of how to page through 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 establish that this is a read-only, non-destructive, open-world GET operation. The description adds the concrete endpoint and filter scope, but it does not disclose pagination behavior, result limits, or other operational details beyond what the annotations and schema already indicate.

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

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

The description is a single compact entry with the core purpose front-loaded, followed by scope, filters, and endpoint. Every clause carries useful information and there is no wasteful prose.

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

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

For a read-only listing tool with rich annotations and no output schema, the description covers the key resource, return fields, scoping, and main filter categories. It leaves some parameter-level detail and pagination/sorting behavior to the schema, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 54%, and the description usefully names several filter categories (dates, statuses, manufacturer, PO number, price range) plus order_id. It does not explain the remaining parameters such as sort_field, rep_group_status, manufacturer_status, or pagination semantics beyond what the schema partially 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?

The description gives a specific verb and resource ('List order lines') and names the returned fields plus the scope ('across orders or for one order'). It distinguishes the line-level resource from the sibling order-level tools, though it does not explicitly name an alternative.

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 states that lines can be listed across orders or narrowed to one order via order_id, and it enumerates available filters. However, it does not say when to choose this tool over markettime_list_orders or other sibling listing tools, nor does it give exclusions.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond that: order lines are omitted unless include_details is true, they make replies large, and card tokens are never returned. Auth and rate limits are not covered, keeping it from a top score.

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 purpose is front-loaded, followed by sorting guidance, filter semantics, order-line behavior, and privacy details. Despite covering many parameters, it is dense but not wasteful, and every sentence contributes operational context.

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, but the description covers the critical reply limitations around omitted order lines and non-returned card tokens, while the schema documents pagination and filter details. It does not describe the full response shape or permissions, but it is adequate for a rich, annotated 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 coverage is 100%, so the baseline is 3, but the description adds practical meaning: a sort recipe for newest-first results, status examples, customer_name contains semantics, rep_group_status being Rep Group only, and date filter roles. It does not explain every parameter in detail, but it complements the schema usefully.

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

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

The description uses a specific verb, 'Search,' and resource, 'wholesale orders,' and explicitly distinguishes this tool from markettime_list_order_details for order-line retrieval. It also names the underlying endpoint, so an agent can identify the resource and its scope 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 clear usage guidance for sorting newest-first and names markettime_list_order_details as the alternative for order lines. It does not exhaustively state when not to use this tool versus other list tools, but the key routing condition for line details is explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuine value beyond that by enumerating the fields that come back, which is important since there is no output schema. It does not mention pagination, result limits, or empty-result behavior, keeping it 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?

One front-loaded sentence naming what is returned, followed by the backing endpoint. No filler, no redundancy.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description is nearly complete: it names the returned payload fields so the agent knows what to expect. The remaining gap is pagination and ordering behavior, which an agent may need for large shipments lists.

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

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

Schema coverage is 100% and there is a single required parameter documented as 'The order's recordID.' The description adds nothing about the order_id beyond what the schema states, 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 (shipment and tracking records) scoped to one order, and enumerates the returned fields (tracking number, link, carrier, ship date, invoice). The read/list distinction from the sibling markettime_create_order_shipment is obvious from the verb, though it is never called out explicitly.

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

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

Usage is implied: use this to retrieve shipment/tracking data for a known order. There is no explicit when-not guidance, no mention of what to do if the order has no shipments, and no pointer to the create sibling for adding a shipment record.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the Rep Group scoping restriction and clarifies this is a POST-based read query, which is valuable, but says nothing about pagination limits or rate 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?

Three short clauses, front-loaded with the operation and scope, with zero filler. Every element (fields returned, account scope, endpoint) conveys distinct 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, naming the returned fields is a useful compensation, and the account-scope constraint clarifies access. For a 5-optional-parameter paginated list tool it is nearly complete, though it could note pagination defaults.

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 80%, so the schema already documents name, offset, page_size, and sort_direction. The description adds no parameter detail beyond what the schema provides; the fields it lists are return fields, not input parameters. Baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (Rep Group's salespeople), and names the returned fields (name, abbreviation, status, ids). No sibling tool covers salespersons, so it is inherently distinguishable, but it does not explicitly differentiate itself from the broader list_* family.

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?

'Rep Group accounts only' gives a clear applicability constraint, which is useful. However, there is no explicit when-to-use vs. alternative guidance, and no mention of what to do for non-Rep-Group accounts.

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