Provenio — Art Intelligence

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

Annotations indicate readOnlyHint=true and destructiveHint=false, but the description adds significant behavior: cost variable, auth forwarding via x-byok-auth header, allowed hosts restriction to HTTPS public URLs (no internal IPs), return format {status, body, headers, fetched_at, source_url}, logging, and no caching. No contradiction found.

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 structured with bullet points and front-loaded with the core action and cost. It is slightly verbose but every sentence adds value. Could be slightly tighter.

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

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

Given the complexity of a proxy-to-external-API tool, the description covers purpose, usage, auth, security constraints, return format, and data handling. No output schema, but return structure is described. Complete and actionable.

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% (all 4 parameters have descriptions). The description does not add detailed semantics beyond the schema for each parameter, but it does explain auth context and allowed hosts. Baseline 3 is appropriate.

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

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

The description opens with 'Forward a JSON HTTP request to YOUR own external API endpoint and return the response', clearly stating the verb (forward), resource (external API), and scope (to user's own endpoint). This distinguishes it from sibling tools like 'fetch' and 'lookup_*' which query internal sources.

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 states 'Use when: you need to query a third-party art-market source (Artnet/Artprice/your own gallery DB) that we do not host.' This guides when to use. It does not explicitly list when not to use or alternatives, but the sibling tools imply internal sources.

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 safety traits (readOnly, idempotent, not destructive). Description adds performance cost (~4s) and detailed return structure, enriching transparency without contradiction.

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?

7 well-organized sentences, front-loaded with cost and purpose, no fluff. Bullet-like structure for use cases enhances readability.

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?

Despite no output schema, description fully explains return content. Annotations cover safety. Combination of cost, use cases, and return details makes it complete for this moderate-complexity tool.

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% with clear parameter descriptions. Description adds extra guidance for artist_id_2 to use a well-documented historical benchmark, improving semantics beyond 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?

Description clearly states it compares career patterns of two artists and returns structured comparison data. It distinguishes from siblings by mentioning alternatives: get_career_trajectory for single artist, find_emerging_artists_by_pattern for discovery.

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

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

Explicit 'Use when' scenarios for pitching emerging artists or curatorial narrative evidence, plus 'Do NOT use when' with specific alternative tools, providing excellent 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?

Adds context beyond annotations by specifying return structure ({id, title, text, url, metadata}) and that text is a readable summary. Annotations already declare read-only and idempotent nature.

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 core purpose and return structure, no wasted words.

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

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

With an output schema and simple single-param input, the description covers all needed context: what the tool does, what it returns, and how it relates to underlying tools.

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

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

Schema coverage is 100%, but description adds examples of id format and reinforces that id comes from search, providing extra clarity beyond the schema description.

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 it fetches a full Provenio record for an id from search, specifies id format (person:… or artwork:…), and distinguishes from siblings by noting it wraps get_artist/get_artwork.

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

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

Explicitly says to use after search. Implicitly suggests it's the proper way to retrieve full records from search ids, though doesn't explicitly state when not to use it.

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 (readOnlyHint, idempotentHint, destructiveHint) already declare the tool's safety profile. The description adds the cost ('Cost: ~2s') and the output nature ('Comparable set'), but does not fully describe behavior like pagination, ordering, or response structure. With annotations covering the core traits, the description adds moderate 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?

Two concise sentences front-loaded with cost and purpose. Every word earns its place; no fluff.

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

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

Given the complexity (8 params, two modes, no output schema), the description is fairly complete. It explains the two modes, mutual exclusivity, and usage boundaries. However, it does not describe the return format or what 'peer artists' means, leaving minor gaps.

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

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

Schema description coverage is high (88%). The description adds value by explaining the mutual exclusivity between artwork_id and artist_id, and that some parameters apply only in artwork_seed mode. This goes beyond the schema's individual param descriptions.

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 the tool finds a 'comparable set' of artworks or peer artists, with two distinct modes based on seed IDs. It distinguishes itself from sibling tools by explicitly naming what it does and what it does not do.

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

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

The description provides explicit when-to-use guidance: 'EITHER artwork_id seed → similar works, OR artist_id seed → peer artists.' It also tells when not to use: 'Not for same-artist lot history (use search_auction_history).' This clearly directs the agent to the correct context.

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 indicate the tool is read-only, idempotent, and non-destructive. The description adds valuable behavioral context: estimated cost (~3s), a coverage dependency on exhibition data, and the return format (ranked candidates with confidence score, exhibition/market data, and signal summary). This goes beyond the annotations but still lacks details on pagination or error handling.

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 well-structured: it starts with the cost and core purpose, then lists patterns, then provides usage scenarios. While it is somewhat lengthy with multiple bullet points, each line adds necessary information. The structure front-loads the most critical information.

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

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

The tool has no output schema, so the description must explain what is returned. It does so clearly: ranked candidates with confidence score, exhibition/market data, and signal summary. It also notes a dependency on ingested exhibition data and explicitly states that artists without exhibition records won't appear. This covers the essential context for the agent to use the tool appropriately.

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%: all 4 parameters have descriptions in the schema. The description repeats the pattern codes but does not add new semantic detail beyond what the schema provides. Therefore, the description does not significantly enhance parameter understanding.

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 uses the specific verb 'Discover' and the resource 'emerging artists whose current KG footprint matches a historical career pattern'. It lists five distinct patterns, making the tool's scope clear. The description distinguishes this tool from siblings by providing explicit do-not-use conditions that name alternative tools (get_career_trajectory and compare_career_patterns).

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

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

The description provides three explicit 'Use when' scenarios (gallery shortlist, curator thematic exhibition, collector discovery) and two 'Do NOT use when' scenarios with named alternatives. This provides comprehensive guidance on when and when not to use the tool, directly assisting the agent in selection.

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

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

Annotations already declare read-only/idempotent. Description adds cost (~1s), return ordering, and specific fields, providing value beyond the annotations.

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

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

Concise at ~70 words with clear bullet-like structure. Each line serves a purpose, though minor redundancy could be trimmed.

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 tool with no output schema, the description explains the full return structure (ordering, fields). Missing pagination details, but otherwise complete for the tool's purpose.

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

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

Schema coverage is 100%, both parameters are described in schema. Description briefly mentions include_former in return context but does not add new semantics beyond what the schema 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?

The description clearly states it finds all galleries representing a specific artist, with ordering and fields. It distinguishes from sibling tools like search_galleries (general gallery search) and get_gallery_artists (from gallery perspective).

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?

Three explicit 'Use when' statements provide clear context for when to use this tool. It implies usage scenarios but lacks explicit 'when not' or direct alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the estimated cost (~1s) and the composite nature of the response, which goes beyond annotations. No contradictions.

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 highly concise—two sentences plus usage guidance—without any fluff. Key information (cost, purpose, usage) is front-loaded, and every sentence serves a purpose.

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?

Despite having no output schema, the description clearly outlines what the tool returns (identity, reception, influence, education, market aggregates) and notes that a single call usually suffices. This is sufficient for a read-only tool with one required parameter.

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

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

Schema coverage is 100%, and the schema already provides a detailed description of the artist_id parameter. The description does not add additional parametric information, so baseline 3 is appropriate.

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

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

The description clearly states it is a composite artist profile including identity, reception, influence, education, and market aggregates. It distinguishes from siblings by specifying that a single call usually suffices and warns against using get_influence_network or query_market_summary for different needs.

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 states when to use: when you have an artist ID and need their full picture. Also provides clear when-not-to-use conditions: do not chain with get_influence_network unless depth > 1, and do not use for multi-artist comparison—use query_market_summary instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds cost (1s), behavioral advice (single call sufficient), and composition details, going beyond annotations.

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

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

Three sentences, front-loaded with cost and summary. Every sentence adds value with no redundancy. Highly efficient.

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

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

Given a single required parameter and no output schema, the description covers what data is returned and usage context. Could mention result size or pagination, but the current completeness is strong.

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 schema already describes artwork_id. The description adds format clarity ('slug or full ID'), which provides additional meaning 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?

The description clearly states the tool returns a composite artwork profile including metadata, Panofsky subjects, reception, custody, polity, and transactions. It distinguishes from sibling tools like get_provenance_chain by noting it usually suffices alone.

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 states when to use ('when you have an artwork ID') and when not to chain with get_provenance_chain unless gap-risk flags are needed. Provides clear alternatives and context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds operational context like cost (~2s) and details on output components (stages, patterns, comparable artists), which go beyond annotations.

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

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

Description is well-structured with bullet points for stages and patterns, and front-loads cost and purpose. Could be slightly more concise but effectively communicates necessary details.

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

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

Given the complexity (multiple stages, patterns, comparables) and absence of output schema, the description thoroughly explains what the tool returns and the context for its use. No gaps remain.

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%, but the description adds meaning by noting 'set false to reduce latency' for include_comparables, which helps the agent understand the trade-off.

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 it performs 'Artist career trajectory analysis' providing milestones, career stage, pattern detection, and comparable artists. It distinguishes from sibling tool get_artist by specifying what it should not be used 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?

Explicitly lists use cases (emerging artist discovery, gallery acquisition decisions, curator narrative building) and provides a clear exclusion ('Do NOT use for purely biographical queries — use get_artist instead.').

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?

Description adds significant behavioral detail beyond annotations: cost, fallback from normalized table to knowledge graph, coverage numbers, and return of coverage_gaps and suggested_next_tools. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint false).

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?

