vintrace MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the description goes beyond them usefully: it discloses audience visibility ('visible to everyone in the winery'), attribution ('recorded under the token's user'), and concretizes non-idempotency ('Adding the same note twice creates two notes'). It stops short of failure modes or permission prerequisites, so not 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?

A single front-loaded sentence carrying the operation, audience, attribution and duplicate semantics, followed by the endpoint. No filler or restated 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 3-parameter mutation with no output schema, the description covers what the operation does and its side effects, and annotations cover the safety profile. It omits what the API returns on success (e.g. new note id), which would be the remaining useful detail.

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 each of stock_item_id, detail and subject documented in the schema, so the schema carries the semantic load. The description adds nothing about parameters (it never mentions the optional 'subject'), which is the expected baseline of 3 when coverage is complete.

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 ('adds') and resource ('note to a vintrace stock item'), and the WRITE prefix immediately separates it from the read-oriented sibling vintrace_list_stock_item_notes. An agent can identify the operation 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?

The 'WRITE:' prefix implies this is the mutation counterpart to vintrace_list_stock_item_notes, and the duplicate-note behavior tells the agent not to use it for deduplicated logging. However, no sibling is named and there is no explicit when-to-use/when-not statement, so the routing is inferred 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 destructiveHint=true and idempotentHint=true, so the description earns credit for adding side-effect context the annotations don't: assignment surfaces the work order in the target operator's list, and reassign=true takes it over from another operator. It does not mention permissions or whether prior assignment history is retained, which matters for a destructive write.

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

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

Three tight sentences: write semantics first, then targeting/reassign behavior, then the prerequisite and endpoint. Every sentence carries information and nothing is repeated from the schema.

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

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

Covers mutation semantics, targeting, override behavior, and a verification prerequisite – sufficient for a 4-param write tool with no output schema. The only gap is the absence of any statement about what a successful call returns or how conflicts surface.

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 defaults for reassign and assign_operator_id. The description reinforces the two interesting ones (reassign, assign_operator_id) but says nothing about job_id and adds no syntax or format detail beyond the schema – baseline 3.

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

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

Opens with an explicit 'WRITE:' marker and a specific verb+resource ('assigns a work order'), then scopes it to the token's own vintrace user or assign_operator_id. This clearly distinguishes it from the read-only siblings vintrace_get_work_order and vintrace_list_work_orders.

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 ('Check the work order first with vintrace_get_work_order') and explains when reassign=true is needed. It stops short of stating what happens without reassign when a work order is already assigned to someone else, so the failure condition is only implied.

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=false, destructiveHint=true and idempotentHint=true. The description adds genuinely useful context beyond them: the operation is a soft deactivation that preserves the record, plus the underlying endpoint. It doesn't mention permission requirements or what state the booking must be in, 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?

Two compact sentences plus an endpoint reference. The "WRITE:" prefix front-loads the most decision-relevant fact, and every clause (soft-delete semantics, prerequisite lookup, endpoint) 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?

A single-parameter mutation tool with rich annotations and no output schema. The description covers purpose, semantics, and how to obtain the required id – nothing an agent needs to invoke it correctly 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% and booking_id is documented there, so the baseline is 3. The description goes slightly beyond the schema by telling the agent where to source the id (vintrace_list_bookings), which is actionable information the schema does not contain.

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 ("deactivates a fruit booking") and immediately clarifies the crucial semantic boundary: the record is kept, not deleted. That distinguishes it cleanly from any delete sibling and tells the agent exactly what state change occurs.

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 run vintrace_list_bookings first to obtain the booking id, which is a concrete prerequisite. It stops short of saying when *not* to deactivate (e.g., what conditions block it), but the routing guidance 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful endpoint detail and the exactly-one selector rule, but says nothing about failure behavior (unknown id, no exact-name match, ambiguous names) or what a returned party 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 sentences, zero filler, with the resource and lookup modes front-loaded and the constraint immediately after. Every clause carries 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 two-parameter read with no output schema, this covers enough to invoke correctly: which selectors exist and that only one is allowed. The remaining gap is what happens on no match or non-exact name input, which matters for an exact-match lookup.

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 parameters are documented, so the baseline is 3. The description's "exact name" wording reinforces the schema's "Exact party name" but adds no new syntax or matching rules; the mutual-exclusivity rule it does add is modestly useful since the schema marks neither parameter 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?

States a specific resource (one party) with its subtypes (customer, grower, supplier, owner) and the two lookup modes (by id or exact name), plus the underlying endpoints. It never names the sibling vintrace_list_parties, so the singular-vs-list distinction is inferable rather than 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?

"Give exactly one" sets a usage constraint, implying the agent should have an id or an exact name in hand before calling. No explicit when-to-use/when-not guidance and no pointer to vintrace_list_parties for fuzzy or partial name matching.

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 read-only, non-destructive, open-world access, so the description doesn't need to restate safety. It does add the useful fact that the response includes vessel, volume and metrics — valuable since there is no output schema — plus the underlying endpoint. Missing only error/not-found 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 clauses, front-loaded with what is returned and followed by the alternate identifier and endpoint. Nothing is redundant and no sentence is wasted.

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

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

For a simple single-entity read with fully documented parameters and no output schema, the description covers identity and returned fields adequately. It leaves the id/barcode relationship and not-found behavior ambiguous, which is the only real 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 the baseline is 3. The description does clarify that barcode is an alternative identifier to product_id, but that clarification actually conflicts with the schema, which marks product_id as required and never indicates the two are interchangeable — a mild inconsistency rather than added precision.

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 wine product by id') and enumerates what comes back ('its vessel, volume and metrics'), which clearly separates it from the list_products sibling. It stops short of naming that sibling explicitly, so the differentiation is inferable rather than stated.

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 parenthetical '(or by vessel barcode)' tells the agent about a second access path, which is real usage guidance. But there is no statement of when to prefer this over vintrace_list_products or vintrace_lookup_stock_item, and no prerequisite/exclusion 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the response includes lines, state and fulfilment, but says nothing about behavior on an unknown id, permissions, or pagination/expansion options.

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 returned payload front-loaded and no filler. The bare REST endpoint is marginal value for an agent but is short enough not to hurt.

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 annotations, the description covers what is returned (header, lines, state, fulfilment), which is the main thing missing from structured fields since there is no output schema. Only failure/permission behavior is absent.

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

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

Only one parameter and schema coverage is 100%, so the schema already documents purchase_order_id fully. The {id} path template hints at where the id originates, but no additional format or sourcing guidance is added 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 resource (one purchase order) and enumerates the returned payload (lines, state, fulfilment), which tells an agent what it gets rather than just restating the title. It does not explicitly name the list-vs-get alternative, but the get_/list_ sibling naming makes the distinction clear.

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 singular resource and the REST path suggest 'call this when you already have an id and need the full record', while list_* siblings cover discovery. No explicit when-to-use/when-not or prerequisites are 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is low. The description adds the underlying endpoints, but says nothing about not-found behavior, code case-sensitivity, or error responses.

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 keying rule; the returned fields are listed compactly. The raw endpoint strings are arguably redundant with the tool itself, but they are brief.

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 getter with two optional params and no output schema, the description covers retrieval modes, exclusivity, and return contents. Minor gaps remain around failure modes and whether code lookups are exact-match.

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

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

Schema coverage is 100%, so the schema documents both fields and the baseline would be 3. The description adds the mutual-exclusivity/'exactly one' rule that the schema cannot express (no oneOf), making it materially more useful than the schema alone.

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

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

States a specific verb and resource (fetch one sales order) plus the two keying options and the fields returned (customer, items, prices, taxes, status). The singular 'One sales order' implicitly separates it from vintrace_list_sales_orders, but no sibling is named explicitly.

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

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

The 'Give exactly one' rule tells the agent not to pass both keys, which is a useful constraint, but there is no statement of when to prefer this over the list tool or what to do when the id/code is unknown. Usage is only implied by the required 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 the endpoint path and the expandable parts, but says nothing about payload size or performance when expanding heavy parts like historyItems.

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 fragments front-load the core behavior and then the optional expansions, with zero filler. Every clause carries new 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 simple single-resource read with a fully documented two-parameter schema and read-only annotations, the definition covers what the agent needs. There is no output schema, but the tool's scope is narrow enough that return-shape detail is a minor omission.

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 baseline is 3. The description restates the expand values verbatim from the schema rather than adding new meaning, and the id parameter is explained only inside 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 ('One stock item by id'), lists the optional expansions, and gives the underlying endpoint GET /v6/mrp/stock/{id}. An agent can distinguish this from vintrace_lookup_stock_item and vintrace_list_inventory without opening a schema.

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

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

Usage is only implied: the id source hint lives in the schema ('from vintrace_lookup_stock_item or vintrace_list_inventory'), not the description. It never states when to pick this over vintrace_lookup_stock_item or when a list call would be better.

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 readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds that the response includes vessel details, dimensions, and contents, plus the endpoint shape, but it does not discuss error behavior, missing ids, or response format.

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

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

The description is compact and front-loaded: it states the single-vessel lookup and returned content first, then includes the endpoint path. There is no filler, and the endpoint path is at least useful for mapping vessel types to path segments.

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 get-by-id tool with annotations and no output schema, the description gives enough to understand scope and returned content. It could be more complete about errors or response shape, but the key invocation context is present.

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 defines vessel_id and the vessel_type enum. The description restates the vessel categories and implies id-based lookup, but adds little semantic detail beyond the schema, so the baseline 3 is appropriate.

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

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

The description gives a specific verb and resource: get one vessel by id, and enumerates the vessel types (tank, barrel, barrel group, tanker, bin) with returned details, dimensions, and contents. It is clear enough to distinguish from list-style siblings, but it does not explicitly differentiate itself from vintrace_get_vessel_details_report.

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 'by id': an agent should use this when it has a vessel id and wants a single vessel. However, there is no explicit when-to-use guidance, no exclusions, and no named alternative such as vintrace_get_vessel_details_report.

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

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

Annotations already carry readOnly/openWorld/destructive, so the description's added value is the authorization scope ('every winery the token's user may access') and the point-in-time snapshot semantics of as_at — both non-obvious and genuinely useful. It does not describe result volume or pagination behaviour, which for an all-wineries report is a real omission.

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

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

