Provenio — Art Intelligence

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

Beyond annotations, the description adds substantial context: variable cost, auth header mechanism, allowed-host restrictions, exact return shape, and data handling (logged, not trained, not cached). This is rich behavioral disclosure that helps the agent predict side effects and safety, exceeding what the annotations convey.

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

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

The description is compact yet dense, covering cost, use case, auth, restrictions, response format, and privacy in a few sentences. It is well-structured with clear sections and no filler, though slightly verbose in the middle; every sentence earns its place.

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

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

Given the tool's complexity (user-provided endpoint, auth, security constraints) and the absence of an output schema, the description is remarkably complete. It explains return structure, security boundaries, data handling, and authentication requirements, leaving little ambiguity 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 description coverage is 100%, so the baseline is 3. The description adds some context about endpoint restrictions and response parsing, but parameters are already well-documented in the schema with defaults and constraints. No further semantic clarification is needed.

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 ('forward') and resource ('your own external API endpoint'), clearly distinguishing this tool from siblings by emphasizing user-provided endpoints and third-party art-market sources. It goes beyond a tautology with concrete details about the request/response behavior.

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 the tool: 'when you need to query a third-party art-market source that we do not host.' It also provides important constraints (allowed hosts, auth) but does not mention when not to use it or name alternatives like the sibling 'fetch' 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 and destructiveHint=false. The description adds valuable behavioral context: cost (~4s), full trajectory data return, and detailed structured comparison components (pattern overlap score, career stage delta, exhibition/market delta, interpretation, recommendation). This goes beyond the annotations, though it could mention rate limits or error cases.

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: cost, output, use cases, and exclusions are clearly separated. Every sentence earns its place, and the length is appropriate for a comparison tool with multiple use cases and alternatives. 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?

Despite lacking an output schema, the description thoroughly explains the return structure (full trajectory data + specific comparison metrics) and provides comprehensive usage context. It covers all essential aspects an agent needs to select and invoke the tool correctly, including cost and common use cases.

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%, with both parameters clearly documented (artist_id_1 and artist_id_2, including the hint to use a well-documented historical artist as benchmark). The description does not add additional parameter semantics beyond what the schema already provides, 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 states 'Side-by-side career trajectory comparison for two artists' with a specific verb (compare), resource (career patterns), and scope (two artists). It clearly distinguishes from sibling tools like get_career_trajectory and find_emerging_artists_by_pattern by naming alternatives.

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 'Use when' scenarios (gallery pitching emerging artist, curator narrative evidence) and 'Do NOT use when' exclusions with named alternatives (get_career_trajectory, find_emerging_artists_by_pattern). This gives clear guidance on when to use this tool vs 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 cover read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the exact return shape ({id, title, text, url, metadata}) and explaining that `text` is a readable provenance/market/influence summary. No contradiction 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 three tight sentences: purpose, return shape, and wrapper context. Every sentence earns its place, no filler, and the core verb+resource 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?

Given the output schema exists, annotations cover safety, and there is only one parameter, the description is complete: it says when to use, what it returns, and how it relates to sibling tools. No obvious missing context.

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

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

The schema already fully documents the single `id` parameter with description and examples (100% coverage). The description reinforces that ids come from search results but adds no new parameter format or syntax 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 states a specific verb ('Fetch') and resource ('full Provenio record'), and scopes the id to values returned by `search` (person:… or artwork:…). It also distinguishes itself from siblings by noting it wraps get_artist/get_artwork as a document-fetch tool.

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

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

It clearly says the id comes from search results, implying use after `search`. It does not explicitly name alternatives or exclusions, but mentioning 'wraps get_artist / get_artwork' gives contextual guidance on when this is the appropriate combined fetch.

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, so the safety profile is covered. The description adds a performance cost estimate (~2s) and clarifies the dual-mode behavior, which is useful context 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?

Three short sentences, front-loaded with the cost. Every sentence serves a purpose: cost, mode, exclusion/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?

The description is complete for a read-only tool: it explains what it does, when to use it, and what not to use it for. Given no output schema, it could specify return shape, but the core usage is well covered.

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 88%, so the schema already documents most parameters. The description adds semantic value by explaining the mutual exclusivity of artwork_id/artist_id and notes which parameters apply only to artwork_seed mode, complementing 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 finds comparable artworks or peer artists depending on the seed type ('artwork_id seed → similar works, OR artist_id seed → peer artists'). This specific verb+resource pairing distinguishes it from sibling search 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?

