InnoVint MCP by usefulapi

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

Adds real context beyond annotations: the results land in cellar history and feed lot data and reports, and InnoVint's API has no delete for this resource — which meaningfully qualifies the non-destructive annotation by warning that the write is effectively permanent. Auth requirements and rate limits are not covered, keeping it out of the top band.

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

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

Front-loads the WRITE classification and the operation, with examples early rather than buried. It is a single dense paragraph where the trailing endpoint URL is the least essential element, but almost every clause carries actionable 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?

Covers a nested-array write tool well: required fields, the vessel-optional semantics, the slug lookup dependency, side effects and irreversibility. With no output schema, it could still say what the created action returns (id, timestamps), which is 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 coverage is 80%, so baseline is 3, but the description adds genuine meaning: the vessel_id/lot_id relationship (vessel-level versus lot composite), the required triple of analysis type slug, value and unit, and that the unit must match what InnoVint lists. Worked examples (pH 3.45, free SO2 28 mg/L) clarify the value/unit pairing.

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: records analysis results as a new analysis action in the winery's InnoVint records. It is clearly distinguishable from sibling read tools such as innovint_list_analysis_actions and innovint_list_lot_analyses, and even names the exact endpoint.

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

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

Gives concrete routing guidance: fetch the analysis type slug via innovint_list_analysis_types, and add a vessel for vessel-level results versus omitting it for a lot composite. It also states an important gating condition ('only call this when the numbers are confirmed'), though it does not contrast against sibling write/read alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the safety profile is covered; the description adds real value beyond that by flagging the operation as a WRITE, disclosing the exact endpoint (POST /api/v1/wineries/{wineryId}/vendors), and warning about duplicates. It does not say whether a duplicate name errors or silently succeeds, which is the remaining behavioral gap.

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

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