Three tight sentences, front-loaded with the report's identity before the options. Slight waste in restating the extra_fields enum already in the schema and in trailing the raw HTTP path, but nothing is 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 13 optional parameters, no output schema and no nested objects, the description covers what comes back (per-vessel contents plus owner/winery/batch), the temporal cut, and the access scope. The gaps are pagination expectations and enumerating which filters are mutually useful, but the offset/limit schema descriptions already handle paging.

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; the description earns above baseline by explaining what extra_fields actually does (adds sections to the output) and that wineryId/wineryName scope the whole result set rather than being per-row filters. Minor cost: it spells those parameters in camelCase while the schema uses winery_id/winery_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?

States a specific artifact ('The bulk wine report'), enumerates the entities it covers (tank, barrel, bin, press, tanker) and the row fields returned (contents, volume, batch, owner, winery) as at a date. That scope wording also implicitly separates it from the single-entity sibling vintrace_get_vessel and from vintrace_list_inventory.

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 extra_fields=composition,allocations,liveMetrics to add them' tells the agent how to widen the payload, and the winery-scoping sentence states the default breadth and how to narrow it. No explicit when-not-to-use or sibling hand-off (e.g. versus vintrace_get_vessel for one vessel), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so safety is covered. The description adds genuine value by disclosing the returned payload shape (jobs with steps, summary text, status, assignee) and the underlying endpoint GET /v6/workorders/{id}. It omits error behavior for an unknown id, 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?