Explicitly explains when to use each mode (EITHER artwork_id OR artist_id) and provides an exclusion with an alternative: 'Not for same-artist lot history (use search_auction_history)'. This is strong usage 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, idempotentHint=true, and destructiveHint=false, which covers safety. The description adds valuable non-obvious behavior: cost (~3s) and coverage limits ('artists with no exhibition records won't appear'). It also discloses that results are 'ranked candidates with confidence score, exhibition/market data, and signal summary', which is more specific than the generic 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 organized into clear labeled sections (cost, patterns, return, use cases, non-use cases, coverage) and each sentence adds distinct value. It is longer than a one-liner but every part earns its place, and the frontline 'Cost: ~3s' is a useful practical signal.

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 there is no output schema, the description compensates by specifying the return type ('ranked candidates with confidence score, exhibition/market data, and signal summary'). It also covers data availability caveats. The 4 parameters and required pattern are all documented, and the use/non-use guidance closes context 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?

The input schema explains all four parameters with full coverage (100%). The description restates the pattern list but adds little beyond the schema: it does not explain the meaning of 'confidence' or 'birth_year_after' in operational terms, nor does it clarify the default for 'birth_year_after'. Baseline 3 is appropriate since the schema carries the load and the description adds mild contextual color.

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 a specific verb+resource: 'Discover emerging artists whose current KG footprint matches a historical career pattern.' This clearly distinguishes it from sibling tools like 'find_comparable_artworks' or 'search_artists', and later explicitly contrasts it with 'get_career_trajectory' and 'compare_career_patterns'. The pattern list further pinpoints the exact domain.

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 gives explicit 'Use when' scenarios for galleries, curators, and collectors, and then provides 'Do NOT use when' with direct alternative tools ('use get_career_trajectory instead', 'use compare_career_patterns instead'). This is textbook usage 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 establish readOnly and idempotent behavior. The description adds meaningful context beyond that: an approximate cost ('~1s'), the return format ('ordered list of representations'), the specific ordering (current first, then deceased_estate, then former), and the fields included (gallery tier/city/country and period). This enriches the agent's understanding without contradicting 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 well-structured and efficient: cost, purpose, return details, and use cases are each covered in short, purposeful segments. Every sentence adds value, and the information is front-loaded with the cost and core function. No redundancy or 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 no output schema, the description compensates by describing the return structure (ordered list with specific fields). It also covers multiple use cases and performance cost. It does not cover edge cases like missing artist or empty results, but for this tool's scope 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 description coverage is 100%, so the baseline is 3. The description does not add additional parameter-level details, but the schema already documents artist_id and include_former with clear descriptions and defaults. The description implies the use of artist_id but does not go beyond the schema, so a 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 the tool's function: 'Find all galleries that represent (currently or formerly) a specific artist.' The verb 'Find' plus resource 'galleries' and the scope 'by artist' distinguish it from siblings like get_gallery_artists (which likely searches artists by gallery). It also specifies the result ordering, adding further clarity.

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 'Use when' scenarios: verifying primary-market representation, building artist-centric outreach, and tracking representation history for a deceased artist's estate. This gives strong context for when to use the tool, though it does not name alternative tools or state when not to use it, so it falls short of a 5.

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, so safety is covered. The description adds behavioral context such as 'Cost: ~1s' and 'SINGLE CALL USUALLY SUFFICIENT', which informs the agent about performance and comprehensiveness. This goes beyond the annotations, though it does not disclose edge cases or error behavior.

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

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

The description is well-structured with a cost line, a clear definition, and bullet-point-like usage guidance. Every sentence carries useful information, and the use of capitalization emphasizes the key takeaway. It is concise without losing important 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 tool's moderate complexity (one parameter, no output schema), the description is highly complete. It explains what the profile includes, when to use it, when not to use it, and performance expectations. The lack of return-format details is mitigated by the comprehensive enumerations of content.

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 parameter description already explains the slug format. The tool description does not add any additional meaning about the parameter beyond what the schema provides, so the baseline score of 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 the tool's purpose: 'Composite artist profile' with a specific verb ('get') and resource ('artist'). It enumerates the included components (identity, reception, 1-hop influence, education, market aggregates) and distinguishes itself from siblings by explicitly advising against chaining with get_influence_network and directing multi-artist comparison to query_market_summary.

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 is provided: 'Use when: you have an artist ID and need their full picture.' It also gives clear exclusions: 'Do NOT chain with get_influence_network unless you need depth > 1' and 'Do NOT use for multi-artist comparison — use query_market_summary.' This fully satisfies the when/when-not/alternatives requirement.

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, idempotent, and non-destructive behavior. The description adds useful context: cost (~1s), the composite nature of the call, and guidance that a single call is usually sufficient. This goes beyond annotations by explaining the trade-offs of using this tool versus others, though it does not detail response format or error conditions.

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 well-structured: it leads with cost, then explains the returned content, then provides usage and exclusion guidance. Every sentence adds value, and the formatting improves 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?

Given the complexity of the tool and absence of an output schema, the description covers the main components of the response, cost, and usage guidance. However, it does not specify the exact return structure or behavior in edge cases (e.g., missing artwork ID), which would be helpful. Overall, it is quite complete for a read-only composite fetch.

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

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

The schema already provides 100% coverage for the single parameter (artwork_id) with a clear description. The tool description does not add additional semantic information about the parameter, so the baseline of 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 explicitly states that this tool returns a composite artwork profile including metadata, Panofsky subjects, reception, custody, polity, and transactions. This clearly differentiates it from siblings like get_provenance_chain and get_reception_arc, making its 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?

It states 'Use when: you have an artwork ID' and explicitly advises against chaining with get_provenance_chain unless gap-risk flags are needed. This provides clear when-to-use and when-not-to-use guidance, effectively distinguishing it from alternative tools.

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, so the safety profile is covered. The description adds significant context beyond annotations: expected cost (~2s), career stage enumeration, pattern definitions, and note that include_comparables=false reduces latency. This goes beyond the structured metadata.

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 organically structured: top-level purpose, then stage/pattern definitions, then use cases, then exclusion. Each sentence contributes new information without redundancy. It is detailed yet easy to scan.

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 description is self-contained: it explains inputs, outputs (milestones, stage, pattern, comparables), domain-specific vocabulary (stage candidates, pattern labels), and provides context for how to use the tool relative to alternatives. Without an output schema, the description carries the burden of explaining what the tool returns, and it does so 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 description coverage is 100%, so both parameters are already documented. The description adds extra value by explaining that include_comparables= false reduces latency, which is not in the schema. It doesn't restate the schema but provides additional context for why one might toggle 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's function: analyzing an artist's career trajectory with milestones, career stage, pattern detection, and historical comparables. It distinguishes itself from siblings like get_artist (biographical) by explicitly scoping its use, and the detailed breakdown of stages and patterns leaves no ambiguity.

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 use cases ('emerging artist discovery, gallery acquisition decisions, curator narrative building') and an explicit when-not-to-use ('Do NOT use for purely biographical queries — use get_artist instead'). It also mentions latency optimization for include_comparables, giving practical 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 description adds substantial behavioral detail beyond the annotations: cost estimate (~0.5s–1s), fallback from normalized table to knowledge-graph nodes, coverage limitations (94 curated events for 20+ artists as of a specific date), and the behavior of returning actionable CLI commands when data is missing. This fully discloses the tool's operational traits.

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 yet information-dense. It front-loads cost and purpose, then details return behavior, coverage, and fallback guidance. Every sentence earns its place, with no filler or redundant repetition of structured data.

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 thoroughly explains what the tool returns (normalized records or fallback nodes), how it handles missing data (coverage_gaps, suggested_next_tools, CLI command), and its coverage scope. This is complete for a two-parameter read-only 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 both artist_id and artwork_id fully described. The description's 'artist OR artwork' phrasing adds no new semantic meaning beyond the schema's mutual exclusivity. Since the schema does the heavy lifting, a baseline of 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 the tool's purpose: 'Exhibition history for an artist OR artwork.' The verb 'returns' and specific resource 'exhibition history' make it distinct from sibling tools like get_artist or get_artwork. The 'SINGLE CALL' emphasis further clarifies its 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?

The description provides clear context on when to use the tool (for exhibition history), including its fallback behavior and the fact that it returns coverage_gaps and suggested_next_tools. However, it does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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, and non-destructive hints, so the added 'Cost: ~1s' and return structure (gallery metadata + ordered artist list with exclusivity/period/notes) provide useful supplementary context. The description adds value beyond the annotations without contradicting them.

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 well-structured: it leads with cost, states the core function, lists return fields, and provides usage guidance. Every sentence carries useful information with no redundancy.

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 description fully covers what the tool does, what it returns, and when to use it, including a clear alternative for the opposite use case. Given the tool's moderate complexity and strong schema/annotation coverage, no critical context is missing.

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

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

Schema description coverage is 100%, with both parameters (gallery_id and include_former) already documented in the schema. The description's mention of exclusivity categories aligns with include_former's meaning, but it does not add significant new parameter 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 'Get the represented-artist roster for a specific gallery', combining a specific verb and resource. It also distinguishes itself from the sibling tool find_galleries_by_artist by explicitly naming the alternative for the reverse lookup.

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 'Use when' scenarios (preparing pitch context, validating overlap) and a 'Do NOT use when' instruction with a named alternative (find_galleries_by_artist). This gives the agent clear decision criteria for tool selection.

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

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

While annotations already mark the tool as read-only and non-destructive, the description adds useful behavioral details: approximate cost (~2-3s) and algorithmic nature (BFS). It does not describe the return format, but the cost and algorithmic disclosure go 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 extremely concise: two sentences that front-load cost and purpose, with no filler. It earns every word by combining cost, action, and usage guidance efficiently.

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's moderate complexity and the rich parameter schema, the description covers the core use case and performance caveat. It does not describe the output structure, but no output schema exists and the read-only nature reduces the need. Overall, it is sufficiently complete for agent decision-making.

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 each parameter clearly described. The description itself does not need to elaborate on parameters, but it adds value by mentioning the cost implications in the max_depth parameter and the default depth of 2. This enriches the schema's existing definitions.

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 as an 'N-hop influence BFS' and distinguishes it from the sibling tool get_artist, which already provides 1-hop influence. This makes the tool's specific role 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 states when to use the tool: 'Use ONLY when depth>1 needed' and points to the alternative get_artist for 1-hop queries. This gives clear guidance on choosing between tools.

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, so the safety profile is covered. The description adds a latency estimate and clarifies the formal education_lineage scope. No additional side effects or auth requirements are mentioned, but the absence of output schema and the simplicity of the tool make this acceptable.

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?

At three short sentences, the description is compact and front-loads the cost. Every sentence adds value: cost, resource definition, and usage guidance.

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 is simple (one required param, two booleans with defaults), annotations are solid, and the description covers purpose, usage, and alternative. It could optionally mention that the result is a network/graph of people, but the name and lineage context make that inferable. Overall sufficient.

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

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

The input schema provides 100% parameter descriptions for artist_id, include_students, and include_teachers, so the description does not need to reiterate them. It adds no extra parameter context, but the schema already carries the full semantic load.

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 identifies the tool as returning a formal teacher/student cluster for academic lineage, and explicitly contrasts it with get_influence_network for conceptual influence. This provides a specific usage directive and distinguishes it from siblings.

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?

States 'Use for academic lineage' and directs users to get_influence_network for conceptual influence, giving an explicit alternative. Also notes a ~1s cost, which helps set expectations.

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 the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context by disclosing an approximate latency (~0.5s), the optional cross_tradition behavior with a concrete example, and the expectation of a single call being sufficient. No contradiction 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?

Each sentence earns its place: cost, output summary, special parameter guidance, usage scenarios, and exclusion. The text is front-loaded with the most critical info and avoids repetition of schema details. Highly efficient and well-structured.

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's complexity (3 params, no output schema), the description covers the core behavior, use cases, exclusions, and special cross_tradition functionality. It might have elaborated on the exact structure of the return context, but the combination with annotations and schema makes it sufficiently complete for effective tool selection and invocation.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds semantic value beyond the schema by explaining the cross_tradition flag with a concrete example (lotus↔rose) and clarifying the concept_id format context. This lifts it above the baseline 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?

Description clearly identifies the tool as retrieving a concept node plus linked artworks, with specific references to definitional context and iconography clusters. It explicitly distinguishes itself from artwork filtering tools by directing users to search_artworks, setting it apart from siblings.

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: definitional context or iconography cluster' and provides a concrete 'Do NOT use for artwork filters — use search_artworks' exclusion with an alternative. Also advises that a single call is usually sufficient, giving practical usage 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 and idempotentHint, so safety is covered. The description adds useful behavioral context: the ~1s cost and the fact that it performs gap-risk analysis with specific historical flags. This goes beyond annotations without contradicting them.

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 compact and front-loaded with cost, then output scope, then usage guidance. Every phrase adds information. It is slightly telegraphic ('Cost: ~1s') but still clear and efficient, 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?

For a read-only tool with three well-described parameters and no output schema, the description provides adequate context by stating it returns a custody timeline plus gap-risk flags and for when to use it. It lacks a detailed return structure, but the high schema coverage and simple output scope make the description sufficiently 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 description coverage is 100%, with each parameter (artwork_id, period_start, period_end) having clear descriptions and examples. The tool description itself adds little about parameter semantics beyond what the schema already provides, so the schema carries the burden and the description meets the baseline.

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 specifies the tool's output as a 'Custody timeline + gap-risk flags' and enumerates specific risk categories (Nazi, colonial, Russian Rev, Knoedler), making the resource clear. It also distinguishes from sibling get_artwork by stating that get_artwork already has basic custody. However, it lacks an explicit verb like 'retrieves' or 'returns', relying on the tool name 'get' to convey the action.

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 gives explicit usage guidance: 'Use only for deep due diligence' and contrasts with get_artwork which 'already has basic custody'. This clearly tells the agent when to use this tool versus the alternative, meeting the highest bar for this dimension.

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, covering the safety profile. The description adds useful behavioral context: cost (~1s), time-ordering, and the concept of 'reception claims', going beyond the annotations without contradicting them.

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, with the cost front-loaded and every clause earning its place: cost, output type, target resource, intended use case, and alternative tool. No redundancy or 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?

The tool is simple with two well-documented parameters and strong annotations. The description adds cost, ordering, and usage context, and while it does not explain what a 'reception claim' is in depth, it is sufficient for a straightforward read-only query 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 description coverage is 100%, with both parameters (artist_id, artwork_id) already described and mutual exclusivity noted. The description adds no new parameter-level detail, matching the baseline for high schema coverage.

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 the tool returns 'Time-ordered reception claims for artist or artwork', which is a specific verb+resource+scope. It also distinguishes itself from a sibling by directing price-related needs to query_reception_price_correlation.

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 usage context ('Use for valence-shift narrative') and an explicit alternative ('Use query_reception_price_correlation if you also need price'). This clearly guides when to use this tool versus a related one.

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 non-destructive behavior, so the description need not repeat that. It adds valuable context: performance (~0.5s), return structure, source URL, and the note about an embedded demo key with an alternative for high-volume use. This goes beyond the annotation 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?

Every sentence serves a purpose: cost, function, use-case, return format, source/key. It is front-loaded with the most essential info and uses bullets/labels for clarity. No redundancy or 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?

With no output schema, the description fully specifies the return structure. It also covers source, key usage, and performance. Given the low complexity (2 params, read-only search), nothing critical is missing.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description enriches the query parameter with examples ('pissarro paris 1897' or 'who:"Rembrandt"') and clarifies the limit range, but this is incremental over the schema, not a major compensation gap.

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 ('Search'), a specific resource ('Europeana cultural heritage corpus'), and gives context (~50M records from EU museums/archives). It also explicitly distinguishes itself from siblings by mentioning Europeana and the 'Use when' condition for European museum holdings.

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 ('triangulating Provenio data against European museum holdings, or finding object records with images for a Western European artist') and names a specific alternative for high-volume use (byok_external_query). This gives clear guidance on when to choose this 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?

Beyond the annotations (readOnly, openWorld), the description adds valuable behavioral context: ~0.3s cost, free public API, ~480K object scope, zero PII, public domain image flagging, and the exact return shape depending on input. This enriches the agent's understanding without contradicting 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?

Five concise sentences, each adding necessary information: cost, primary function, use cases, return format, and data source/quality. No fluff or redundancy, and the first sentence immediately states the tool's purpose and 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?

Given no output schema, the description adequately covers the return shapes for both modes. It also includes source URL, data scale, latency, and the 'Use when' context, making it a complete picture for a lookup tool with good annotations and schema. The absence of error handling or pagination details is not a significant gap due to schema and annotations.

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 adds semantic value by explaining the two modes (search vs dereference) and how object_id changes the return type, which goes beyond the schema descriptions. It does not elaborate on all parameter interactions, but the key conditional logic is clarified.

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 the Metropolitan Museum of Art collection and optionally dereferences an objectID. This specific verb+resource combination distinguishes it from sibling tools like lookup_europeana or lookup_wikidata_art, and the return format is explicitly noted.

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 'Use when' scenarios: needing a museum-confirmed match or triangulating Provenio data against Met holdings. It gives clear context for when to use the tool, though it does not mention alternative tools or explicit 'when not to use' cases, which would earn a 5.

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

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

Annotations declare read-only and open-world behavior, and the description adds valuable context: cost (~3-8s), no auth required, public source, 12-second timeout, and raw SPARQL JSON result format. These details go beyond what annotations provide and help set expectations for latency and output.

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 compact and front-loaded: cost, purpose, when to use, usage pattern, return format, and source. Every sentence contributes meaningful information, and the structure allows quick scanning. No fluff or repetition.

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 one parameter and no output schema, the description provides sufficient context: what it does, when to use it, example input, return format, source, and timeout. It is complete enough for an agent to select and invoke the tool correctly in most scenarios.

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

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

The single parameter 'sparql' is fully documented in the schema with a detailed example query, giving baseline coverage. The description reinforces usage by stating 'pass a SPARQL query string' and references the example, adding clarity on the expected input pattern without being redundant.

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 function: running a SPARQL query against Wikidata for art-related entities. It uses a specific verb ('Run'), names the resource ('Wikidata'), and distinguishes itself from sibling lookup tools by focusing on cross-museum location data and biographical data not in Provenio.

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 the tool: 'Use when: you need cross-museum location data for an artist's works, or biographical data not in Provenio.' This provides clear context and an implicit alternative (Provenio), though it does not explicitly name sibling tools like lookup_europeana or fetch.

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, non-destructive behavior. The description adds a 'Cost: ~2s' latency expectation and characterizes the output as aggregate data across market, reception, and polity dimensions, supplementing the annotation-provided safety profile.

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: cost, what it does, and usage alternatives. No filler or repetition; every sentence contributes distinct value and is front-loaded for quick scanning.

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 communicates the aggregate nature and directs users to sibling tools for detailed single-artist or lot-level data. It could specify the return structure more explicitly, but it is adequate for selecting and invoking the 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 description coverage is 83%, so the schema already documents most parameters. The description mentions the 'reception × polity' dimensions and cross-artist aggregation but doesn't add meaning beyond the existing parameter descriptions. 'limit' lacks schema description but default and bounds are present.

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 identifies the tool as providing 'Per-artist market aggregates × reception × polity' and positions it for 'cross-artist comparison.' It distinguishes itself from siblings by explicitly pointing to 'get_artist' for deep profiles and 'search_auction_history' for individual lots.

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 the tool ('Use for cross-artist comparison') and names concrete alternatives for adjacent use cases, making the decision boundary clear. This is strong guidance beyond simple purpose statements.

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 as safe, so the description does not need to repeat safety. It adds a performance note ('Cost: ~2s') and scopes to 'now dispersed' artworks, which is useful. However, it does not disclose output behavior such as result format, limits, ordering, or what 'dispersal' means beyond the optional parameter. This aligns with the calibration example where annotations lower the bar and description adds mild 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 is composed of four short, purposeful fragments: cost, what the tool covers, usage context, and a sibling alternative. It is front-loaded with the most actionable info (cost) and every sentence earns its place. No word is wasted.

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 three parameters and no output schema, the description carries the burden of explaining what the tool returns. It states 'Polity-origin artworks now dispersed,' suggesting it lists dispersed artworks, but it does not explicitly describe the return shape, whether it includes provenance details, or how results are ordered. The schema descriptions for parameters provide some context (e.g., claim_priority_score), but the overall output is under-specified. This is adequate for tool selection but leaves gaps for invocation.

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

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

Schema description coverage is 100% for all three parameters, so the schema already explains polity_id, years_after_collapse, and rank_by_claim_priority. The description adds no parameter-specific details. Per the rubric, baseline 3 is appropriate when schema covers parameters fully and description provides no extra semantics.

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 'Polity-origin artworks now dispersed' and suggests use for 'restitution/cultural-heritage analysis.' The tool name clarifies the action (query). It distinguishes from search_artworks by explicitly directing simple lists to that sibling. However, the description is a fragment and does not fully articulate the query behavior (e.g., 'returns dispersed artworks from a polity'), which keeps 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?

The description gives a clear use case: 'Use for restitution/cultural-heritage analysis.' It also names an alternative for a different scenario: 'For simple list: search_artworks.' This explicitly tells when to use this tool and when to use a sibling, fully meeting the criterion.

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, and non-destructive behavior. The description adds a performance cost indicator (~2s) and notes that it combines two underlying tools, which is useful operational context beyond what annotations provide. This meets the lower bar for transparency when annotations are present.

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 a single sentence plus a cost note, with no redundant words. It conveys the core purpose, scope, and cost efficiently, earning every word.

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 one-parameter, read-only query with rich annotations, the description covers the essential context: what it does (combines reception and price), scope (one artist), and operational cost (~2s). It does not detail output format, but the term 'timeline' gives a reasonable expectation, and no output schema is provided.

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% for the single required parameter artist_id, which is described as 'Person ID slug or person:...'. The description adds no additional parameter semantics beyond 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 produces a combined reception and price timeline for one artist, using the explicit verb 'combines' and naming the component parts (get_reception_arc + price trend). This distinguishes it from sibling tools like get_reception_arc (reception only) and query_market_summary (market summary).

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 clear context by indicating that this tool combines reception and price data in one call, implying its use when both are needed together. It does not explicitly list alternatives or when NOT to use it, but the combination statement is sufficient guidance for an agent to select it over making separate calls.

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, non-destructive. The description adds the return shape ('ranked list of {id, title, url}') and the wrapper behavior, providing useful context beyond the 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?

Four concise sentences, front-loaded with the main action, then return format, usage guidance, and wrapper context. Every sentence adds value.

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

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

With one param, rich annotations, and output schema present, the description covers entry point, return shape, and next step (fetch), making it complete for a search 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 covers the single query parameter with a clear description. The tool description adds no additional parameter syntax details, so 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?

The description states a specific verb ('Search') and resource ('Provenio art-provenance knowledge graph') with explicit scope ('artists + artworks'). It also distinguishes from siblings by noting it wraps search_artists + search_artworks and points to fetch for full records.

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 this as the entry point for any name/title lookup' and 'Pass an id to `fetch` for the full record', giving clear when-to-use and an alternative. This contrasts with sibling lookup/search tools.

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/idempotent annotations, the description discloses non-obvious behavior: approximate cost (~0.4s), output ID format ('person:slug'), how to pass IDs to search_artworks, and a stopping rule. This significantly aids safe and correct invocation.

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?

Every sentence delivers distinct, useful information. Cost is front-loaded, guidance is clearly labeled, and the total length is proportional to the tool's complexity. No filler or redundancy.

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 search tool with four parameters and no output schema, the description covers return shape, use cases, exclusions, alternative tools, ID format, and downstream usage. This is a complete, self-sufficient description.

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 covers 100% of parameter descriptions, so baseline is 3. The description adds valuable usage semantics: using partial names for query, using empty string to browse by filters, and how returned IDs plug into another tool's artist parameter. This exceeds baseline.

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 function: 'Shortlist person nodes by name/nationality/era' and lists exact return fields. It distinguishes itself from siblings by explicitly contrasting with get_artist and specifying that results are person IDs for use in 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 if' guidance, including the alternative to call get_artist directly when an ID is known. It also gives practical advice on partial-name matching, making the tool's intended context unmistakable.

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, but the description adds valuable behavioral context beyond that: cost (~0.5s), substring ILIKE matching, the 'summary rows' return shape, and the coverage_gaps interpretation for provenance_risk. It also explains data-density limitations. No contradiction 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 front-loaded with purpose and organized into clear usage directives, making it scannable. However, it is somewhat dense and repeats the 'do not put artist names in query' guidance also present in the schema, and the 'STOP after this' sentence duplicates the earlier 'Do NOT use if' call to get_artwork. Nearly every sentence earns its place, but minor redundancy prevents a 5.

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

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

Without an output schema, the description compensates by stating 'Returns summary rows', explaining filter semantics, adding cost, and giving a stopping rule. It also clarifies the coverage_gaps caveat for provenance_risk. For an 8-parameter list/search tool, the description gives an agent enough context 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 description coverage is 100%, so baseline is 3. The description adds practical parameter semantics on top: warns against embedding artist names in query, recommends 'person:...' slug format, and suggests combining query + artist filter for ambiguous titles. This exceeds schema-only meaning but is not a full replacement for all 8 parameters.

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 'Shortlist artworks by title/artist/medium/date, or risk-filter (provenance_risk, attribution_status). Returns summary rows.' This clearly states the verb, resource, and filtering scope, and explicitly contrasts with get_artwork for single-work detail, distinguishing it from sibling 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?

Provides explicit guidance: 'Use when: you need a list, not one work's detail.' and 'Do NOT use if: you know the artwork ID — call get_artwork.' It also advises against chaining multiple search_artworks calls and gives concrete filter-vs-query best practices, including using the person ID slug. This is exemplary usage 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 cover read-only and non-destructive hints. The description adds useful behavioral context: a ~0.7s cost, the ability to combine filters with percentile_summary in one call, and the realized-vs-estimate output. This goes beyond the basic safety profile without contradicting 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?

Four concise sentences, each earning its place: cost, core functionality, usage guidance, and a single-call tip. Front-loaded with the most decision-relevant info; 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 8 parameters, no output schema, and a rich sibling context, the description covers purpose, usage boundaries, cost, and aggregation options. It lacks explicit return-structure details (e.g., row fields, pagination), but the 100% param schema documentation compensates. A strong, actionable entry point.

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 each parameter already well-described (e.g., min_price_usd CPI behavior, date formats). The description adds little about parameters beyond reinforcing percentile_summary's purpose, so it stays at the baseline for high schema coverage.

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 returns auction transaction rows, with optional percentile_summary returning P25/50/75/90 and realized-vs-estimate. It distinguishes itself from sibling query_market_summary by explicitly contrasting lot-level prices/stats versus per-artist aggregates.

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

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

Explicit 'Use when' and 'Do NOT use if' instructions with a named alternative (query_market_summary). Also highlights the single-call friendliness for appraisal work, giving clear decision criteria.

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/non-destructive behavior, so the description adds complementary context: an estimated cost (~1s) and definitions of the tier taxonomy. It does not describe return format or pagination, but given the strong annotation baseline, the added value justifies above-average transparency.

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 compact and well-organized with clear sections for cost, search dimensions, tier definitions, and usage guidelines. Every sentence has a distinct purpose: no fluff or repetition of schema 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?

With no output schema, a simple search tool is sufficiently specified by the description plus annotations and parameter schema. It covers purpose, usage context, alternative tools, domain-specific tier definitions, and a cost note, making it a robust contract for an agent to invoke 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 80%, with tier only having an enum without descriptions. The description fills this gap by explaining each tier (mega, major, boutique, emerging) with real-world examples. It also clarifies that 'name' relates to the query parameter, though it could have been more explicit about matching the parameter names exactly.

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 function: "Search galleries by name, tier, country, or city" – a specific verb and resource with search dimensions. It also distinguishes from a sibling tool by explicitly pointing to find_galleries_by_artist for artist-based lookups, leaving no ambiguity about its 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?

Two explicit "Use when" scenarios define appropriate contexts (market/tier analysis, B2B list building), and a "Do NOT use when" clause names the alternative tool (find_galleries_by_artist). This is exemplary guidance for an agent selecting among siblings.

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