Three short sentences with zero waste, front-loaded with the 'WRITE:' marker so the mutation nature is the first thing read. Every sentence carries distinct information: action, precondition, endpoint.

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 creation tool with full schema coverage, annotations, and no output schema, the description covers action, dedupe workflow, and endpoint adequately. The only missing piece is response/duplicate-handling behavior, which is minor at this complexity level.

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 both parameters are fully documented in the schema, including the winery_id pattern and the innovint_list_wineries pointer. The description adds no additional parameter semantics, 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 ('adds a new vendor (supplier)'), names the system of record ('winery's InnoVint records'), and clarifies the supplier synonym. An agent can immediately distinguish this from innovint_list_vendors without opening either schema.

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

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

Explicitly routes the agent to innovint_list_vendors as a precondition to avoid creating a duplicate, which is concrete when-to-use guidance. It stops short of stating exclusions or what to do when the vendor already exists, so it is strong but not complete.

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

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

The annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description's added value is the enumerated return fields and the raw endpoint, but it says nothing about error behavior, permissions, or what 'links to related data' actually resolves to.

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

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

Two sentences, zero filler, with the payload contents front-loaded before the endpoint reference. Nothing here could be cut without losing information.

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

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

For a two-parameter read tool with no output schema, the description gives enough return-value detail to know what to expect. 'Links to related data' stays vague, and nothing is said about missing-id behavior, so it falls just short of fully self-sufficient.

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

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

Schema coverage is 100%: both lot_id and winery_id carry patterns, examples, and a cross-reference to innovint_list_wineries. The description adds nothing beyond that, 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 and resource (get one lot by id) and enumerates what comes back: stage, volume, weight, bottles on hand, tags, links. 'One lot by id' implicitly separates it from the list endpoint, but no sibling tool is actually named.

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 never says when to reach for this versus innovint_list_lots or the composition/component-summary siblings. There are no prerequisites or exclusions stated, only a bare statement of what is fetched.

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 contributes nothing behavioral beyond that — no indication of whether the summary aggregates additions, analyses, or costs, nor how large or costly the response might be.

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?

It is short and front-loaded, so there is no bloat. However, the second sentence merely transcribes the REST route, which duplicates structural information and consumes the only remaining space that could have carried real guidance.

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 is the only place a caller could learn what the "summary" returns, and it says nothing about the fields or shape. For a summary/aggregation endpoint with a near-identical sibling, this leaves a meaningful 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 the schema already documents winery_id (including how to obtain it via innovint_list_wineries) and lot_id with a concrete example format. The description adds no parameter meaning of its own, 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?

The description restates the title almost verbatim ("A summary of the lot's components") and then repeats the REST path, so the only new information is the endpoint URL. It never explains what a "components summary" contains or how it differs from the closely related sibling innovint_get_lot_composition, which an agent would need in order to choose correctly.

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 when-to-use guidance at all, no prerequisites, and no mention of alternatives such as innovint_get_lot_composition or innovint_get_lot. The agent is left to infer the selection criteria entirely from the tool name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the temporal nuance that composition can be as-of-now or as-of-after-an-action, but says nothing about pagination, size, permissions, or what the composition payload 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 short sentences, front-loaded with the purpose. The raw endpoint path is low-value filler for an agent that already has the schema, but it costs little.

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 carries the burden of describing what a 'composition' returns (components, quantities, percentages?) and does not. For a read tool with three simple params this is workable, but an agent cannot predict the response shape.

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 lot_id, winery_id and after_action are already fully documented with examples. The description's 'right after a given action' merely echoes the after_action schema text, adding no syntax or edge-case meaning.

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

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

States the resource and the concept being fetched ('the lot's makeup composition (what it is made of)'), disambiguating an unusual domain term. It does not, however, distinguish this from the close sibling innovint_get_lot_components_summary, so an agent could still confuse the two.

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 'now or right after a given action' implies when to supply after_action, but there is no explicit when-to-use vs. when-not, and no mention of the components_summary or get_lot siblings as alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds only the endpoint path and the fact that returned permissions are scoped to 'the token user', which is genuine but thin added context; nothing about auth scoping beyond that or how a missing/inaccessible id behaves.

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: the payload first, the endpoint last. Every element earns its place with no filler or 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?

For a one-parameter read-only getter with no output schema, the description usefully enumerates the returned fields (name, internal id, permissions), which compensates for the absent output schema. Only the error/not-found behavior is left unspecified.

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

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

Schema description coverage is 100% and the single parameter already carries its pattern and an explicit pointer to innovint_list_wineries for discovery. The description's 'by id' adds nothing 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 ('One winery by id') plus the fields returned (name, internal id, permissions), which is well beyond a tautology. It implicitly contrasts with the plural list_wineries, but never names that sibling in the description itself, so it falls just short of the top bar.

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: you call this when you already hold a winery id. There is no explicit 'use when' statement or named alternative in the description (the pointer to innovint_list_wineries lives in the schema, not here), and no preconditions or failure cases are mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful context beyond that: the filterable dimensions and the shape of each returned record (action type, effective date, lots and vessels involved), plus the underlying GET endpoint. Pagination behavior is left to the schema rather than repeated here.

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 plus the endpoint reference. The umbrella scope lands first, the record shape second, and the sibling routing last — no filler.

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

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

For a 14-parameter list tool with no output schema, the description supplies the missing return-shape signal (action type, effective date, involved lots and vessels) that the schema cannot convey. The remaining gap is minor: how the many concurrent filters combine and how pagination continues is only in the schema.

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

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

Schema description coverage is 100%, so every one of the 14 parameters is already documented at the field level. The description echoes the filter dimensions (type, state, reference number, dates) but adds no syntax, precedence, or semantics beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb+resource (work history across all action types) and enumerates the concrete action kinds covered (additions, analyses, transfers, racking, blending, bottling, fruit receiving). It also explicitly distinguishes itself from the typed sibling list tools, so an agent can choose without opening schemas.

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 'the typed list tools' when full detail of a single action kind is needed, which cleanly separates it from innovint_list_addition_actions, innovint_list_analysis_actions, etc. It lacks an explicit 'when not to use' (e.g. cross-winery or bulk export), but the context is otherwise 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 and destructiveHint=false, so the safety profile is covered. The description adds only the REST path, which confirms the read-only listing nature but says nothing about default state filtering (ACTIVE vs DELETED), pagination behavior, or result size that an agent would want to know.

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 with the substance front-loaded; nothing is padding. The trailing raw endpoint is of marginal value to an agent that invokes the tool rather than the HTTP API, but it costs little.

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

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

For a 13-parameter list tool with no output schema, the description says what the records are about but not what a record contains (additive type, rate, unit, timestamps, related lot/vessel ids). An agent knows what to query but not what it will get back.

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 every one of the 13 parameters is documented in-schema, including the pointer to innovint_list_wineries for winery_id and the next_offset convention. The description adds no parameter meaning beyond that, which is the expected baseline when the schema does the work.

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 (addition actions) and states its content precisely: which additives were added to which lots and vessels, and when. That content description implicitly separates it from list_transfer_actions or list_analysis_actions, though no sibling is named explicitly.

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

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

There is no when-to-use or when-not guidance at all. With siblings such as innovint_list_actions, innovint_list_lot_additives and innovint_list_lot_analyses available, the agent must infer whether this is the canonical addition source or a subset of the generic action 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds nothing further — no mention of pagination behavior, result ordering, or what 'batches' means in the response — so it contributes essentially zero behavioral context beyond 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?

Two short fragments, front-loaded with the resource identity. The raw 'GET /api/v1/wineries/{wineryId}/additives' path is largely dead weight for an agent that never constructs URLs, but the text is not bloated.

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?

Annotations cover safety, the schema covers all 8 filter/pagination parameters, and there is no output schema to explain. What remains missing is exactly the part structured fields cannot supply: how this catalog listing differs from lot-level additive listings and what shape the results take. Adequate but with a clear gap.

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

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

Schema description coverage is 100% across all 8 parameters, including the winery_id cross-reference to innovint_list_wineries and the offset guidance about next_offset. The description repeats no parameter meaning and adds none, which is acceptable given the schema already carries the burden — 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?

The description names the resource ('additive products and their batches') which is more than a restatement of the title, but it supplies no verb and never distinguishes this catalog-level listing from the sibling innovint_list_lot_additives, which is the most likely confusion point. An agent can guess it reads a winery's additive catalog, but must infer rather than read that.

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 when-to-use guidance at all. With siblings innovint_list_lot_additives and innovint_list_lots in the toolset, the description should say this lists the additive product catalog for a winery rather than the additives applied to a specific lot. Nothing about prerequisites, exclusions, or alternatives is stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the raw REST path, which gives no usable behavioral context beyond the schema – no pagination model, no default state scope (the schema hints 'default is up to InnoVint'), no indication of result volume.

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

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

Two short sentences with no filler, front-loading the resource definition before the endpoint. The first sentence is a sentence fragment, which is terse but readable; 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 14 optional filters, no output schema and no return-value description, the definition leaves the agent to work out result shape, pagination habits and default state filtering from the schema alone. It is minimally adequate for a read-only list call but does not describe what comes back.

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

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

The description contributes nothing about the 14 parameters (date ranges, action_type, state, sorting, pagination). However, schema description coverage is 100% – every property including winery_id and offset/next_offset is documented in-schema – 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?

Names the exact resource (adjustment actions) and enumerates its four subtypes, which meaningfully distinguishes it from the many other action-list siblings such as innovint_list_addition_actions and innovint_list_transfer_actions. The verb is implied rather than stated (the 'list' comes from the name/title and the REST GET path), so it stops short of a fully self-contained statement.

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 when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The subtype enumeration implies the tool is for volume/weight/water/makeup records, but an agent must infer that from the noun phrase alone and gets no help choosing between this and innovint_list_actions.

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 real value beyond that by describing the payload contents (analyses with type/value/unit, linked lots and vessels), which matters since there is no output schema. It does not mention pagination behavior or whether deleted/edited actions appear by default, which are the remaining gaps.

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

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

Two sentences, front-loaded with the entity definition, with no filler prose. The trailing raw endpoint path is largely redundant with the tool contract 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 13-parameter read-only listing tool with no output schema, the description does explain the returned data and is backed by complete schema docs and safety annotations. What it lacks is routing context against the many sibling list/get tools and any note on defaults (e.g. action state inclusion, pagination via next_offset), leaving an agent to infer how this differs from adjacent endpoints.

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 13 parameters (id, state, date bounds, limit/offset, sort, reference_number, winery_id) are individually documented in the schema with formats, defaults and cross-references. The description adds no parameter meaning of its own, 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 names a specific resource (analysis actions = lab and in-house results entered in the winery) and enumerates the content returned (analyses with type/value/unit, plus lots and vessels). It is clear what the tool retrieves, but it never distinguishes this from close siblings like innovint_list_lot_analyses or the generic innovint_list_actions, so an agent cannot tell from the text why it would pick this one.

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 when-to-use or when-not-to-use guidance, no mention of alternates, and no prerequisites beyond the endpoint path. The agent must infer that this is the way to enumerate analysis/lab results per winery, and it gets no help deciding versus list_lot_analyses or list_actions.

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 value beyond that by disclosing the underlying endpoint (GET /api/v1/analysisTypes) and, crucially, that the returned slugs are a prerequisite for other calls — a dependency trait annotations cannot express. Return shape and pagination behavior are not described, keeping it below 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 sentence that front-loads the resource, gives illustrative examples, and ends with the downstream dependency and endpoint path. 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?

For a read-only, fully documented, zero-required-parameter lookup with no output schema, the description covers what the tool returns at the field level of interest (slug) and why it matters. It does not sketch the response shape (names, units, pagination envelope), which is a minor remaining gap given the absence of an output schema.

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

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

Schema description coverage is 100%, with q, slug, limit and offset all documented in the schema, including the hint to pass the previous reply's next_offset. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific resource ('the analysis types InnoVint knows') with concrete examples (pH, TA, free SO2, Brix) and the key payload it returns (the slug). It also names the downstream consumer, innovint_create_analysis_action, so an agent can separate this lookup tool from the many list_* siblings 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?

The description effectively tells the agent when to call it: before creating an analysis action or filtering analyses, because those need the slug. That is a clear use context with an implied alternative (call this first, then the consumer tool). It stops short of explicit when-not-to-call or exclusion language, so a 4 rather than 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 and openWorldHint=true, so the safety profile is covered. The description adds the GET endpoint path, which is mild extra context, but says nothing about pagination defaults, archived handling, or response shape beyond what the schema states.

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 terse fragments with no wasted words, but the clipped noun-phrase style reads as under-specification rather than disciplined conciseness. The endpoint string consumes space without adding agent-relevant meaning.

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 full schema coverage and no output schema, this is minimally viable: filters and pagination are documented in the schema. What is missing is the routing information an agent needs to pick this over innovint_list_vineyards or other list_* 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%, including detailed docs for limit, offset, archived, vineyard_in and id_in, so the schema carries nearly all parameter meaning. The description's only contribution is the 'filter by vineyard' hint, matching the existing vineyard_in description. 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?

The description identifies the resource (vineyard blocks belonging to the winery's vineyards) and the endpoint, but it is a noun fragment rather than a verb+resource statement, so the 'list' action comes only from the title/name. It does partially distinguish scope from innovint_list_vineyards by saying these are blocks of vineyards, but the distinction 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?

'Filter by vineyard' hints at using vineyard_in but gives no when-to-use guidance, no exclusions, and no reference to siblings like innovint_list_vineyards or innovint_get_lot. An agent is left to infer pagination and archived-record behaviour entirely from the schema.

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, covering the safety profile. The description adds the domain concept (TTB bonds) and the GET endpoint, but does not describe return format, pagination, or rate limits. With annotations present, a 3 is appropriate for the additional context provided.

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 two short sentences with no wasted words, and the resource is front-loaded. However, the endpoint notation is slightly redundant for a tool description, and the first sentence is a fragment rather than a complete statement.

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 the simple list operation and full schema coverage, the description is minimally adequate. It conveys what the tool returns at a high level ('whose ids lots belong to') but does not explain response structure, pagination behavior, or whether the list is filtered—gaps that an agent might need when interpreting results.

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 three parameters (winery_id, limit, offset) are fully documented in the schema. The description adds no parameter-level detail 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 identifies the resource specifically as 'The winery's bonded premises (TTB bonds)' and notes their relationship to lot IDs. It distinguishes from siblings because no other bond-related tool exists, though the phrasing is a noun fragment rather than a direct verb+resource statement.

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 mention of alternatives. The clause 'whose ids lots belong to' hints at a use case (looking up bond IDs referenced by lots), but it does not instruct the agent on when to select this tool over others.

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 REST path (GET /api/v1/wineries/{wineryId}/growerReceipts/{vintage}), which helps map to the API but reveals nothing extra about auth, rate limits, or result shape. Pagination behaviour is left entirely to the schema's offset description.

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

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

Two short, front-loaded sentences with no filler; the resource and scope come first. The raw endpoint path is arguably redundant with the tool name but is compact and 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?

With no output schema, the description does not say what a receipt record contains or whether results are paginated, though the offset parameter implies paging. For a simple read-only list endpoint with fully documented params and safety annotations, this is adequate but not complete.

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

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

Schema description coverage is 100%, so limit, offset, vintage and winery_id are all documented in the schema itself, including the next_offset paging hint. The description only restates that vintage is a year, adding nothing beyond the schema baseline.

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

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

States a specific resource ('Fruit receipts from growers') scoped to one vintage, so an agent can tell it apart from innovint_list_growers or innovint_list_receive_fruit_actions. The verb is only implied (list) from the name rather than written out, but the object and scope are unambiguous.

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

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

There is no guidance on when to use this over the sibling list tools (growers, receive fruit actions), nor any prerequisite note beyond the required winery_id and vintage. An agent must infer applicability from the resource name alone.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered elsewhere. The description adds nothing beyond the raw endpoint path — no note on pagination behavior, result ordering, or what a read-only grower list 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 short sentences with no filler; the resource description is front-loaded. The trailing HTTP path is slightly redundant given the tool abstraction but is compact and occasionally useful to API-aware agents.

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

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

A read-only, fully documented four-parameter list endpoint with no output schema does not demand much, and the schema carries pagination and filtering detail. Still, the description omits any sense of what is returned or how results are ordered, leaving an agent to infer the response shape entirely.

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 id filtering, limit range and default, offset semantics including 'next_offset', and winery_id format all documented inline. The description contributes no parameter meaning beyond the schema, 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 names the resource ('the growers the winery buys fruit from') and the underlying GET endpoint, so the retrieval intent is inferable. However, it never uses a verb like 'list' and offers no differentiation from siblings such as innovint_list_vendors or innovint_list_grower_receipts, leaving the agent to lean 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 statement of when to use this tool versus alternatives, no exclusions, and no prerequisites in the description itself. The only routing hint (use innovint_list_wineries for winery_id) lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds only the raw REST path, which conveys nothing about pagination behavior, result ordering, or error conditions beyond what the schema and annotations already state.

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

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

Two short clauses, front-loaded, nothing padded. The endpoint URL is marginal value for an agent but costs little and does anchor the response shape.

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 is the only place an agent can learn what is returned — additive names, amounts, units, application dates, or whether entries are paginated objects. It says none of this, leaving the response shape entirely unknown.

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 itself explains all four parameters, including that offset should come from the previous reply's next_offset. The description adds no parameter meaning on top of 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?

The fragment 'Additives that have been added to a lot' identifies the resource and its scope (per-lot), which does imply a listing. But it is a noun phrase rather than a verb+resource statement, and it never distinguishes this from the sibling innovint_list_additives (winery-wide additive catalog), which an agent could easily confuse.

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 innovint_list_additives, innovint_list_addition_actions, or innovint_get_lot_composition. No prerequisites, no exclusions, nothing beyond the resource statement.

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 useful context by naming the result domain and API endpoint, but it does not discuss pagination behavior, authentication, or response shape beyond what the schema and annotations provide.

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-loads the result domain, then lists the main filter dimensions and the endpoint. It is well structured and has little waste, though the endpoint sentence is somewhat implementation-specific rather than agent-oriented.

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 the rich input schema and explicit annotations, the description covers enough for an agent to understand the resource and main filters. It does not explain pagination or return fields, but pagination is documented in the schema and there is no output schema requiring extra return-value explanation.

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 ten parameters thoroughly. The description mentions filtering by analysis type slug, vessel, and date range, but adds no syntax or format details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly identifies the resource as lab and in-house analysis results recorded on a lot, with concrete examples of analysis metrics and the relevant API endpoint. It is specific enough to distinguish this from general lot or winery tools, but it does not explicitly name sibling alternatives such as innovint_list_analysis_types or innovint_list_analysis_actions.

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 says what can be filtered but gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent can infer that this tool lists analyses for a lot, but there is no stated condition for choosing it over related 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=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine value with the 'as of a date' snapshot semantics of effective_at and the endpoint path, but says nothing about pagination behavior even though the schema references a 'next_offset' that no output schema defines.

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 fragments with no filler; the core resource and the date semantics come first. The raw endpoint string is the only line that does not clearly earn its place for an agent.

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

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

For a seven-parameter read-only list tool with no output schema, the description covers the shape of the data at a high level but leaves the returned cost fields and the pagination contract unexplained. Adequate to select the tool, thin for calling it correctly on multi-page reads.

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 applies: every parameter is already documented in the schema. The description echoes the effective_at and code/lot filter concepts but adds no constraints, defaults or interaction rules beyond what the schema states.

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

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

States the resource (cost data per lot) and its point-in-time nature, plus the underlying GET endpoint, so an agent can tell this returns cost records rather than lot composition or analyses. It never uses an explicit verb like 'List', and cost-vs-composition vs summary siblings are only distinguished by inference from the resource name.

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

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

Mentions filtering by lot code or id, which hints at the retrieval use case, but gives no when-to-use guidance against innovint_get_lot, innovint_get_lot_composition or innovint_list_lots, and no statement of what this tool cannot do.

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 reinforces this with the GET endpoint. It adds genuine value beyond the annotations by enumerating the returned attribute set (code, stage, volume, bottles on hand, tags, etc.), which matters because there is no output schema. Pagination behaviour is left to the schema rather than restated.

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 front-loaded sentences that lead with what is listed and what is returned, then what can be filtered. The trailing GET path is mildly redundant but short and legitimately useful for API-context consumers. No filler sentences.

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

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

With 10 parameters but 100% schema coverage and no output schema, the description carries the burden of describing return content, which it does by listing the exposed fields. Pagination and id-sourcing (innovint_list_wineries) are handled by the schema. The only meaningful omission is explicit routing against sibling lot tools.

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 every parameter including limit/offset semantics and next_offset usage. The description's filter sentence ('search term, code, id, bond, archived state or last update') is a helpful index of the filter axes but adds no format or behavioural detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('List the winery's lots') and clarifies the domain meaning of a lot with a concrete parenthetical (wine, juice, fruit or case-goods batches). It also enumerates the fields returned, so an agent knows what it gets back. It does not explicitly distinguish itself from innovint_get_lot or the various lot-scoped list tools, relying on the 'list vs get' naming convention instead.

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

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

The second sentence lists the available filter axes, which implies when this tool is useful (broad discovery/filtering of lots). However, there is no explicit guidance on when to prefer innovint_get_lot for a single lot, or when a lot-scoped tool like innovint_list_lot_analyses is the right choice. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that results are joined with the received fruit and created lots, which hints at response enrichment, but says nothing about pagination (offset/next_offset), limits, or default state filtering — behavior the agent must infer from the schema.

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

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

A single front-loaded sentence stating the resource and payload, followed by the endpoint path — no filler. The endpoint URL is mildly redundant but useful for API-level traceability.

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 some of the burden of describing what comes back; it gestures at this ('with the fruit received and the lots created') but gives no pagination or shape detail. Against 13 well-documented params and read-only annotations, it is minimally adequate rather than complete.

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

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

Schema description coverage is 100%, and each of the 13 parameters (state, sort, limit, offset, date filters, reference_number, winery_id) is documented inline. The description adds no additional parameter meaning, 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?

Names a specific resource (fruit receiving / harvest intake actions) and adds what the payload contains (the fruit received and the lots created), which goes beyond a restatement of the title. It does not, however, explicitly differentiate itself from the many sibling action-listing tools such as innovint_list_actions or innovint_list_transfer_actions.

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

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

There is no statement of when to use this tool versus the generic innovint_list_actions or the other per-type action lists. The narrower scope is only inferable from the name, and no prerequisites, exclusions, or follow-up patterns are given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond the raw endpoint path: it does not mention pagination limits/defaults, the default state filtering behavior, or the shape of the paged response.

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

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

Two short sentences with no filler, and the resource definition is front-loaded before the endpoint. The endpoint path is arguably redundant with the tool, but it is compact.

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

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

With 14 filter parameters, no output schema, and only a read-only annotation, the definition is minimally adequate — the schema carries all field-level meaning. It stops short of explaining paged results or its relationship to the generic actions listing, which an agent would benefit from here.

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 of the 14 parameters carries its own description (including the winery_id lookup hint and the offset/next_offset paging note). The description itself contributes no additional parameter meaning, 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?

The description names the resource (transfer actions between vessels) and enumerates its concrete subtypes (racking, filtering, topping off, barrel-down), plus the backing endpoint. That is enough for an agent to know it retrieves transfer records, though it never says 'list' explicitly and never names innovint_list_actions as the broader sibling it differs from.

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

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

There is no statement of when to use this tool versus innovint_list_actions or the other typed list_*_actions tools, and no guidance on paginating or on applying the state/date filters. The agent must infer usage entirely from the tool name and schema.

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 concrete GET endpoint and winery scoping, which is useful context. However, it says nothing about pagination behavior, default ordering, or what the response contains—though limit/offset descriptions in the schema partially cover 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?

Two short, front-loaded sentences with no filler. The resource definition comes first and the endpoint second. The REST path is somewhat redundant but useful for agents mapping to the API.

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 annotations covering safety and 86% schema description coverage, the core call mechanics are documented. However, there is no output schema and the description does not describe the response shape, whether vendors are paginated, or what fields are returned. For a seven-parameter list endpoint, this leaves a modest but 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 high at 86%, so the schema already documents most parameters, including limit, offset, id_in, and the winery_id lookup hint. The description adds no parameter semantics beyond the resource scope. Baseline 3 is appropriate where the schema carries the burden.

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 identifies the resource precisely as a winery's vendors and clarifies the domain with examples (additives, dry goods, services). Combined with the title 'List vendors' and the GET endpoint, the read/list purpose is clear and distinguishable from the sibling create_vendor. It stops short of explicitly stating a verb like 'List all vendors' or differentiating from other list siblings.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not explain the relationship between the name and name_contains filters, when to use id_in, or how this list differs from other vendor-related tools. An agent must infer usage solely from the name and schema.

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 known. The description adds that results carry codes and current contents plus the underlying GET endpoint, but says nothing about pagination behavior, result caps, or permissions beyond what the annotations cover.

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 what the tool returns and followed by the filter surface. The middle sentence largely echoes schema fields, which is mild redundancy rather than bloat.

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 full schema coverage and no output schema, the description supplies the key return context (vessels with codes and current contents) and the endpoint. The only gaps are the paging envelope and total counts, which the schema's next_offset hint partially covers.

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 one of the eight parameters is already documented in the schema, including paging via limit/offset and the winery_id pattern. The description restates five of the filters and omits limit/offset entirely, adding no syntax or semantics beyond the schema; baseline 3 applies.

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

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

The description gives a specific verb and resource ("List tanks, barrels and other vessels") and states what comes back (codes and current contents). It is clear, but it does not differentiate itself from the close sibling innovint_list_vessels_at_point_in_time, leaving the agent to infer that this one is current-state only.

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

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

The filter list implies how the tool is used (narrow by search term, code, id, lot, archived state), but there is no explicit when-to-use or when-not-to-use guidance. In particular, no signal about choosing this over innovint_list_vessels_at_point_in_time for historical snapshots.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: a 'Preview (vendor contract may change)' stability warning that no annotation conveys, plus the concrete endpoint path. It omits pagination behavior, though the schema covers 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?

Two compact sentences with no filler, and the endpoint path is a useful anchor. The preview caveat leads ahead of the actual purpose, which slightly delays front-loading the core meaning but is defensible as a risk disclosure.

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 full schema coverage and clear annotations, the description plus schema gives an agent what it needs to call correctly. It lacks any hint of what a returned 'vessel contents' record contains, but with no output schema that is a minor gap for a straightforward list endpoint.

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

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

Schema description coverage is 100%, so every parameter including effective_at (ISO 8601 with timezone) and offset/next_offset is already documented. The description reinforces the semantics of effective_at as a historical moment but adds no format or filtering detail 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 and resource: 'What every vessel held at a past date-time (history of cellar contents)', which clearly distinguishes a historical snapshot from the current-state sibling innovint_list_vessels. It does not name that sibling explicitly, so differentiation is implicit rather than spelled 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 phrase 'at a past date-time' implies this is the historical variant versus a current listing, which is usable context. However, it never says when to prefer innovint_list_vessels instead, nor any prerequisite beyond the required effective_at, leaving usage to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the REST path — no pagination behavior, no result ordering, no statement of whether the list is filtered by winery scope or includes archived/inactive vineyards.

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?

Very short with no padding, but it is a sentence fragment followed by an internal endpoint reference, which carries no value for an agent. Brevity here reflects under-specification rather than disciplined front-loading.

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 four-parameter list tool with no output schema, the description should at least say what is returned and how it relates to growers/blocks. It leaves the agent to infer the return shape and the domain distinction from the schema alone.

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

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

Schema description coverage is 100%: limit, offset, id_in and winery_id are all documented in the schema, including the next_offset pagination hint. The description contributes no parameter meaning of its own, 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?

The description is a bare noun phrase ('The winery's vineyards (grower sources)') plus a raw endpoint path; it never states the verb 'list' or the scope of the result. 'Grower sources' adds a little domain meaning, but nothing distinguishes this from sibling innovint_list_growers or explains what a 'vineyard' record contains.

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 indication of when to call this versus innovint_list_growers, innovint_list_blocks, or innovint_list_grower_receipts, and no prerequisites (though winery_id's schema description hints at flow). Usage is only implied by the resource name.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open world), and the description adds genuinely new context: scoped connections return only the selected winery while unscoped stdio returns all accessible ones. That is a non-obvious behavioral trait an agent could not infer from annotations or schema.

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

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

Front-loads the resource and returned fields, then explains connection-mode variance in one sentence. The trailing endpoint path ('GET /api/v1/wineries or /api/v1/wineries/{wineryId}') is the weakest element but still signals the two access modes.

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-optional-param list tool with no output schema, the description names the returned fields and the scoping rules, which is enough to call it correctly. Missing only an explicit pointer to innovint_get_winery for single-record reads.

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

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

Schema description coverage is 100%, with limit and offset fully documented including the default and the next_offset hint. The description adds nothing about pagination, so baseline 3 applies since the schema carries this dimension.

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 the connected winery') and enumerates the returned fields (id, name, permissions). It does not explicitly distinguish itself from the sibling innovint_get_winery, so the boundary between 'list' and 'get' is left to inference.

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

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

The second sentence describes how results vary by connection mode (hosted/scoped stdio vs unscoped stdio), which implies when each behavior applies. However, it never tells the agent when to prefer this over innovint_get_winery or other sibling list tools, so usage is only implied.

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