Two sentences plus the endpoint reference, with the core identity of the tool front-loaded and no filler. Every clause contributes either scope, a routing hint, or payload 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 naming the fields returned. For a single-parameter read it is nearly complete, with only missing behavior on invalid/not-found ids.

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 warns this is the numeric id, not the TWL code. The description only restates "by id," adding no format or validation detail beyond the schema, 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 work order by id") and enumerates what comes back: jobs, steps, summary text, status, assignee. This clearly separates it from the list_work_orders siblings, which return collections rather than a single fully-expanded order.

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 to vintrace_list_work_orders or vintrace_list_work_orders_v6 to obtain the required id, which is the only precondition for calling this tool. An agent knows exactly when to use this versus the listing siblings.

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 readOnly/no-destructive/openWorld, so the description's added value is the pagination contract (results plus next_offset) and the underlying endpoint GET /v7/operation/barrel-treatments, confirming a pure read. It still doesn't say anything about result size, ordering, or time-zone/format expectations for the modified filters.

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 the resource is, then the reply shape and endpoint. Slightly telegraphic with the slash-joined 'Barrel move shipments / barrel treatments', but there is no filler.

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

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

No output schema exists, so the description usefully compensates by stating the reply contains results plus next_offset and mentions barrel states and treatment types. For an unpaginated-optional read with fully documented parameters and safety annotations, that is nearly enough; ordering and exact result fields remain unstated.

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, treatment, modified_since and modified_before are already documented in the schema. The description adds nothing about filter semantics (e.g. treatment matching behavior or date format) beyond the schema, 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?

Names a specific resource (barrel treatments / barrel move shipments) and what comes back (barrel states, treatment types), so the agent knows what it is listing. However, it never distinguishes itself from the sibling vintrace_list_shipments, and 'Barrel move shipments / barrel treatments' leaves the exact entity slightly ambiguous.

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?

No statement of when to use this versus vintrace_list_shipments or other list endpoints, and no prerequisites or exclusions. The only usage hint is the implicit pagination contract 'Reply: results plus next_offset', which is mechanics rather than selection 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, openWorldHint, and destructiveHint=false, so safety is covered. The description adds the pagination contract ('Reply: results plus next_offset'), which matters because there is no output schema, but says nothing about filtering behavior, ordering, or whether block context is required.

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 purpose, followed by return shape and endpoint. The GET path is mildly redundant with the readOnly annotation but is compact and does not bury the important 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 six-parameter read-only list tool with no output schema, the description covers purpose and the paging reply but omits what an assessment record contains and gives no hint about how it relates to blocks, which matters since block selection is not a 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%, with all six parameters including the offset paging contract and the ext:/ne: prefix conventions already documented in the schema. The description adds no parameter 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 and resource (list vineyard block assessments) and disambiguates the ambiguous noun 'assessments' with a parenthetical on vine/fruit assessments by the viticulture team. It is clearly distinct from the nearest sibling, vintrace_list_blocks, though it never says so 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?

There is no guidance on when to call this versus related siblings like vintrace_list_blocks or vintrace_search_fruit_intakes, and no prerequisites or exclusions. Usage is only implied by the verb 'list'.

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, destructiveHint=false, so the safety profile is covered. The description adds beyond that: it discloses the reply shape (results plus next_offset) and the underlying endpoint GET /v7/harvest/blocks, giving an agent concrete expectations for a read call.

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, front-loaded sentences with no filler; the resource and its fields come first, then the conditional, then the return shape. The endpoint path is marginal but not distracting.

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 list tool with no output schema, the description supplies the essentials: field scope, the include/vintage condition, and the paging reply shape (next_offset). Only the absence of any sibling routing or edge-case note keeps it from full marks.

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, including the include/vintage relationship and offset paging rule. The description restates the include+vintage pairing but adds no syntax or format detail the schema lacks — 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?