Description is moderately detailed with each sentence serving a purpose (cost, purpose, fallback, coverage, edge case handling). Slightly verbose but well-structured and front-loaded.

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

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

Given two mutually exclusive parameters, no output schema, and complex fallback behavior, description covers main functionality, edge cases (missing data), and return fields. Slight gap: no output structure description, but compensated by listing returned elements.

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 provides 100% description coverage for both parameters, including mutual exclusivity. Description repeats this without adding new meaning or format details.

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?

Description clearly states it retrieves exhibition history for an artist or artwork, with specific verb 'get' and resource 'exhibition history'. It differentiates from siblings like 'get_artist' by specifying it is a single call for exhibition-specific data.

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?

Implied usage: use for exhibition history. Includes cost and coverage but no explicit when-not-to-use or alternatives. Does not directly guide against using other tools for similar artist data.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds cost (~1s), return structure (gallery metadata + ordered list with fields), and implies a predictable safe operation. No contradictions.

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?

Four sentences, each with a distinct purpose: cost, purpose, return, usage rules. Front-loaded with key info. No fluff.

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?

Despite no output schema, the description fully explains the return value: gallery metadata and an ordered artist list with exclusivity, period, notes. The cost hint and usage guidelines make it self-contained.

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% with clear descriptions for both parameters. The description repeats that gallery_id is required and include_former defaults to true but adds no new semantic information 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?

