AllPaintingsStore Art Search & Quotation

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: the 25-250 cm per-side bounds, what quotation_price does and does not include (option costs live in notes), the >105 cm disassembled frame kit, and the 3-face portrait coverage. It also instructs the agent to hand order_page_url to the user, which is real behavioral guidance. Minor gap: no note on currency or unit-conversion behavior beyond the size bounds.

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 and usage are front-loaded in the first two sentences, and later clauses about frames, sizing, and returns all carry information. It is dense and parenthetical, though, and the frame_code enumeration largely duplicates the already-verbose schema description, which costs some efficiency.

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 contract itself and does so thoroughly, listing quotation_price, currency, frame fields, dimensions, notes, and order_page_url. Combined with the sizing limits and fallback conditions, an agent has everything needed to call it and to communicate 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% and the frame_code property description is already exhaustive, so much of the frame_code and senior_artist wording is restated. The description still earns credit for adding semantics absent from the schema, notably the 25-250 cm per-side limit (schema only enforces exclusiveMinimum 0) and the fact that frame_code/senior_artist prices are folded into quotation_price.

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 verb (price quotation) and resource (a CUSTOM reproduction from a customer-supplied image), and immediately scopes it against the catalog path by declaring 'No artwork identification is needed or accepted'. An agent can distinguish this from get_a_quotation 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?

It names the exact triggers for this tool: search tools returning nothing relevant, get_a_quotation failing with artwork_not_found, or the customer wanting their own picture reproduced. The fallback relationship to the sibling tool is explicit rather than inferred.

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

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

Annotations already establish this is a safe, idempotent, non-destructive read, yet the description goes far beyond them: aspect-ratio snapping with surface area preserved, clamping to the 25–250 cm range rather than failing, invalid_size only when no proportional size fits, fuzzy-match warnings and the returned score, and available_now semantics for objects actually for sale. This is exactly the behavioral context an agent needs before quoting a price to a user.

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 is front-loaded in sentence one, but the body is a dense multi-clause run-on that mixes sizing rules, error codes, field inventories and user-facing advice into two long paragraphs. Most content earns its place given the tool's complexity, but scanning it is hard and some field enumeration (pk, artist_name, title, meta_description...) restates structure.

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 11 parameters, no output schema, and non-obvious resize/adjustment behavior, the description covers everything needed: identification by pk or title/artist_name, unit handling, frame and senior-artist pricing effects, size adjustment signaling, and what to do with available_now. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3; the description still earns above baseline by explaining width/height interactions the schema only hints at (derive the missing side, size_derived_from, ratio adjustment) and by expanding senior_artist into its effect on price and buy_url. frame_code is largely duplicative of its already very verbose schema description, which keeps this from a 5.

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 names a specific verb+resource (price quotation for a reproduction), enumerates the two media (art print vs hand-painted oil), and scopes it by size and currency. It is clearly distinguishable from the sibling get_a_custom_reproduction_quotation and from get_artwork_availability.

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?

Rich conditional guidance: omit type to get both quotations, give only width or only height to pin that side, and a clear rule for when available_now appears versus a quotation. What is missing is explicit routing to the sibling get_a_custom_reproduction_quotation — the agent must infer that a custom request goes elsewhere.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: available_now is true only when the artwork itself can be transacted today, prices are fixed and shipping-inclusive, stock items ship within 48 hours, offer_text must be pasted untouched, and title resolution is surname-guarded with a relevance "score" and a "warning" flag. It also warns that currency follows the strict no-fallback rule of the quotation tools.

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 content is front-loaded and relevant, but it is delivered as one very long em-dash-and-parenthesis-chained sentence covering channels, output fields, availability semantics, triggers, identification strategy, and list mode. The density forces re-reading; splitting into short labeled sentences (channels / when to call / how to identify / list mode) would preserve all information at far lower parsing cost.

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, and the description compensates by naming the key returned fields (available_now, available_now_summary, stock_quantity, price, size, buy_url, offer_text) for each channel type. Combined with the trigger conditions and the two operating modes, an agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the resolution precedence (pk, then exact title, then surname-guarded search) and the meaning of the returned "score"/"warning" values, which the schema does not convey. It also clarifies that channel narrows offers when pk/title is supplied but switches the tool into list mode when they are absent — a semantic distinction the schema only hints at.

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

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