Specific verb plus resource and enumerated fields: 'List vineyard blocks (grower, vineyard, region, variety).' It is clearly distinct from vintrace_list_block_assessments in subject matter, though the description never explicitly names a sibling to route against.

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 one concrete usage condition — include fruitPlacements together with vintage to see fruit placements — which is genuinely helpful. It offers no when-not guidance and no comparison to sibling list tools such as vintrace_list_block_assessments.

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 read-only/non-destructive safety, and the description adds genuinely new behavioral context: the reply shape ('results plus next_offset'), pagination implications, and that only active bookings are returned. It stops short of describing rate limits, permissions, or ordering of results.

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 core action and scope, then required params, then reply shape, then endpoint. Every clause carries information, though the field enumeration ('grower, block, variety, expected pick time and quantity') is somewhat list-heavy for the space it takes.

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 supplies the critical return information (results plus next_offset) and pagination semantics, and it ties the tool to a concrete endpoint. Combined with 100% schema coverage of 11 parameters, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so every parameter including limit, offset, block_name, grower_name and modified_since is already documented in the schema. The description only echoes that vintage and winery_ids are required and notes the plural winery scope, adding little beyond 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 and resource ('List active fruit bookings') and defines the domain term inline ('grape deliveries planned for a vintage'), plus names the fields returned. It does not explicitly contrast with the nearest sibling (vintrace_search_fruit_intakes) or with vintrace_deactivate_booking, so it stops 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?

It declares the two required parameters and the 'active' scope, which implies deactivated bookings are excluded. However, it gives no explicit when-to-use vs. vintrace_search_fruit_intakes or when-to-use vintrace_deactivate_booking instead, so the routing guidance is only implied.

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

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

With readOnlyHint=true and destructiveHint=false already present, the safety profile is covered by annotations. The description adds useful pagination behavior ('Reply: results plus next_offset') and the underlying GET endpoint, but it does not disclose rate limits, auth requirements, or result field structure.

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

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

The description is three tight sentences with no wasted words. The core scope is front-loaded, followed by the return shape and endpoint, making it easy to parse.

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

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

The tool has no output schema, but the description covers the essential return behavior ('results plus next_offset') and all parameters are fully documented in the schema. Annotations cover safety, so the definition is nearly complete for a read-only list tool, though it does not describe the fields inside each allocation result.

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 in the input schema. The description repeats 'status and vintage' but adds no parameter syntax, defaults, or meaning beyond what the schema provides, 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?

The description clearly states a specific verb and resource: 'List brand allocations of bulk wine.' It also explains the domain concept ('how much of a wine is promised to which brand'), but it does not explicitly distinguish this tool from sibling list tools such as vintrace_list_bulk_intakes or vintrace_list_wine_batches.

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 'by status and vintage,' which signals available filtering dimensions. However, the description gives no explicit when-to-use guidance, exclusions, or alternatives relative to the many sibling list/get tools.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context: the reply is "results plus next_offset" and the underlying call is GET /v7/operation/bulk-intakes, which tells the agent the result is paginated and how to continue. No rate limits or field-level return detail, but that is beyond the annotation bar.

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

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

Two tight sentences: the first front-loads purpose and included fields, the second front-loads the response contract. No filler, no repetition 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 must carry the return contract, and it does so at a high level (results plus next_offset). Field-level shape is only loosely described (batch, volume, owner, cost) and pagination defaults are left to the schema, so a small gap remains but the essential call-and-continue information is present.

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 each parameter already documents its meaning, defaults and pagination convention (offset = previous offset + limit). The description adds nothing about parameters, 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 bulk wine/juice intakes") and clarifies the domain concept with a parenthetical gloss plus the attributes returned (batch, volume, owner, cost). This clearly distinguishes it from list-type siblings like list_wine_batches or search_fruit_intakes, though it never names an alternative 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?

No guidance on when to choose this tool over adjacent ones such as vintrace_search_fruit_intakes or vintrace_list_wine_batches, and no mention of prerequisites or filtering strategy. The agent must infer usage entirely from the name and the parameter list.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered; the description adds meaningful context beyond that: the permission requirement and the response shape ('results plus next_offset'), which signals pagination. It does not detail rate limits or error behavior, but that's a minor gap given annotation coverage.

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 plus the endpoint, with the core purpose and time-window scoping front-loaded before the optional filters, permission note, and reply shape. No sentence is wasted.

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

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

For a read-only list tool with no output schema, the description covers the essentials: what is listed, the required period, optional filters, the permission prerequisite, and the reply shape with pagination. Nothing an agent needs to call it correctly 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 start/end, limit, offset, winery_id, winery_name and business_unit are already documented. The description only restates that winery/business unit are optional filters and does not add format or semantics beyond the schema, 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?

