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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context — that it prevents column-name guessing and reveals semantic aliasing like brand→`designer` — but says nothing about error behavior for an invalid table alias or how table aliases are discovered beyond a pointer to list_tables.

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 purpose, followed by routing guidance, then a concrete example, then arg notes — a sound ordering. The Rolex example partially restates the preceding sentence's point about `usd_price_decimal`, so it is slightly longer than strictly necessary, but each block still earns its place.

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

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

The return shape is handled by the output schema, and the description covers the remaining needs for a one-parameter read tool: when to call it, what it reveals, how to find valid aliases, and alias disambiguation. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 0% (the lone column is just typed 'string' with no description), so the description must carry the load and it largely does: it explains that `table` is a table alias, points to list_tables for the full set, and disambiguates the confusable 'gems' vs 'jewelry' aliases. Only the alias syntax/format itself is left implicit.

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 a table's column names and types' — and immediately frames the outcome ('so you can build a precise query'), which separates it from query_table, market_stats, and the other siblings. An agent knows exactly what this returns without opening the schema.

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

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

Explicitly prescribes when to call it: 'before query_table (or before adding filters to market_stats / price_trend)'. It names the alternatives and the exact condition that selects this tool, including a concrete worked example with a real table alias and field names.

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?

Adds substantial context beyond the annotations: alerts belong to a signed-in account rather than an API key, this MCP can only read/report them, and a non-signed-in key yields setup guidance rather than data. It also discloses allowance tiers, which helps the agent interpret non-data responses. This is consistent with readOnlyHint=true.

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 and the structure is logical: what it does, account constraints, fallback behavior, then the argument. It is slightly verbose with background about how alerts fire and the allowance list, but those details are relevant enough that the length is largely justified.

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 an output schema exists, the description need not explain return values, and it covers the key behavioral edge cases: feed reachability, account-session requirements, read-only scope, and fallback guidance. For a one-parameter read tool, nothing important is missing.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning. It does: 'limit' is documented as the maximum fired alerts to show, with the condition 'if the alerts feed is reachable' and the default value, fully covering the single optional parameter.

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

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

States a specific verb and resource ('Show ALT/FNDATA price alerts') and explicitly scopes it as read-only or explanatory. It distinguishes this MCP's read/report capability from the app's create/manage capability, so an agent can tell exactly what this tool does without opening the schema.

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

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

Explains when this tool applies (reading/reporting alerts), when it does not (creating/managing alerts, which must be done in the app), and what happens when the API key is not tied to a signed-in session. The alternative path (app.altfndata.com) is named explicitly.

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 openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: results are live/current rather than static, entries include column counts, and it warns about a specific taxonomy trap ("loose gemstones live in `gems`, not `jewelry`"). It doesn't discuss ordering or the shape of each row, but the output schema exists to cover 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?

Front-loaded with the purpose in the first sentence, followed by routing guidance and examples in descending priority. The category enumeration is somewhat long, but it doubles as evidence of scope and the gems-vs-jewelry caveat earns its place.

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

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

For a zero-parameter, read-only discovery tool with an output schema, this covers everything an agent needs: what it returns, when to call it, which siblings to route to next, and the main taxonomy pitfall. No gap remains that would cause a misinvocation.

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 the baseline is 4. The description correctly implies a no-argument call by framing the tool as a discovery entry point, and adds no misleading input expectations.

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 every auction-data table ALT/FNDATA serves") and immediately adds what each entry carries (live descriptions, column counts). It is unmistakably distinct from siblings like get_table_schema and query_table, which consume the aliases this tool returns.

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 says "Start here whenever a question names a category and you need the right table alias," and names the four downstream tools that consume the output. It also gives the when-not guidance ("Always call this for the current set rather than assuming it") plus concrete trigger examples for discovery-style questions.

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 and openWorldHint, but the description adds real behavioral context beyond them: the read is 'instant, no scan' (precomputed source) and it 'never invents a figure that isn't precomputed,' which tells the agent how to interpret missing results. It stops short of discussing coverage gaps per model or empty-result behavior.

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

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

The purpose and routing guidance are front-loaded ahead of the Args block, and every sentence carries information. Slight redundancy in restating each parameter in prose after the summary paragraph keeps it from a 5.

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?