The description states a specific verb and resource — return every purchasable offer for ONE artwork across its sales channels — and enumerates the concrete channel types (ready-made stock, auction lot, owner original, studio collectible, reproduction, print, digital licence). It explicitly separates itself from the made-to-order pricing path by naming get_a_quotation as the tool for size-based print/reproduction prices, so an agent can distinguish it from siblings 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?

It gives explicit trigger conditions: call whenever a customer asks about availability, stock, ready-to-ship, discount, auction, or real-object price, and specifically before any "yes, it is available". It also defines the alternate invocation mode (no pk or title → list mode by channel) with example utterances, and routes made-to-order pricing to get_a_quotation.

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?

Goes well beyond the readOnly/idempotent annotations: it enumerates the exact return fields, names the 'links' payload and its three variants, discloses the article_not_found outcome, and documents the 25000-character cap with the 'truncated' flag. That is exactly the kind of behavior an agent needs before calling.

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 purpose and prerequisite, then the return contract, then error and truncation semantics — each sentence adds a distinct fact with no filler. Dense but never 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 full burden of explaining return values and it does so completely: field list, related-link contents, error case, and size cap. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents pk and language, making 3 the baseline. The description reinforces that pk identifies one article but says nothing about the language parameter or its defaulting behavior, so it adds little on top of the schema.

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

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

States a specific verb and resource ('Full data of ONE article identified by pk') and scopes it to a single record, which cleanly separates it from the search_articles / search_article_sections siblings. Capitalized 'ONE' removes any ambiguity about single vs. list semantics.

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

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

Explicitly tells the agent to 'use a search tool first to find the pk', which is the key prerequisite for a detail-by-id tool. It stops short of naming search_articles specifically and gives no when-not-to-use guidance, but the routing intent is clear.

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

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

Goes well beyond the annotations by enumerating the exact returned fields, documenting the artist_not_found failure case, and disclosing the 25000-character cap with a 'truncated' flag. That truncation behavior is the kind of non-obvious trait an agent cannot infer from readOnly/idempotent hints.

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

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

Front-loaded with the core action, then the return contract, then the error and truncation caveats in a single dense block. Every clause carries information an agent would otherwise have to discover by trial.

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 return-value burden alone and does so thoroughly: field list, link list, error token, and size cap. Nothing essential for calling this correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema and baseline 3 applies. The description reinforces that pk identifies a single artist and must come from a search tool, but never mentions the 'language' parameter or its default behavior, adding little beyond the schema.

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

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

States a specific verb and resource ('Full data of ONE artist identified by pk') and makes the scope explicit with "ONE" and the identifier. An agent can distinguish it from search_artists and from get_detail_artwork 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 a clear prerequisite: 'use a search tool first to find the pk', which routes the agent to the search siblings when it lacks an identifier. It does not explicitly state when to prefer this over get_detail_artwork or the other get_detail_* tools, but the resource specificity makes the choice obvious.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds far more: an enumerated return payload, the conditional 'only for channels on sale' link, the null-when-unknown museum case, the artwork_not_found error, and a concrete 25000-character cap with a 'truncated' flag. That is exactly the behavioral detail an agent needs before calling.

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 identity and return contract, with no filler sentences. The parenthetical enumerations of link types are dense but each carries actionable meaning, though the prose is slightly heavy.

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 fully specifies the return shape, error condition, truncation behavior, and null cases. An agent knows what it will get and when it will be cut off, so nothing material is missing for a simple two-parameter reader.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description only reinforces how to obtain pk. The language parameter's effect on the returned url and links is never mentioned in the description, leaving its observable impact to inference.

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 scope: 'Full data of ONE artwork identified by pk'. The all-caps ONE plus the sibling set (search_artworks, get_detail_article, etc.) makes it immediately clear this is the single-object detail read, not a search.

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

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