States a specific verb (list) and a well-scoped resource ('bulk wine cost movements between batches and wineries'), which is distinct from generic siblings like search_transactions or list_inventory. It does not explicitly name an alternative tool, so it stops short of full sibling differentiation.

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

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

Gives clear usage context: a required time window, optional narrowing to one winery or business unit, and the prerequisite of the vintrace cost-viewing permission. It does not state when NOT to use it or name alternative tools, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. Beyond those, the description adds useful behavior context: the endpoint is GET /v6/inventory and breakout_costing specifically requires the view-costs permission. It does not describe pagination behavior or response shape, but the permission detail is valuable context not present in annotations.

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

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

The definition is compact and front-loaded: the first clause states the resource and scope, followed by returned fields, a permission caveat, and the endpoint. Every fragment carries useful information with no redundant restatement of the tool name.

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

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

For a read-only list tool with six optional parameters, complete schema coverage, and no output schema, the description is quite complete. It names the returned inventory fields (quantity, committed, on order, available, location, owner, tax class), which compensates for the missing output schema, and notes the permissions caveat. Pagination details are left to the schema, which is acceptable.

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 six parameters well. The description still adds a small amount of meaning beyond the schema by naming the specific permission required for breakout_costing ('view-costs'), which the schema only calls 'the permission.' Other parameter semantics are largely left to the schema.

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

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

The description clearly states a specific resource and scope: stock on hand (bottled wine, dry goods, additives) up to a date, with the fields returned. It is easy to distinguish from mutation-oriented siblings, but it does not explicitly differentiate itself from related read tools like vintrace_get_stock_item, vintrace_lookup_stock_item, or vintrace_list_stock_dispatches.

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 by 'Stock on hand ... up to a date.' The description provides no explicit when-to-use guidance, no exclusions, and does not name alternatives such as vintrace_get_stock_item or vintrace_search_items. The only conditional note is about permissions for breakout_costing, not about tool selection.

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

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

Annotations already cover read-only and non-destructive semantics, and the description adds the non-obvious default that completed tasks are omitted unless 'Completed' appears in status, plus the reply shape (results plus next_offset) and pagination continuation. It does not cover ordering, maximum page size defaults, or what a result record contains beyond that.

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?

Roughly three short clauses with no filler, and the core behavioral caveat (completed tasks excluded) is placed early. The telegraphic phrasing ('with lab, template, vessel...') and the trailing raw endpoint read more like notes than prose, but nothing is wasted.

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

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

For a 12-filter tool with no output schema, the description covers the two highest-risk defaults (completed-task exclusion, offset/limit pagination) and total count via next_offset. It is silent on the shape of an individual lab-request result and on how the many filters (date_after, work_order_number, modified_since) combine, leaving gaps the schema alone cannot fill.

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 field list largely restates schema keys; its only genuine semantic addition is the cross-parameter interaction between 'status' and the default exclusion of completed tasks.

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 identifies the resource concretely as 'analysis tasks (samples to measure)' and enumerates the dimensions carried (lab, template, vessel, batch, status, arrival), which lets an agent distinguish it from list tools over work orders, batches, or inventory. The verb 'list' is only implied by the name/title rather than stated in the description itself.

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 a filtered-list use case via the field enumeration and gives one real usage rule ('include Completed in status to see finished tasks'), but it never says when to pick this over siblings such as vintrace_list_work_orders or vintrace_list_wine_batches, nor mentions prerequisites or limits.

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 externally. The description adds the returned field set (address, phone, email) and the getter endpoint, but says nothing about pagination defaults, page-size limits or result ordering even though max/first exist.

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

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

Two compact sentences with the entity scope front-loaded and filtering second. The trailing "GET /v6/party/list" is of marginal use to an agent but costs little; nothing is padded or 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?

For a read-only list endpoint with no output schema, the description covers what the tool returns and how to narrow it, and the annotations carry the safety profile. The remaining gap is pagination semantics (page size default, total counts, how to iterate), which an agent paging this list would want.

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 max, first, category and starts_with are all documented in the schema itself, including the enum and defaults. The description's filter sentence merely restates category and starts_with without adding format, matching behavior, or precedence rules. 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?

Specific verb+resource ("List parties") plus an enumeration of what a party is (customers, growers, suppliers, owners, individuals or organisations) and the fields returned. The plural "List" wording implicitly separates it from the singular vintrace_get_party, 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?

"Filter by the start of the name and category" hints at how to narrow results, but there is no statement of when to reach for this tool versus vintrace_get_party (single lookup) or vintrace_search_items. Usage is only implied by the fact that it is a list operation.

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 value on top by disclosing that results include recent lab metrics, that skip_metrics trades completeness for speed, and that barcode resolves against either a vessel code or an asset id. It does not describe pagination behaviour or result ordering, which keeps it below 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?