The description clearly states the verb 'Get' and the resource 'represented-artist roster for a specific gallery'. It distinguishes from sibling tools like find_galleries_by_artist, which does the reverse.

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 provides two 'Use when' scenarios (pitch context, validating overlap) and a 'Do NOT use when' condition with an alternative tool. This leaves no ambiguity.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds cost (~2-3s) and a warning about combinatorial cost for depth>3. No contradictions. This adds meaningful behavioral context beyond annotations.

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

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

Two sentences, front-loaded with cost and purpose. Every word serves a purpose; no fluff. Ideal conciseness.

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

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

Given the tool has 3 well-described parameters, annotations covering safety, and no output schema, the description is sufficient. It explains the BFS nature and direction options. A minor gap is lack of output structure, but overall complete enough.

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 does not add significant meaning beyond the parameter descriptions in the schema. The cost warning for max_depth is helpful but minor. Hence score 3.

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

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

The description clearly states the tool performs 'N-hop influence BFS', specifying the verb and resource. It distinguishes itself from the sibling 'get_artist' by noting that tool already handles 1-hop, giving clear scope.

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 instructs 'Use ONLY when depth>1 needed — get_artist already has 1-hop.' This provides a precise condition for use and names the alternative tool, meeting the highest standard.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds 'Cost: ~1s' and clarifies it returns a formal cluster, adding value beyond annotations.

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

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

Two sentences, front-loaded with cost, then purpose, then alternative. No wasted words.

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

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

Given no output schema, the description could hint at the return type (e.g., list of people). However, it provides enough context for a simple retrieval tool with clear purpose and alternatives.

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 parameters are fully documented in schema. The description does not add additional meaning beyond what is in the schema (e.g., format constraints or examples).

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 the tool retrieves a formal teacher/student cluster for academic lineage, distinguishing it from the sibling get_influence_network for conceptual influence. The verb 'get' and resource 'lineage cluster' are specific.

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 states 'Use for academic lineage' and directs to 'get_influence_network' for conceptual influence, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context: estimated cost (~0.5s), the effect of cross_tradition=true with an example ('lotus↔rose'), and the note 'SINGLE CALL USUALLY SUFFICIENT'. No contradictions.

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?

Extremely concise: four sentences, each serving a distinct purpose. Front-loaded with cost and core output. Bold emphasis on 'SINGLE CALL USUALLY SUFFICIENT' draws attention. No wasted words.

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

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