'use a search tool first to find the pk' gives an explicit prerequisite that routes the agent to the search_* siblings before calling this. It stops short of naming a specific search tool or stating when not to use this reader, so it falls just short of full alternative coverage.

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?

Beyond the read-only and non-destructive annotations, the description discloses the returned fields, the five-link limit, the museum_not_found outcome, and the 25000-character cap. It also explains that truncated is true when description_html is shortened, giving the agent valuable response and edge-case context.

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 front-loads the operation, scope, and prerequisite, then efficiently covers output contents and exceptional behavior. Although dense, its field list and limits are useful rather than redundant, especially because there is no output schema.

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

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

For a simple two-parameter read operation, the definition supplies everything needed to select and invoke it and interpret important outcomes. The detailed return-field, not-found, and truncation information compensates well for 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%, so the baseline of 3 applies. The description's pk and search-tool guidance largely repeats the schema's pk documentation, and it adds no further meaning for language beyond what the schema already supplies.

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

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

The description clearly states that the tool retrieves full data for one museum identified by its pk. Emphasizing "ONE museum" distinguishes it from search tools, while the museum resource differentiates it from sibling detail tools for articles, artists, and artworks.

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 instruction to "use a search tool first to find the pk" provides an explicit prerequisite and workflow. It would be stronger if it named search_museums specifically or stated when not to use this detail tool, but the intended selection context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is in disclosing the result shape: pk, title, url, absolute image_url with its null case, category_code, meta_description and a relevance score. That is meaningful behavior beyond the annotations, though ranking/tie-breaking behavior and result caps context are not explained.

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 operation and its filter, followed by the return contract. No redundant or filler wording.

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

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

With no output schema, the description compensates by enumerating returned fields and the null-image case, and the schema fully documents all four inputs. Remaining gaps are matching semantics (AND/OR, stemming) and ranking behavior, which are minor for a bounded top-10 search.

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 defines query, limit, language and the category enum. The description only echoes the optional category filter and the notion of full-text matching, adding little syntax or format detail beyond the structured data.

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

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

The description names a specific verb and resource ('Full-text search of website articles') plus the optional category filter, so the operation is unambiguous. It does not differentiate itself from close siblings such as search_article_sections or search_fts, which is the only thing keeping it from a 5.

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

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

'Full-text search' implies keyword-based lookup rather than the semantic or section-level siblings, but no alternative is named and no condition for preferring one over another is given. 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: sections are returned whole and never truncated, results are ranked by cosine score where higher is closer, output is packed best-first into ~9,000 characters, and sections_omitted_for_size signals additional matches. It also names the one error condition and its remedy.

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 and return shape lead, alternatives and error handling follow — well front-loaded with no filler sentences. It is densely packed with parentheticals and reads as one long block, which slightly hurts scannability but not content value.

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 full burden of explaining returns, and it does: every returned field is enumerated, the ranking metric is defined, and the character-budget/omission behaviour is disclosed. Combined with the error fallback, an agent has everything needed to call this correctly and interpret 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 description coverage is 100%, so a 3 is the baseline, but the description adds real meaning: query should be a full sentence, the query may be in any language while passages are English, and language refers to site language rather than query language — a distinction the schema alone does not make clear. Category filtering guidance is left to the schema, which already covers it well.

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 ("Semantic search of the passages of our articles") plus the return unit ("article sections that answer the question best"), and explicitly distinguishes two siblings: search_articles for listing articles on a subject, and search_sections_semantically via the models=["article"] equivalence. An agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use ("ground an answer in what our articles say") with concrete example domains, an explicit alternative ("use search_articles to list articles on a subject"), and a failure path ("Error index_unavailable: fall back to search_articles"). It even prescribes input shape ("Ask in a full sentence") and notes any language is accepted.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real context beyond them: the exact alive_in_year interval rule including the 80-year fallback when the death year is unknown, and the fact that image_url is an absolute URL that can be null. It says nothing about result ordering or relevance scoring, which keeps it from a 5.

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

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