Three tight sentences, front-loaded with the returned field set, then the performance tip, then filter semantics. The trailing 'GET /v6/products/list' endpoint string earns little for an agent that never constructs URLs, but it is only a fragment.

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 it explains the one non-obvious parameter (skip_metrics) plus the barcode resolution rule. What remains thin is pagination/ordering behaviour and how this list differs from the batch- or vessel-oriented siblings.

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 max, first, barcode and skip_metrics are already documented. The description adds one piece of meaning beyond the schema — that skipping metrics is a speed optimization — and restates what barcode matches, but says nothing about max/first. 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 plus the exact field set returned (batch code, vessel, volume, colour, state, lab metrics), which is more than a restatement of the name. It never names the nearby alternatives (vintrace_get_product, vintrace_list_wine_batches, vintrace_get_vessel), so an agent must infer the boundary itself.

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 'wines as they sit in vessels' and by the barcode filter, but there is no explicit when-to-use or when-not-to-use, and no routing away from vintrace_get_product for a single product or vintrace_list_wine_batches. The one useful hint is 'skip_metrics=true makes it faster', which is a performance guideline rather than a selection guideline.

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 only the raw endpoint path; it does not say whether multiple filters combine with AND, what the default page size/result cap is, or whether the list is truncated.

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, zero padding, front-loaded with what the tool returns before the filtering guidance and the endpoint. Every clause carries information an agent can act on.

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 fields is the right compensating move, and all 10 parameters are optional and schema-documented. What's missing is pagination guidance (max/first interaction, default page size) for a list endpoint that can return large result sets.

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

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

Schema description coverage is 100%, so every parameter is already documented with types, patterns, enum values and defaults. The description restates the filter dimensions at a higher level without adding syntax, combination rules, or pagination 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?

States a specific verb and resource ("List sales orders") and enumerates the returned fields (customer, status, price list, line items, totals, invoice date), so the agent knows exactly what comes back. The list-vs-get distinction from vintrace_get_sales_order is only implicit in the naming rather than called out.

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 filtering sentence ("Filter by status, customer, order date range or invoice date range") implies when the tool is appropriate, but never states when to prefer vintrace_get_sales_order for a single order or what happens with no filters applied. Usage is inferable rather than 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 and destructiveHint=false, so safety is covered. The description adds that results include destination and wine details and that the reply contains results plus next_offset, which is useful pagination context, but it does not describe auth needs, rate limits, or deeper return structure.

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 plus the endpoint, with the core purpose front-loaded and no wasted language. The return shape and endpoint are compact and useful.

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

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

Given 8 optional parameters, full schema coverage, existing read-only annotations, and no output schema, the description covers purpose, scope, return shape, and pagination sufficiently. It could be slightly richer on differentiating from sibling dispatch-list tools, but it is complete enough to call correctly.

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

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

Schema description coverage is 100%, so all 8 parameters are already documented in the schema. The description adds no parameter-level guidance beyond the implicit scoping to bulk dispatch and inter-winery operations, 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: list shipments created by Bulk Dispatch and inter-winery dispatch operations, with destination and wine details. The scope distinguishes it from generic stock dispatch lists, though it does not explicitly name the sibling vintrace_list_stock_dispatches as 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?

The scope implies when to use it (bulk dispatch and inter-winery shipments), but there is no explicit when-to-use/when-not-to-use guidance or comparison against sibling tools such as vintrace_list_stock_dispatches.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description's remaining job is pagination/return behavior. It does disclose the reply envelope ('results plus next_offset') and the underlying GET endpoint, but says nothing about maximum page size, ordering, or how deep the result set can be paged.

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, front-loaded sentences with no filler: purpose first, then return shape, then endpoint. The endpoint path is arguably redundant for an agent, but each line is compact and scannable.

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 2 optional params, a 100%-covered schema, and no output schema, the description supplies the scope, the reply envelope, and the endpoint. Nothing essential is missing, though a note on distinguishing dispatches from shipments would close the 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%, and both limit and offset are documented there including the maximum of 200 and the 'previous offset + limit' paging hint. The description adds no parameter meaning beyond the schema, which is the baseline-3 case for two fully documented params.

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 stock dispatch actions') plus a parenthetical defining what a dispatch is (bottled goods and dry goods sent out) and the fields it carries (routes, items, shipping information). It does not differentiate from the nearby sibling vintrace_list_shipments, which an agent could easily confuse with dispatches, so it falls 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?

Usage is only implied by the verb 'List' and the scope definition; there is no explicit when-to-use, when-not-to-use, or named alternative such as vintrace_list_shipments or vintrace_get_stock_item. The definition of dispatch contents gives some selection signal but no 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 endpoint and resource context but does not disclose pagination, ordering, or return behavior, so it adds only limited value beyond 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 very short fragments with the resource front-loaded and the endpoint as secondary detail. There is no repetition or wasted text.

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?

This is a simple read-only list tool; annotations cover safety and the schema fully documents the three parameters. No output schema is present, and the description identifies the returned notes well enough, though it could mention pagination behavior.

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

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

Schema description coverage is 100%, and all three parameters are documented in the schema, so the baseline is 3. The description adds no parameter semantics such as pagination defaults or usage of first_result/max_result beyond what the schema provides.

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

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

