listed-wine-companies

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds genuinely useful behavior: inputs are used only for this answer and never stored, and the output is a range implied by recorded multiples rather than an appraisal. It does not disclose rounding, currency conversion, or what happens with sparse inputs, which keeps 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?

The purpose is front-loaded in the first clause, and the caveat plus example payload are valuable. The middle sentence is a long em-dash run-on that takes effort to parse, and a small amount of wording could be trimmed without loss.

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 burden of describing returns, and it does list the outputs (growth, net margin, size percentiles, implied value range). Given nine all-optional parameters, the missing piece is guidance on minimally sufficient inputs and how missing fields affect the 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 coverage is 100%, so the baseline is 3; the description mostly restates units already present in the schema (revenue/profit/ebitda/land_value/inventory in currency, growth in %). It adds the example payload shape but never explains which of the nine optional parameters actually drive the result or what a sensible minimal set looks like.

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: benchmark one private winery's figures against listed wine companies, producing percentiles and an implied valuation range. It is clearly distinct from the sibling lookup/ranking tools (get_wine_company, rank_wine_companies), and the link to the equivalent public page anchors the computation.

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

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

Usage is only implied: an agent can infer it is for valuing a private winery from its own financials. There is no explicit when-to-use/when-not, no statement that this is unsuitable for a listed company (where get_wine_company applies), and no guidance on which inputs are needed at minimum.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavioral detail: the free tier returns only count and names, while history and source probes require the paid x402 route. The phrase "the paid x402 route in `paid`" is somewhat cryptic about how that route is accessed.

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 plus an inline example; the free/paid distinction is front-loaded after the purpose statement. No padding, though the trailing paid-route reference is terse to the point of ambiguity.

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 its job of sketching the return value at both tiers (count/names free, monthly record with history and source probes paid). What's missing is clarity on how the paid route is invoked and whether results are paginated.

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

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

Schema coverage is 100% and the single `symbol` parameter already documents format and points to get_wine_stock_index. The description's example {"symbol":"TWE.AX"} restates what the schema already conveys, so it adds no new 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?

The opening sentence states a specific resource (estates, wineries, vineyards owned by a listed wine company) with a clear scope of ownership. It does not explicitly contrast itself with the sibling get_wine_company, so an agent must infer the difference in output focus.

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

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

Usage is implied by the free-vs-paid split, and the `paid` route is named as an alternative for richer data. There is no explicit statement of when to choose this over get_wine_company or rank_wine_companies, leaving the sibling selection 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 establish read-only, idempotent, closed-world semantics, so the bar is lower; the description still adds real value by disclosing the 5-row free cap, the paid x402 alternative, and the fact that data is sourced from issuers and exchanges. It does not say what the row order or truncation looks like, but the tiering disclosure is the operationally important detail.

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 what the tool returns, then the free/paid split. The trailing JSON example is largely redundant with the schema example and could be dropped without loss.

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 burden of describing returns, and it does name the record types (dates, AGMs, dividends). The free-tier truncation is disclosed, but the unparameterized (no symbol) behavior and response shape remain 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 coverage is 100% and the schema already documents `symbol` with the TWE.AX example and a pointer to get_wine_stock_index, so the description's example adds little. Notably, the parameter is optional (0 required) and the description never explains what happens if `symbol` is omitted, which is the one semantic gap the schema cannot fill.

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 specific resource (results dates, AGMs and dividends for listed wine companies) and its provenance (issuer and exchange sources), which is clearly distinct from siblings like get_wine_stock_index and get_wine_company. It stops short of explicitly naming those siblings as alternatives, so an agent must infer the boundary.

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 clearly states the free tier boundary (next 5 rows) and points to the paid x402 route for the full calendar with recorded outcomes, giving the agent a concrete escalation path. It does not address when to use this versus get_wine_stock_index or get_wine_company, so the sibling routing is left implicit.

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, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are returned with the source URL and locator they were read from, which tells the agent the data is provenance-traceable and 'latest reported' rather than live. It does not mention staleness windows or failure behavior for an unknown symbol.

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

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