For a read-only query tool with 3 params and no output schema, the description adequately covers usage, behavior, and key parameter details. It mentions the output type. Minor missing details about the exact structure of 'concept node', but not critical for selection.

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 adds value by giving concrete examples for concept_id (e.g., 'period-dutch-golden-age') and explaining cross_tradition with the analogy example, which clarifies the parameter's purpose beyond the schema description.

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 returns 'Concept node + linked artworks' and is for 'definitional context or iconography cluster'. It distinguishes from sibling tool 'search_artworks' by explicitly saying 'Do NOT use for artwork filters — use search_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?

Provides explicit 'Use when' and 'Do NOT use' guidance, including a specific alternative tool ('search_artworks'). The description also notes that a single call usually suffices, guiding efficient usage.

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 indicate readOnly, idempotent, not destructive. The description adds cost (~1s) and specific flag types (Nazi, colonial, etc.), providing additional behavioral context beyond the annotations. However, it does not detail the output format beyond 'timeline + flags.'

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 concise sentences with no wasted words. The most critical information (cost, purpose, usage context) is front-loaded.

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 tool with 3 parameters and no output schema, the description covers purpose, usage, cost, and output type (timeline + flags). It could be more explicit about the structure of the returned timeline, but given the context of deep due diligence and the specific flags mentioned, it is largely complete.

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

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

Schema descriptions cover 100% of parameters (artwork_id, period_end, period_start). The tool description does not add further meaning beyond what is already in the schema, so the baseline of 3 applies.

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

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

The description clearly states it provides a custody timeline with gap-risk flags for specific historical contexts (Nazi, colonial, Russian Rev, Knoedler). It distinguishes itself from get_artwork by specifying it's for deep due diligence, while get_artwork has basic custody.

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

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

Explicitly says 'Use only for deep due diligence — get_artwork already has basic custody,' giving clear guidance on when to use this tool versus the sibling tool get_artwork.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds performance cost ('~1s') and ordering behavior ('time-ordered'), which are helpful beyond annotations. No contradictions.

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

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

Three short sentences with no waste. Front-loaded with cost metric, then purpose, then usage guidance. Efficient and easy to parse.

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

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

Given the absence of an output schema, the description does not explain return structure, but for a query tool with robust annotations and clear parameter guidance, it covers the essentials. Could elaborate on 'reception claims' but not critical.

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% with clear descriptions for both parameters (artist_id, artwork_id). The description does not add new parameter-level information beyond what the schema provides, so baseline score is appropriate.

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

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

The description clearly states the tool returns 'time-ordered reception claims for artist or artwork', using specific verb and resource. It distinguishes from sibling 'query_reception_price_correlation' by noting its exclusive use for pricing needs.

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

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

Explicit guidance on when to use this tool ('valence-shift narrative') and when to use an alternative ('if you also need price, use query_reception_price_correlation'). Clear and actionable.

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

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

Adds cost (~0.5s), source info, and return format. Annotations already indicate read-only and non-destructive, so description complements without contradiction.

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 key info (cost, purpose), every sentence adds value, no waste. Compact but comprehensive.

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, description fully specifies return shape and fields. Covers auth, source, and typical usage.

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 description provides example queries and default/max for limit, adding context beyond schema.

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

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

The description clearly states it searches the Europeana cultural heritage corpus for art records, specifying verb, resource, and scope. It distinguishes from siblings like lookup_wikidata_art and lookup_met_museum.

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 states when to use: triangulating against European museum holdings or finding object records with images. Mentions alternative method (byok_external_query for high-volume), but does not detail when not to use.

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

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

Adds value beyond annotations by noting cost (~0.3s), dual return formats, source URL, and privacy note. No contradictions with readOnlyHint and other annotations.

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

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

Description is well-structured with line breaks and concise sentences. Includes cost, usage, return format, and source without being verbose.

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?

Adequately covers the dual behavior (search vs dereference) and return types. Despite no output schema, the description explains both possible return structures sufficiently.

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 has 100% description coverage, so baseline is 3. Description adds little beyond schema for individual parameters, but it contextualizes the overall dual-mode behavior.

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?

Clearly states it searches the Met collection and optionally dereferences an objectID, distinguishing it from similar lookup tools like lookup_europeana by specifying the museum source.

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?

Provides explicit use cases: 'when you need a museum-confirmed match' or 'triangulate Provenio data'. Does not explicitly exclude uses but implies context sufficiently.

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 provide readOnlyHint and destructiveHint. The description adds valuable behavioral context: cost (3-8s), public no auth, raw SPARQL JSON results, source URL, and a 12-second timeout. This goes beyond the annotations.

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

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