Identifies the resource as notes recorded on a stock item and supplies the exact API path. It distinguishes the read resource from the sibling vintrace_add_stock_item_note, but the description itself uses a noun phrase rather than an explicit list verb, relying on the title.

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 explicit when-to-use guidance or exclusion. It does not mention that this is the read counterpart to vintrace_add_stock_item_note, nor when to call vintrace_get_stock_item instead; the endpoint alone does not route usage.

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 the reply contract ('results plus next_offset') and the underlying endpoint, which helps pagination behaviour, but nothing about result volume, status values, or filter interaction.

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, purpose first, then parameter hint, then output contract and endpoint – well front-loaded with no filler. The telegraphic phrasing ('Reply: results plus next_offset') is dense but readable.

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 listing tool with a fully documented schema, the description covers purpose, key parameter usage, and return shape. With no output schema present, it at least states what comes back, though it could say more about what a trial blend record contains.

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 every parameter is already documented with constraints and defaults. The description only reinforces one parameter with a worked example (composition_summary_by=variety,vintage) and alludes to offset via next_offset, 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?

Specific verb (List) plus resource (trial blends), with a clarifying gloss '(planned blend trials)' and the fields returned (status and composition). It does not name or contrast a sibling, but the sibling set is other resources entirely, so disambiguation is implicit.

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

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

No statement of when to use this tool versus alternatives, no prerequisites, no guidance on which filters matter. The only usage-like sentence ('Use composition_summary_by=variety,vintage') is parameter syntax help, not tool-selection 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 safety is covered. The description adds genuinely new behavioral facts: the reply shape ('results plus next_offset'), the pagination continuation model, and the underlying endpoint GET /v7/operation/wine-batches. It stops short of stating rate limits or ordering of results, so not 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?

Three short sentences, front-loaded with purpose, then the optional expansion, then the reply shape and endpoint. Every sentence carries information and there is no filler.

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

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

With no output schema, the description usefully states the return shape (results plus next_offset) and how to page, which is exactly what an agent needs. Minor gaps remain: result ordering and whether id lookup mixes with pagination are unaddressed.

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

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

Schema description coverage is 100%, so id, limit, offset and include are already documented in the schema, setting the baseline at 3. The description's note that include=vessels,allocations adds 'where each batch sits' adds a little interpretive value over the schema's bare enumeration, but no format or behavioral detail about the other three 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?

Specific verb (List) plus concrete resource (wine batches), with a parenthetical defining the domain term as 'the named lots of wine' and enumerating the fields returned (volume, variety, vintage, owner). This is clearly distinguishable from the sibling list tools such as vintrace_list_bulk_intakes or vintrace_list_inventory without opening any schema.

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

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

The description tells the agent how to enrich results (include=vessels,allocations adds vessel and allocation placement), which is a usage hint, but never says when to choose this tool over alternatives like vintrace_list_inventory or vintrace_get_vessel, nor any prerequisites or exclusions. Usage is implied by the resource rather than argued.

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 useful behavior beyond that: the reply shape ('results plus next_offset'), the implicit pagination model, and the underlying endpoint (GET /v7/operation/work-orders). It does not state default sort order or how to know results are exhausted, but it goes meaningfully past 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, tightly structured: purpose and scope first, filters second, return/pagination last. No filler and nothing redundant with the schema.

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

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

With no output schema, the description carries the return-value burden, and it does so adequately ('results plus next_offset' ties into the offset parameter). Filters and pagination are covered; the only material omission is the v6/v7 distinction, which matters given a sibling of the same name.

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 (limit, offset, status, operation_types, scheduled_since/before) is already fully documented including the comma-separated multi-value syntax. The description's mention of the filter dimensions adds no syntax or constraints beyond the schema, 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?

Uses a specific verb and resource ('List winery work orders') and parenthetically clarifies the domain with concrete job examples (transfers, additions, bottling) plus the fields returned. It implicitly distinguishes itself from the singular vintrace_get_work_order, but never addresses the near-identical vintrace_list_work_orders_v6 sibling.

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 what can be filtered ('scheduled time range, status and operation type'), which implies when the tool is useful, but gives no explicit when-to-use vs. when-not-to-use guidance. The critical ambiguity — this tool vs. vintrace_list_work_orders_v6 vs. vintrace_get_work_order — is left entirely unresolved.

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 it a safe read, so the description's job is lighter. It still adds real behavior: the default window (last 7 days to 3 days ahead), what the response carries (job counts, status, scheduled dates), and the operator-centric default view.

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 scope, then the defaults, then the endpoint. Nothing is redundant and every sentence carries operational 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 characterizes the return payload and the implicit default filters, which is enough for an agent to call it correctly. It stops short of explaining pagination or how the operator view differs structurally from the general work order list.

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

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