An output schema exists, so return-value explanation is optional, yet the description still names the useful fields (low/25th/median/75th/high, sample size, trend). Combined with the routing guidance, an agent has enough to invoke correctly; only edge cases like combined query+brand are uncovered.

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

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

Schema coverage is 0% and the schema carries no enum for `category`, so the description must carry the load — and it does, supplying the three valid values, inference-when-omitted behavior, example values for `query`, and the query/brand alternative. It doesn't state what happens if both `query` and `brand` are supplied.

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

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

States a specific verb+resource — 'Precomputed model-level price index' — and immediately characterizes the data source (ALT/FNDATA hot-stats). It explicitly distinguishes itself from market_stats and price_trend by category scope, so an agent can route 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?

Gives explicit selection logic: a typed model `query` for one model's band, a `brand` alone for the whole brand set, and names market_stats or price_trend for categories outside handbags/watches/cars. When-to-use and alternatives are both present.

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 openWorldHint=true, and the description adds meaningful context beyond that: stats are computed server-side over the full matching set rather than a sample, and sold_only=true restricts to sold lots with a positive USD price so results reflect realized transactions. No auth, rate-limit, or cost disclosure, but the sampling and sold-only semantics are genuinely useful behavioral details.

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 and return set are front-loaded, followed by per-argument notes, so the structure is easy to scan. The Args-style block is slightly verbose and the return enumeration is somewhat redundant given an output schema, but nothing is outright 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 3-parameter read-only aggregation with an output schema, the description covers the argument semantics and the key caveat about full-set versus sampled computation. The remaining gap is relational: it never positions itself against market_index or price_trend, so an agent must guess between them.

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 0%, so the description carries the full burden and does so: table is explained with alias semantics ("gems" = loose/unmounted, "jewelry" = finished/mounted, may span both), filters is defined as field/op/value dicts matching query_table with a concrete Patek Philippe example, and sold_only is given its default and effect. All three parameters gain meaning beyond the bare schema.

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

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

The first sentence states a specific verb and resource — summarize the realized-price market for a table or filtered segment — and the return list makes the output concrete (count, median, percentiles, min/max, vendor ranking). It does not explicitly distinguish itself from sibling aggregators such as market_index or price_trend, which an agent would still need to disambiguate.

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

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

It gives a prerequisite ("call list_tables first") and explains when to pick "gems" versus "jewelry" and that a loose-stone question can span both, which is real usage context. However, it never says when to use market_stats instead of market_index, price_trend, or price_check, leaving the biggest selection question unanswered.

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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds genuinely non-derivable behavior — the realized-price range plus confidence plus source-linked comps, and the deliberate exclusion of loose stones and jewelry because under-specified colored stones give unreliable medians. The remaining detail (exact output shape) is carried by the output schema, so it doesn't need restating.

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?

Purpose, input alternatives, and the sibling boundary are all front-loaded in the first two paragraphs, and the exclusion caveat earns its space. The Args block partially duplicates the input schema but adds the missing category enum and example formatting, so the redundancy is mostly justified rather than padding.

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 an output schema present and annotations covering the read-only/open-world profile, the description only needed to explain inputs, routing, and limitations — all of which it does, including the category-coverage caveat. The one real hole is edge-case behavior when both or neither of description and lot_url are provided, on a tool where all three params are optional.

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 0%, so the description must carry the load, and it largely does: it explains the description/lot_url tradeoff, gives a concrete free-text example with brand/model/material, and supplies the category enum values ("handbags", "watches", "cars") plus an inference rule when omitted — none of which appears in the schema. It stops short of saying what happens when both description and lot_url are supplied, or when neither is.

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 ("Estimate a single item's fair-value range from comparable auction sales") and immediately distinguishes itself from the sibling market_stats ("Best for valuing ONE specific piece; for a whole-market read use market_stats"). An agent can route between the two 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?