Two sentences, front-loaded with the core action and filters, then the return shape. Every clause carries information (filter semantics, fallback rule, nullable image URL) with no filler.

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

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

For a six-parameter search with no output schema, the description covers the action, the filterable dimensions, the tricky filter's exact semantics, and enumerates the returned fields including the nullable one. An agent has everything needed to call it and interpret 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%, so the baseline is 3, and the description genuinely earns above that by explaining alive_in_year as 'born <= year <= died, or born + 80 years when the death year is unknown' — a semantic the schema does not contain. The city/country/query/limit parameters are only restated at the level the schema already provides.

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

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

States a specific verb and resource ('Full-text search of artists') plus the searchable fields (name, biography) and the narrowing filters, which is far beyond a restatement of the name. It stops short of naming a sibling such as get_detail_artist for single-record lookup, so the boundary with siblings is left 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?

Usage is implied by 'full-text search' versus the get_detail_* siblings, and the optional filters suggest a discovery workflow. However, there is no explicit statement of when to prefer this over get_detail_artist or search_fts, and no exclusions or prerequisites 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavior: results are filtered to 'good-confidence matches' only, and it enumerates the returned fields including the null-when-absent image_url and a relevance score. It does not explain how confidence is determined or how relevance is ranked, which keeps it short of a 5.

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

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

Two sentences, no filler. The search scope is front-loaded and the return contract follows, with the image_url null case handled inline in parentheses.

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

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

With no output schema, the description carries the return-value burden and does so by naming every field returned. Combined with complete parameter documentation, an agent has what it needs to call and interpret it. The only gap is that ranking/confidence semantics are asserted but not explained.

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 query, limit and language are already fully documented in the schema, including the 1-10 limit bound and the default language. The description restates the query scope (title, artist name, description) without adding syntax, matching behavior, or language-code guidance 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 ('Full-text search of the artwork catalog') plus the fields searched (title, artist name, description), which clearly separates it from the get_detail_* siblings. It does not, however, distinguish itself from search_objects_semantically, which is the closest alternative for the same resource.

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

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

Usage is only implied: calling it a 'full-text search' suggests keyword lookup, but there is no explicit statement of when to prefer this over search_objects_semantically or when to go straight to get_detail_artwork. No prerequisites or exclusions are given.

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

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

Annotations already cover read-only, idempotent and closed-world behavior, so the description's job is to add operational detail - and it does: a hard cap of 10 results per model, relevance-based merging across models, and explicit null handling for image_url. It stops short of describing ranking behavior or whether results can be paged beyond the cap.

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 search scope and cap, then the result shape. The field enumeration is long but earns its place since there is no output schema.

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

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

With no output schema, listing the returned fields - including pk, model and score - is genuinely needed and is supplied. What is missing is context about result limits and pagination past the 10-per-model cap, which matters for an agent planning a retrieval strategy.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description does little beyond confirming that the query spans all four catalogs. It adds no meaning to 'language' (e.g. whether it affects matching or only displayed labels), so the baseline 3 holds.

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 ('full-text search across artworks, artists, museums and articles') plus the scope that separates it from the single-catalog siblings like search_artworks or search_artists. An agent can immediately tell this is the cross-catalog variant.

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 once' implies this is the broad sweep versus the per-model search_* tools, but the description never explicitly says 'use search_artworks when you only want artworks' or when to prefer search_objects_semantically. Usage is inferable rather than stated.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the description only needs to add operational context. It does: results are filtered to good-confidence matches only, and the return shape is enumerated, including the non-obvious 'image_url is null when there is none' rule.

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, no filler. The core operation and narrowing options come first, and the return contract follows. Every clause carries information an agent would otherwise have to guess.

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

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

