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 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 declare read-only, idempotent, closed-world behavior, so the description's contribution is the extra context it supplies: a cap of 10 results per model merged by relevance, and the exact result shape including that image_url is an absolute URL or null. Useful and above the annotation baseline, though it doesn't clarify whether the cap is a hard limit with no pagination.

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

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

Purpose is front-loaded in the first clause, the alternative follows, and the return-field list is dense but earns its place since there is no output schema. The field enumeration is long but each token is informative.

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

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

With no output schema, the description usefully enumerates every returned field and the result cap, and it routes to the right alternative. The remaining gap is query semantics (what constitutes a match, language effects), which an agent must guess before calling.

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

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

Schema description coverage is 100% and both parameters (query, language) are documented in the schema, so the baseline is 3. The description adds no search-syntax detail (matching rules, multi-word handling) and never mentions the language parameter's effect on results.

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 at once — and the phrase "at once" plus the explicit contrast with search_sections_semantically separates it from the per-model search siblings and the semantic tools.

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 positive trigger ("when you know a name or keywords and want the objects") and names one alternative with the condition that selects it (answer questions from texts → search_sections_semantically). It does not say when to prefer the narrower search_artworks/search_artists/search_museums/search_articles or search_objects_semantically, so routing among the remaining siblings is still partly 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 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 read-only/idempotent safety profile, and the description goes well beyond them: it enumerates every returned field with its meaning (best_score as cosine of the single best passage, score_sum as summed passages, matched_vectors_count), explains the rank_by tradeoff, notes language handling, and gives the index_unavailable fallback. This is the kind of behavioral context annotations cannot express.

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 key distinction ("OBJECTS, not passages") and every clause carries information. It is a dense single paragraph with heavy dash usage, which slightly hurts scannability, but nothing is redundant enough to cut.

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 documenting the result shape field by field, including the object_pk handoff to get_detail_* tools. Combined with error handling and ranking guidance, an agent has everything needed to call and interpret this tool 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 baseline is 3, but the description adds real meaning the schema lacks: rank_by "score_sum" is explained as favouring objects matching in many passages versus "best_score" for the single closest passage, with the recommendation to use best_score to find the exact work a text is about. It also clarifies that the query can be any language while the underlying texts are English.

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

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

Names the specific verb (semantic search) and the objects returned (artworks, artists, museums, articles), and explicitly contrasts with siblings: "returning OBJECTS, not passages" and "with a name or keywords, use search_fts". An agent can distinguish it from search_sections_semantically and search_fts 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 when-to-use ("when you have a text and want the objects it is about") and two named alternatives with the conditions that select them: search_fts for names/keywords, search_sections_semantically for answering passages. It also provides a recovery path for the index_unavailable error, which is unusually complete routing guidance.

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

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

The annotations already establish that this is a read-only, idempotent, non-destructive search. Beyond that, the description discloses that section_text is never cut, results are packed best-first into about 9,000 characters, sections_omitted_for_size reports additional matches, and index_unavailable has a fallback path.

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

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

The description is dense but front-loaded, leading immediately with the tool's purpose and then layering in models, result fields, alternatives, packing behavior, and error fallback. Every clause carries operational information; there is no filler.

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

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

Although there is no output schema, the description enumerates the result fields and explains packing/truncation via sections_omitted_for_size. It also covers model scope, query style, language behavior, sibling routing, and the index_unavailable fallback, making it complete for this complexity.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description still adds useful meaning: query should be a full sentence and may be in any language, the model types are explained by content, and category_code is limited to articles with Support/Website emphasized for service and policy questions.

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: semantic search over the site's texts, returning sections by meaning rather than shared words. It clearly distinguishes this from search_fts and search_objects_semantically by explaining what each alternative is for.

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 usage guidance: use it to answer a question from what the site's texts say, use search_fts to find a work/artist/museum by name or keywords, and use search_objects_semantically to find the objects a text is about. It also names the index_unavailable error and the correct fallback to full-text tools.

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