Gives explicit input alternatives (free-text description OR auction-house lot URL), an explicit use-case boundary versus market_stats, and an explicit exclusion with a fallback: gemstones and jewelry are held from comp-matching, so use market_stats on `gems` or `jewelry` instead. This is close to a complete routing rule set.

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 and openWorldHint, so the safety profile is covered; the description adds substantive behavior: the aggregation it performs, the time-bucketing behavior, and that sold_only restricts to sold lots with a positive USD price (default true) – a material effect on results. No auth or rate-limit context, and no note on sparse/empty periods.

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 purpose, then an Args block that is easy to scan. Slightly redundant where it restates defaults already present in the schema (year, true), but those restatements are paired with clarifying semantics rather than pure duplication.

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?

An output schema exists, yet the description still summarizes the returned metrics (per-period sales count, median, average), which is enough for an agent to know what it will get. Combined with the parameter documentation and read-only annotation, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so: it explains the table alias domain (Gems = loose stones, jewelry = mounted), the allowed 'by' values (year/quarter/month) which are absent as an enum in the schema, the filter shape referenced to query_table, and the precise semantics of sold_only. All four parameters gain meaning beyond the bare schema.

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

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

States a specific verb and resource ('Show how realized prices moved over time') and adds the exact computation performed (bucket sold lots by period, report count/median/average usd_price_decimal), which is more than a restatement of the name. It does not explicitly distinguish itself from siblings like market_stats or price_check, leaving the agent to infer the difference.

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 actionable prerequisites ('call list_tables first') and clarifies that filters use 'the same shape as query_table', which steers reuse of a known pattern. It never says when to prefer market_stats or price_check instead, so there is no explicit exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and an output schema exists, so the bar is lower. The description still adds value annotations cannot: the full operator vocabulary for filters, the 20-row default with a hard 500-row cap (the cap is absent from the schema), and the alias semantics for "gems" vs "jewelry". It does not mention error behavior for an invalid table or what happens when a filter references an unknown column.

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 purpose and a use case, then a clean Args block matching the schema order. Slightly long, and the two examples partially overlap (the query example restates filter/sort/limit intent), but nearly every sentence adds distinct information.

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

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

With an output schema present, the description needn't explain return values, and annotations cover the safety profile. For a 7-parameter, 0%-coverage schema the description fully compensates, including nested filter structure and the limit ceiling, leaving nothing an agent needs to call it correctly.

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

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

Schema coverage is 0%, so the description must carry the load and does: every parameter is explained, including the nested filter dict shape with its "field"/"op"/"value" keys, the enumerated operator list, and a concrete filter example. It also supplies the missing max limit and clarifies that `fields` defaults to all columns.

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 and immediately bounds the scope: 'Query one known table'. The worked example (table="watches" with filters, sort, limit) makes the operation concrete, and the described purpose is clearly distinct from the sibling `search` (whole-market) and `market_stats` (aggregates).

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?

Explicit routing is given: use this when the target table is already known from `list_tables`, use `search` when the table is unknown, and use `market_stats` for aggregate figures. Both an inclusion condition and two named alternatives are stated, so no inference is required.

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 only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing tokenization, synonym expansion (ruby↔rubis), the exact fields matched, merge/dedup behavior ranked by top realized USD sales, and the limit ceiling of 100. That is exactly the kind of engine-level behavior an agent cannot infer from structured fields.

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

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

Front-loaded one-line summary followed by mechanics and an Args block, with no filler sentences. Minor redundancy: the intro already explains the no-category fan-out and merge behavior, then the category arg repeats part of it, making it slightly longer than necessary.

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 4-param search tool with an output schema, everything the agent needs to call correctly is present: matching semantics, result merging/ordering, filter syntax, and size caps. Return-value shape is correctly left to the 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 0%, so the description carries the full burden and does so for all four parameters: query examples ('Daytona 116500', 'Birkin 25'), the dual alias/plain-word semantics of category, the AND-ed filter dict shape with a concrete usd_price_decimal gte example, and limit's default 25 / max 100.

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 with explicit scope: 'Whole-market keyword search across every ALT/FNDATA category at once.' The line 'so you don't have to guess which table holds an item' implicitly positions it against the per-table query_table sibling, letting an agent choose without opening the schema.

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

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

Gives clear use context (use when you don't know which table holds an item; omit category to fan out) and explains that category can be a table alias or a plain word, with gemstone hints searching both loose gems and mounted jewelry. It stops short of explicitly naming query_table or price_check as alternatives, so there is no explicit when-not-to-use routing.

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