There is no output schema, so the description rightly spends its second sentence on the returned fields. The good-confidence filter and null-image rule are the kind of details an agent cannot get elsewhere. Only the absence of any sibling routing keeps it below 5.

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 query, city, country, limit and language are all documented in structured fields. The description reinforces the narrowing semantics of city/country but adds nothing for limit (max 10) or language, 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 ('Full-text search of museums by name') plus the narrowing dimensions, so an agent knows exactly what is retrieved. It does not distinguish itself from siblings like get_detail_museum or search_fts, which is the only thing keeping it from a 5.

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

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

'Optionally narrowed by city and country' implies the search-widening usage pattern, but there is no explicit when-to-use statement and no mention of the alternative (get_detail_museum for a known museum, search_fts for broader text search). The agent must infer the routing.

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, idempotent, non-destructive), yet the description adds substantial extra behavior: the exact shape of each result item, what best_score and score_sum actually measure, the matched_vectors_count meaning, and the 'any language query works even though texts are English' quirk. It also discloses the index_unavailable error and the recovery route, which is the kind of operational detail annotations never carry.

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 objects-not-passages distinction is front-loaded, and the result-field enumeration and error advice each earn their place. Sentences are long and dash-heavy, making it denser than it needs to be, but no clause is 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 no output schema, the description takes on the return-value burden itself and does so completely — result fields, scoring semantics, and the error case are all covered. For a 5-parameter read-only search with full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description nonetheless adds real meaning by explaining the tradeoff between the two rank_by modes in retrieval terms (many matching passages vs one closest passage) rather than restating the enum. It also reinforces that object_pk feeds the matching get_detail_* tool, linking parameters to downstream calls.

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 ('semantic search') and a precise resource set (artworks, artists, museums, articles), and immediately draws the boundary against the sibling search_sections_semantically by declaring it returns OBJECTS, not passages. An agent can route between the two semantic tools 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 concrete selection guidance — use rank_by='best_score' to find the exact work a text is about, default 'score_sum' when many passages match — and names a fallback path to the search_* full-text tools on index_unavailable. It does not explicitly state when to prefer this over search_sections_semantically beyond the objects-vs-passages framing, so it stops short of the top score.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description layers on substantial behavior: sections are returned whole and never truncated, results are packed best-first into ~9,000 characters, sections_omitted_for_size reports overflow, and score is cosine similarity. It also names an error condition and its fallback, which annotations never convey.

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 and scope are front-loaded, and essentially every clause carries information an agent needs. It is a dense, semicolon-chained single block rather than structured prose, which slightly hurts scannability, but there is little true 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?

Though no output schema exists, the description enumerates the returned fields (model, object_pk with its downstream get_detail_* usage, object_title, object_url, category_code, section_heading, section_text, is_faq_question, score). Combined with the size-packing and error notes, an agent has everything needed to call and interpret it.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning: the model names are glossed (article = how reproductions are made, policies, art history; artist/artwork = biographies and descriptions), and category_code is explained as article-only with Support/Website flagged for service and policy questions. It also clarifies the query should be a natural-language question.

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 ("semantic search of the texts of our site") and immediately distinguishes itself from keyword search ("by meaning rather than shared words"). It enumerates the searched models (article/museum/artist/artwork) so an agent can tell it apart from siblings like search_articles or search_objects_semantically.

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 usage conditions: ask in a full sentence, any language works while texts are English, default is all indexed models, and on the index_unavailable error fall back to the search_* full-text tools. It does not explicitly contrast with search_objects_semantically or search_article_sections, so a sibling-differentiation gap remains.

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