One front-loaded sentence that leads with the resource and then the returned fields, followed by a compact example call. Slightly dense with parentheticals but zero filler and no repetition of the input schema's prose.

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

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

There is no output schema, so the description carries the return-shape burden and does so: named result lines, provenance fields, and the next investor event. For a single-parameter, read-only lookup this is enough for an agent to call it correctly without guessing at the response.

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

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

Schema coverage is 100% and the single symbol parameter is already documented with an example and a pointer to get_wine_stock_index. The description repeats the example call ({"symbol":"TWE.AX"}) and adds nothing about format, casing or exchange-suffix conventions. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific resource (one listed wine company, keyed by symbol) and enumerates exactly what comes back: latest reported revenue, operating and net result lines plus its next investor event. That is well beyond a restatement of the name. It stops short of naming how it differs from siblings like get_investor_calendar, which also surfaces investor events.

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 resource scope: fetch a single company's latest results. There is no explicit when-to-use, no exclusion against get_investor_calendar (which overlaps on the 'next investor event' payload) and no statement of prerequisites. The routing hint to get_wine_stock_index for symbol discovery 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 cover the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=false), so the description only needs to add data-specific behavior. It does add one genuine caveat, that prices are delayed, which matters for interpreting results, but says nothing about update cadence, whether the index recomputes live, or how stale data may 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?

The first sentence is well front-loaded and information-dense. However, the trailing 'Example: {}' is a meaningless artifact — it reads like an unfilled template placeholder for a no-argument call and adds no information, slightly undermining an otherwise tight description.

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

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

With no output schema and no parameters, the description carries the burden of describing return content, and it does so at a useful level of detail (level, close, constituent fields). The main gap is the ambiguous 'Example: {}' line and the absence of any hint about the shape or ordering of the constituents 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?

The tool takes zero parameters, so there is no parameter semantics to explain; the 100% schema coverage and empty property set confirm the baseline of 4. The description correctly does not invent or describe nonexistent inputs.

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 (the VINCAP Wine Stock Index / BCWINE) and enumerates its payload: live level, published close, and constituents with symbol, country, exchange and weight. That clearly separates it from siblings like get_estates or rank_wine_companies. It lacks an explicit verb, but the noun phrase is unambiguous about what data comes back.

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 call this versus the sibling tools (get_estates, get_wine_company, rank_wine_companies), nor any exclusions or prerequisites. The only contextual hint is 'Prices are delayed', which tells the agent something about freshness but 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/idempotent/closed-world, so the description is free to add value — and it does: percentile-within-universe scoring, the rule that a company missing a weighted figure is 'listed unscored, never scored as zero', and the direction of the from_high metric. It doesn't state sort order or tie-breaking, which is the main residual 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?

Front-loaded with the core operation, then the scoring rule, then a concrete example payload. The opening sentence is dense and packs five metric definitions inline, which reads more like a clause-stack than prose, but nothing is redundant.

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

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

With no output schema, the description carries the return-shape burden and does so ('each row carries the figures and the results period'), plus it covers the key edge case (missing figures → unscored). For a 3-parameter, zero-required ranking tool this is sufficient for correct invocation.

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

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

Schema coverage is 100% so the structural baseline is 3, but the description earns credit above that by defining what each weight actually measures (growth = revenue growth latest period, margin = net margin, y1 = 1-year share price, wine = wine share of revenue) — semantics the schema only names. The inverted direction of from_high is especially valuable since the field name alone is ambiguous.

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 ('rank listed wine companies VINCAP tracks') and pins the universe precisely as 'index constituents and tracked companies'. This verb (ranking/composite scoring) is clearly distinct from the retrieval semantics of siblings like get_wine_company and get_wine_stock_index.

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

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

Usage is implied rather than stated: the 'include' semantics (index vs tracked vs all) hint at screening scenarios, but there is no explicit 'use this when you want a ranked shortlist instead of a single company lookup' guidance and no mention of the sibling tools as alternatives. An agent can infer the use case but must do the routing work itself.

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