Schema coverage is 100%, so the schema already explains all 8 parameters, giving a baseline of 3. The description adds the default date window that no parameter default states, which materially affects results the agent didn't ask to filter.

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 ('Work orders from the operator's point of view') and adds scope detail ('what is waiting for me / unassigned'). It hints at the distinction from the plain list sibling via 'operator's point of view' but never names the alternative, so differentiation is implicit.

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

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

The framing 'what is waiting for me / unassigned' implies the operator workflow context, which is decent guidance. However, with a sibling tool named nearly identically (vintrace_list_work_orders), the description gives no explicit rule for when to pick this one over that one.

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 lookup, so the description does not need to repeat the safety profile. It adds useful context by listing returned attributes and noting prefix matching, though it does not explain no-match or multiple-match behavior for prefix lookups.

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 definition is compact and front-loaded: the core lookup behavior, identifier options, returned fields, and endpoint are all packed into one efficient sentence.

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 lookup with full schema coverage and annotations, the description is mostly complete, especially since it lists return fields in the absence of an output schema. The main missing context is how this tool differs from the very similar vintrace_get_stock_item sibling.

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 parameter meanings are already clear from the schema. The description adds the one-of invocation pattern ('Give code or id'), but it does not clarify whether both may be supplied or which takes precedence.

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

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

The description states a specific verb and resource: find one stock item by code prefix or id, and lists the fields it returns. It is clear on its own, but it does not distinguish itself from the sibling vintrace_get_stock_item, which appears to cover the same resource.

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

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

The phrase 'Give code or id' implies how to invoke it, and the code-prefix behavior is noted. However, there is no guidance on when to use this versus vintrace_get_stock_item, vintrace_search_items, or vintrace_list_inventory.

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 route (GET /v6/intake-operations/search), which helps an agent understand this is a server-side search returning a paged result set, but says nothing about empty result behavior, permissions, or result ordering.

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

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

Three compact sentences, front-loaded with what the resource is and followed by filters, paging, and endpoint. The enumerated field list ('weights, grower, block, vineyard, vintage, docket numbers and metrics') is slightly redundant with the filter list that follows but still earns its place by describing the payload.

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 13 optional parameters and no output schema, the description should carry more weight on what is returned and how the time-window filters (recorded_after/recorded_before/modified_since) interact. It gives a partial field inventory but leaves key semantics, such as distinguishing the two docket filters, undocumented.

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 baseline 3 applies. The description restates the main filter axes (vintage, grower, vineyard, block, recorded time) and pagination, but adds no meaning beyond the schema and omits any explanation of the intake_docket vs delivery_docket distinction or the modified_since parameter.

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

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

States a specific verb+resource ('Fruit intake operations') and even defines the domain concept ('grape deliveries weighed in at the winery'), which tells an agent exactly what records this returns. It does not distinguish itself from the sibling vintrace_list_bulk_intakes, which an agent may reasonably confuse with this 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?

The filter sentence ('Filter by vintage, grower, vineyard, block or recorded time') implies how to narrow results, which is useful context for use. But there is no explicit when-to-use/when-not-to-use guidance and no mention of the obvious alternative, vintrace_list_bulk_intakes.

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, openWorld). The description adds the important behavioral trait that results are lightweight name/id pairs rather than full records, which is exactly what an agent needs to choose between this and a detail-fetching sibling. Pagination behavior is not mentioned, keeping 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?

Front-loaded with what it returns, then the use case, in two tight sentences. The trailing "GET /v6/search/list" is implementation detail that adds little for an agent and costs a bit of conciseness.

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

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

Given no output schema, the description does the key work of saying results are names and ids. It doesn't say whether results are paged or bounded despite a `first` parameter implying pagination, which is a minor but real gap for a search 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%, with documented semantics for first, exact_match and starts_with, so the schema already carries the parameter burden. The description's item-type enumeration adds a little context but largely mirrors the enum, 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 (look up) and resource (names and ids of one item kind), enumerating the item types and framing itself as an id/name resolver. That framing clearly separates it from the many specialized list_*/get_* siblings which return full records for one fixed resource type.

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 it to find the id or exact name another tool needs" gives a clear selection condition. It stops short of explicitly saying when not to use it (e.g. prefer vintrace_list_blocks when you want full block detail), so no explicit alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description still adds real behavioral value that annotations do not: an implicit date default that silently narrows the result set to today, and the fact that vessel and pre/post volumes come back with each operation. It stops short of disclosing result limits or pagination.

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?

Roughly two sentences, front-loaded with the resource and its scope, then the default behaviour, then the endpoint. No filler; every clause carries information an agent would otherwise have to guess.

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?

All five params are optional and fully schema-described, and there is no output schema, so the description need only frame the call and its result shape — which it does. The residual gap is that nothing explains how batch/owner/winery name filters interact with the date range or what volume of results to expect.

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 all five parameters (including batch_name, owner_name and winery_name) are already documented, which sets the baseline at 3. The description adds nothing about the three name filters — whether they are exact-match or partial, and how they combine — and the 'from/to vessels' phrase describes return values rather than 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 (winemaking transactions: transfers, additions, blends, racking) plus the scope (date range) and the payload it returns (from/to vessels, before/after volumes). The parenthetical examples disambiguate it from near-neighbours such as vintrace_list_cost_transactions and vintrace_search_fruit_intakes without needing to open a schema.

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

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

The 'defaults to today when no dates are given' clause gives the agent a concrete cue for whether to supply dates, but there is no explicit when-to-use/when-not-to-use statement and no named alternative (e.g. cost transactions vs winemaking transactions, or fruit intakes). Usage is implied rather than instructed.

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