The description is concise and front-loaded with cost and purpose. Every sentence adds value, with no redundant information. It uses bullet points and clear 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?

Given no output schema, the description explains the return format ({total, bindings: [...]}) and includes timeout and source. It could mention error handling or rate limits, but overall it is complete for the tool's 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 coverage is 100%, so the schema already documents the parameter. The description does not add new meaning beyond stating 'pass a SPARQL query string' and referencing the example already in the schema. Baseline 3 is appropriate.

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

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

The description states 'Run a SPARQL query against Wikidata for art-related entities,' with a specific verb and resource. It clearly distinguishes itself from sibling tools like lookup_europeana and lookup_met_museum by targeting Wikidata specifically.

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

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

The description explicitly states when to use: 'when you need cross-museum location data for an artist's works, or biographical data not in Provenio.' It does not explicitly state when not to use, but the context of sibling tools provides implicit differentiation.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds cost (~2s) as extra behavioral context. No contradictions.

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

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

Three concise sentences, front-loaded with purpose and cost. Every sentence earns its place; no wasted words.

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

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

For a read-only aggregate tool with no required parameters and high schema coverage, the description provides sufficient context: purpose, usage guidelines, cost, and alternatives.

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 83%; description does not add new parameter details beyond the schema. The mention of 'market aggregates × reception × polity' aligns with parameters but adds no new info.

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 it provides 'Per-artist market aggregates × reception × polity' for cross-artist comparison, distinguishing it from siblings like get_artist and search_auction_history.

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

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

Explicitly says when to use ('Use for cross-artist comparison') and when not to ('Single artist deep profile: get_artist. Individual lots: search_auction_history').

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds a performance cost hint (~2s) but does not elaborate on other behavioral aspects. With annotations covering safety, a score of 3 is appropriate.

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 very concise: two sentences and a cost hint, all front-loaded. Every sentence adds value with no fluff.

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

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

Given the tool has 3 parameters with good schema descriptions and annotations covering safety, the description provides the core context (polity-origin artworks dispersed), use case, and alternative. No output schema exists, so return values are not expected. Minor missing details like pagination are not critical for this purpose.

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 three parameters with descriptions. The tool description does not add any additional parameter semantics beyond what the schema provides. Baseline is 3.

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

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

The description clearly states the tool queries polity-origin artworks that are now dispersed, using specific verb 'query' and resource 'polity-origin artworks'. It also distinguishes from sibling tool 'search_artworks' by noting 'For simple list: search_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 description explicitly says 'Use for restitution/cultural-heritage analysis' and provides an alternative tool ('For simple list: search_artworks'). However, it does not explicitly state when not to use it or list other alternatives.

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

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

Annotations already indicate read-only and idempotent. Description adds latency (~2s) and notes it combines two functions, which is useful beyond annotations.

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

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

Two sentences, front-loaded with timing and summary, no wasted words.

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, and description doesn't explain return format. For a simple tool, it's adequate but could mention correlation output.

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% with clear description for artist_id. The description does not add extra parameter semantics 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?

The description clearly states the tool combines reception arc and price trend for one artist, which is specific and distinct from siblings like get_reception_arc.

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 implies usage for a single artist, but lacks explicit when-to-use vs. alternatives. The mention of combining two calls gives context.

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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about ranking and wrapping but no additional behavioral traits such as rate limits or pagination. The description adds some value beyond annotations.

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

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

Description is two sentences plus a parenthetical. It is front-loaded with the action and target, contains no wasted words, and is appropriately sized for the tool's simplicity.

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

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

Given the simple single-parameter search with an output schema, the description covers what the tool does, what it returns (id/title/url), how to use results (pass id to fetch), and its role as a wrapper. Complete for the tool's 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 has one parameter 'query' with a clear description (free-text query for artist, artwork, movement, or keyword). Schema coverage is 100%, so description adds minimal extra meaning. Baseline 3 is appropriate.

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

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

Description clearly states the tool searches the Provenio art-provenance knowledge graph by free text, returns a ranked list with id/title/url, and serves as the entry point for name/title lookups. It also distinguishes from siblings by noting it wraps search_artists + search_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?

Explicitly states to use as the entry point for any name/title lookup and to pass an id to fetch for full records. Does not explicitly state when not to use, but the context is clear and no alternatives are needed for its intended role.

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 annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds cost (~0.4s), warns results are a shortlist, explains return format with person:slug IDs, and advises on usage patterns like empty query for browsing.

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 concise (6 sentences), front-loaded with cost and purpose, and every sentence adds unique value. No redundancy or unnecessary detail.

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

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

Given 4 parameters and no output schema, the description fully explains return format, usage hints, and how to chain results with search_artworks. It covers all needed context for an agent to use the tool effectively.

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 adds value by explaining that query can be empty for browsing, limit default 20 with has_more check, and filters are AND. These details are not in the schema, improving parameter understanding.

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 'Shortlist person nodes by name/nationality/era' and lists return fields. It distinguishes itself from siblings like get_artist (direct ID lookup) and search_artworks (different entity), making purpose unambiguous.

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

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

Explicitly provides 'Use when:' and 'Do NOT use if:' conditions, directly names the alternative get_artist, and advises to try partial names. This gives clear decision guidance for the agent.

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 (readOnlyHint, idempotentHint, destructiveHint) are already informative. The description adds substantial behavioral context: cost (~0.5s), substring matching (ILIKE), behavior of provenance_risk filter producing coverage_gaps, and a stopping condition. No contradictions.

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 well-structured with clear sections and bullet points. It is slightly verbose but every sentence adds value. Could be marginally tighter, but overall efficient for the complexity.

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

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

Given no output schema, the description explains it returns 'summary rows' and covers edge cases like coverage_gaps. However, it does not detail the fields in summary rows, which could improve completeness for an agent.

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%, but description adds extra meaning beyond schema: warns against embedding artist names in query, clarifies substring matching, explains empty query browses all, and provides rationale for using artist filter. This significantly aids correct parameter usage.

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 the tool's purpose: 'Shortlist artworks by title/artist/medium/date, or risk-filter.' It explicitly distinguishes from sibling tools, notably 'get_artwork' for single artwork details, providing strong differentiation.

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

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

The description provides explicit guidance: when to use ('you need a list, not one work's detail'), when not ('if you know the artwork ID — call get_artwork'), and specific constraints like not chaining searches and proper use of artist parameter versus query field.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds performance cost ('~0.7s'), calls it 'single-call friendly', and describes the optional feature's purpose. No contradictions. Slight deduction because it doesn't disclose any side effects beyond what annotations imply (which is none).

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?

Highly concise: three sentences plus two bullet-like usage lines. No extra words. Front-loads cost, core functionality, and usage guidance. Every sentence serves a purpose.

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?

While inputs are fully documented in the schema, there is no output schema and the description only vaguely describes the return ('rows' and percentiles). It does not mention ordering, pagination, or the exact fields in each row. For a tool making a database query, this is a notable gap that could lead to misuse or confusion about the response format.

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%, baseline is 3. The description adds value by explaining how 'percentile_summary' works (returns P25/50/75/90 + realized-vs-estimate), which goes beyond the schema's description that only lists the percentiles. It also positions the feature for appraisal work, providing context for when to set the parameter.

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

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

The description clearly states the tool returns 'auction transaction rows' and optionally 'P25/50/75/90 + realized-vs-estimate'. It distinguishes itself from the sibling 'query_market_summary' by contrasting lot-level vs. per-artist aggregates. The verb 'search' is implicit but the resource and scope are well-defined.

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 provides both positive ('Use when: need lot-level prices OR percentile stats') and negative usage guidance ('Do NOT use if: you only need per-artist aggregates — use query_market_summary'). This directly helps the agent choose between this and a sibling tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context like cost (~1s) and search behavior, but does not disclose response structure or rate limits. No contradictions with annotations.

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

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

The description is extremely concise: one sentence for cost and search fields, one line for tier definitions, two lines for usage guidance, and one line for the anti-use case. All sentences are necessary and front-loaded with key information.

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

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

Given the moderate complexity (5 parameters, no required ones) and lack of output schema, the description covers cost, searchable fields, tier meanings, and usage context well. However, it does not describe the return format or pagination behavior, which could be helpful for agents.

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 high (80%), but the description adds meaning beyond the schema by explaining the tier enum values (mega, major, boutique, emerging) and clarifying the free-text query across name and id. This provides semantic enrichment not present in the raw schema.

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

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

The description clearly states the tool searches galleries by name, tier, country, or city. It defines tier categories (mega, major, boutique, emerging) and distinguishes itself from the sibling tool 'find_galleries_by_artist' by explicitly stating when not to use it.

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?

Provides explicit 'Use when:' scenarios (identifying galleries in a market/tier band, building B2B target list) and a 'Do NOT use when:' with a named alternative (find_galleries_by_artist), giving clear guidance on when to choose this tool over siblings.

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