connect

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

Annotations cover idempotency, read-only status, and non-destructiveness, but the description adds valuable context: it clarifies that this tool 'does not yet mint the shared view' and is for signaling intent, which goes beyond annotations. No contradictions with annotations (e.g., 'claim' aligns with non-readOnlyHint). However, it doesn't detail rate limits or auth needs, keeping it from a perfect score.

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 efficiently structured with front-loaded purpose, followed by usage guidelines and triggers. Every sentence adds value without redundancy, such as distinguishing from alternatives and providing actionable instructions, making it concise and well-organized.

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 (mutation with idempotency) and lack of output schema, the description is mostly complete: it explains the action, when to use it, and behavioral nuances. However, it doesn't detail the response format or error cases, leaving a minor gap for an agent invoking it.

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

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

Schema description coverage is 100%, so the schema already documents the 'request_id' parameter fully. The description repeats 'Never ask the user for this' from the schema but adds minimal extra meaning (e.g., 'From list_rai_requests' is implied). Baseline 3 is appropriate as the schema does the heavy lifting.

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 specific action ('Claim a pending RAI request') and distinguishes it from sibling tools by explaining it 'signals intent to fulfill but does not yet mint the shared view.' It explicitly differentiates from 'fulfill_rai_request' for immediate fulfillment, making the purpose distinct and 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?

The description provides explicit guidance on when to use this tool ('Use when the artist wants to acknowledge the request but needs more time to pick the right work or generate the PIN') and when not to ('For immediate fulfillment, use fulfill_rai_request directly instead'). It includes trigger phrases and prerequisites ('Find the request_id via list_rai_requests'), offering comprehensive usage 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=true, destructiveHint=false, openWorldHint=false, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond this: it explains that the image URL is publicly accessible from Supabase Storage, requires fetching and visual inspection, and outlines a multi-step flow (call tool, fetch image, present proposals, confirm updates). However, it doesn't detail rate limits or authentication needs, keeping it from a perfect score.

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 appropriately sized and front-loaded, starting with the core purpose. However, it includes detailed lists of fields and flow steps that, while informative, could be streamlined. Every sentence adds value, but some redundancy (e.g., reiterating field lists) slightly reduces efficiency, preventing a perfect score.

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 (analysis for catalogue proposals) and lack of output schema, the description is highly complete. It covers purpose, usage guidelines, behavioral context (e.g., public URL, visual inspection), parameter resolution, and integration with other tools (e.g., 'update_work'). No annotations are contradicted, and it provides all necessary context for effective agent use.

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 has 0 parameters with 100% coverage, so no parameter documentation is needed. The description compensates by explaining how to resolve the work: 'Resolve the work by workId (UUID) or uwi (e.g., "RAI-2026-00417").' This adds practical guidance beyond the schema, though it's not strictly about parameters, warranting a high but not perfect score.

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: 'Return the primary image URL and current metadata for a work, so you can visually analyze the image yourself and propose structured catalogue fields.' It specifies the verb ('Return'), resource ('primary image URL and current metadata'), and distinguishes it from siblings like 'update_work' or 'search_works_visual' by focusing on analysis for catalogue field proposals rather than direct updates or searches.

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 on when to use this tool: 'Use this when the artist asks you to read a work you uploaded, or when beat 2 of the add-work flow surfaced thin hints.' It also specifies alternatives and exclusions: 'Use search_natural_language to find workId — never ask the user' and distinguishes fields to improve from those to leave alone, ensuring clear context 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?

Adds context beyond annotations: reveals that cancellation is visible to the artist and that the request is pulled before resolution. Annotations (idempotentHint=true, destructiveHint=false) are not contradicted.

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, front-loaded purpose, followed by usage guidance, triggers, and parameter sourcing. No wasted words; each 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?

Covers when to use, parameter sourcing, behavioral outcome, and caution. No output schema, but description adequately informs agent for correct invocation. Missing return value details, 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?

Adds important meaning: explains how to obtain request_id (from list_rai_requests, never ask user) and that reason surfaces in audit trail. This goes beyond the schema's basic 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?

Clearly states 'Cancel an RAI request' with specific verb and resource, and distinguishes from siblings like accept_rai_request and decline_rai_request by noting it is for user-sent requests before resolution.

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 describes when to use ('user has decided they no longer need the record'), provides trigger examples, and instructs to find request_id via list_rai_requests with direction='outgoing', with a confirmation warning.

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 indicate write operation (readOnlyHint: false) and non-destructive nature (destructiveHint: false). Description adds valuable behavioral context: 'triggers auto-provenance' and 'imports images from the website in one operation'—significant side effects not indicated in 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 dense sentences with zero waste. Front-loaded with core purpose, followed by workflow prerequisites, operational details (side effects), and parameter-specific guidance. Every clause delivers actionable 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?

Excellent coverage of the multi-step workflow prerequisites and parameter usage. Minor gap: no mention of return values (no output schema exists) or idempotency concerns (idempotentHint: false suggests duplicate creation risk if called twice), which would be valuable for a confirmation/save operation.

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?

Despite 100% schema coverage (baseline 3), description substantially enhances parameter understanding: explains 'skip: true' is for 'duplicates, unwanted' works, clarifies 'works' array accepts 'artist-corrected values', and mandates artist_id sourcing via get_profile rather than user input.

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 explicitly states the tool 'Save[s] works extracted from a website import' with specific verbs (save, creates, imports) and clearly distinguishes this from direct work creation by specifying it's for 'confirmed' website imports only.

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 workflow sequencing: 'Call this after presenting import_from_website results and receiving artist approval.' Also specifies prerequisite tool usage ('Use get_profile to obtain artist_id') and warns against user input ('never ask the user for 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?

While annotations declare idempotency and non-destructive nature, the description adds crucial flow context: that this establishes a connection equivalent to OAuth, requires immediate invocation without confirmation when triggered, and follows specific pattern matching (WORD-1234). It does not disclose additional side effects like session duration or caching 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?

Every sentence serves a distinct purpose: purpose statement, OAuth warning, conditional prerequisites, proactive prohibition, execution instruction, and UX language guidance. The structure front-loads the action, follows with warnings, and ends with specific handling instructions. No redundancy despite high information density.

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 complex authentication tool with conditional logic and no output schema, the description comprehensively covers prerequisites (get_profile failure state), input format, immediate execution behavior, and user-facing language constraints. The inclusion of error-state triggering conditions compensates for the lack of output schema documentation.

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?

Despite 100% schema description coverage, the description adds semantic context by linking the code to user-initiated sharing ('user shares a code'), reinforcing the pattern format with examples (TULIP-3657), and emphasizing normalization requirements. This bridges the gap between technical schema and conversational UX.

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+method ('Connect to the user's catalogue using a pairing code'), clearly distinguishing this from OAuth-based connections mentioned immediately after. It explicitly differentiates from sibling tool get_profile by explaining when each authentication method applies.

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 when/when-not conditions using numbered criteria ('Only use this tool when: (1) get_profile returns an authentication error...'), names the alternative tool (get_profile/OAuth), and includes UX constraints ('Never proactively ask', 'Never say "pairing code"'). This is a model for conditional tool selection 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 establish this is a non-destructive write operation. The description adds valuable behavioral context not in annotations: the confirmation workflow ('Present a summary and confirm before saving') and critical data sourcing constraint ('artist_id from get_profile — never ask the user'). 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?

Four sentences, each serving a distinct purpose: purpose definition, usage triggers, parameter extraction guidance, and workflow/constraint instructions. No redundant or filler text. Information is front-loaded and actionable.

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?

Adequate for the critical path: covers the mandatory artist_id sourcing constraint and confirmation workflow. However, gaps remain: three parameters (url, isbn, notes) lack explanation, and with no output schema, the description omits what success/failure looks like or what the tool returns.

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 only 11% schema coverage (artist_id only), the description must compensate. It adds meaning for 5 key parameters (title, author, publisher, year, type) by listing them as fields to extract, but leaves 3 parameters (url, isbn, notes) completely undocumented. The artist_id instruction repeats the schema description rather than adding new information.

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 a specific verb ('Add') and resource ('bibliography entry'), and clarifies the scope ('a publication referencing the artist's work'). It clearly distinguishes from sibling tools like create_work or create_exhibition by focusing on publication references.

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 trigger phrases ('published in,' 'there's a book about,' etc.) indicating when to invoke the tool. However, it lacks explicit 'when not to use' guidance or named alternatives for edge cases (e.g., when to use link_work_to_bibliography 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?

While annotations establish the write-level safety profile (readOnlyHint: false, destructiveHint: false), the description adds critical workflow context: 'Gather details conversationally' and 'Present a summary and confirm before saving,' revealing the interactive confirmation pattern not evident in structured metadata. It omits mention of the idempotentHint: false implication that multiple calls create multiple reports.

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 delivers maximum information density across four sentences: purpose definition, trigger enumeration, workflow guidance, and ID resolution instruction. Every clause serves agent decision-making without redundancy or filler, with critical trigger phrases 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 tool's complexity (10 parameters, write operation) and lack of output schema, the description adequately covers the core workflow and primary content domains but leaves numerous secondary parameters unexplained and provides no indication of return values or post-creation behavior beyond the confirmation step.

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 schema description coverage at only 10%, the description partially compensates by mapping conceptual domains 'surface, structure, frame' to their respective note fields and emphasizing the work_id resolution strategy. However, it fails to clarify six other parameters including report_date, reported_by_name, and recommendations, leaving significant semantic gaps for a 10-parameter tool.

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 ('Create') and resource ('condition report'), explicitly scopes the content to 'physical state (surface, structure, frame),' and clearly distinguishes itself from sibling tools like `list_condition_reports` or `create_work` through this specific physical-documentation 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?

It provides explicit trigger phrases ('this piece has damage,' 'condition report,' etc.) indicating precise invocation contexts, and specifies prerequisite workflow steps ('Resolve work_id via search_natural_language'). It lacks an explicit pointer to `list_condition_reports` for read-only scenarios or 'when not to use' guidance, preventing a perfect score.

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

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

Annotations are all false, and the description adds critical behavioral details: it does not trigger pending_resignature, custody lives on separate timeline, exclusive consignment conflict returns 409, and defaults for status. No contradiction with annotations. The description fully discloses behavioral traits 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 around 150 words, well-structured with a clear opening, bullet-like trigger examples, and explicit constraints. Every sentence adds value without redundancy. Information is front-loaded 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 complexity (15 params, no output schema), the description covers all necessary aspects: purpose, kind distinction, conflict handling, parameter contexts, UUID avoidance, and behavioral notes. It is fully sufficient for an agent to invoke the tool correctly without additional clarification.

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 73% schema coverage, the description adds significant meaning beyond the schema: explains kind semantics (consignment vs loan), notes list_price and commission_rate are for consignments only, exclusivity only for consignments, holder_entity_id resolution via suggest_entity, and status default. Every parameter's context is enriched.

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 records a consignment or loan where physical custody changes without ownership change. It distinguishes between the two kinds with specific sale intent, and provides trigger phrases. This is a specific verb+resource with clear differentiation from sibling tools like record_sale.

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 describes when to use consignment vs loan, mentions exclusivity constraint and HTTP 409 conflict resolution, advises to resolve work_id via search_natural_language and never ask for UUID, and notes that custody is on a separate timeline not invalidating existing VCs. Provides 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 indicate mutating operation (readOnlyHint=false). Description adds important behavioral trait: the need for user confirmation before execution. 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?

Two concise sentences plus a highlighted warning. Front-loaded with core purpose. 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?

No output schema. With 9 parameters and low schema description coverage, the description should provide more parameter context. It lacks details on required fields like direction or work_id, making it incomplete.

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 only 22% (low). The description does not elaborate on any parameters; it only mentions 'for a work' but does not specify work_id or direction. Fails to compensate for the low 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?

Clearly states 'Create a new deal for a work' and explains the context of deals tracking the process of a work changing hands. Distinguishes manual creation from auto-created deals, though does not explicitly name 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?

Explicitly states when to use: 'use this for manual deal creation.' Provides a critical warning: 'IMPORTANT: Present a summary and get confirmation before calling.' This is strong 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 establish write operation (readOnlyHint: false) and non-destructive nature. Description adds critical context about deduplication workflow and explains where entities are referenced throughout the catalogue (provenance, exhibitions, bibliography). Minor gap: does not specify what happens if creation violates uniqueness constraints.

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 with zero waste. Front-loaded with definition and critical prerequisite (suggest_entity). Each subsequent sentence adds distinct value: usage context, parameter guidance. No redundant 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?

Strong coverage for a creation tool: explains entity types, duplicate-checking workflow, and usage patterns. Minor deduction for no mention of return value (ID confirmation?) or error states given the absence of an output schema.

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

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

Schema has 0% description coverage. Description partially compensates by explicitly mentioning city, country, and listing entity types, but leaves aliases, website, and sort_name completely undocumented. Baseline compensation for critical deduplication fields.

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?

Specific verb 'Create' + resource 'entity' with exhaustive enumeration of entity types (person, gallery, museum, etc.) that maps to the entity_type enum. Clearly distinguishes from siblings like create_work or create_exhibition by specifying this is for provenance holders, venues, and bibliography authors.

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 workflow instruction: 'Always call suggest_entity first to check for duplicates before creating.' Provides clear prerequisite and references sibling tool by name. Also specifies when to include optional parameters (city/country 'to help with deduplication').

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 valuable workflow context beyond annotations: specifies 'present a summary before saving' indicating a confirmation expectation, and notes the 'one at a time' constraint for bulk operations. Annotations correctly indicate mutation (readOnly=false) and non-idempotency, which the description supports 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?

Perfectly structured with purpose first, followed by clear TRIGGER labeling, workflow notes, and parameter sourcing. Every sentence earns its place with zero 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?

For a 13-parameter creation tool without output schema, the description successfully covers invocation triggers, prerequisites, and workflow patterns. Minor gap in parameter semantics documentation prevents a perfect score, but sufficient for correct agent operation.

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 only 8% schema description coverage (just artist_id described), the description partially compensates by noting 'Only artist_id and title required' and the artist_id source. However, it fails to explain other parameters like catalog_reference, catalog_published, or date formats, relying only on the vague 'Extract all details you can.'

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 ('Add') and clear resource ('exhibition to the catalogue'), distinguishing it from sibling tools like create_work or create_bibliography. It precisely defines the operation's 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?

Excellent guidance provided through explicit TRIGGER examples ('I was in a show at,' 'here's my CV'), workflow instructions ('create one at a time' for bulk), and prerequisite requirements ('artist_id from get_profile — never ask the user'). Clearly defines when to invoke versus 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 establish the write/non-destructive nature. The description adds valuable behavioral context not present in annotations: the default visibility is 'private' unless specified otherwise. It could further clarify idempotency or side effects, but the default disclosure is meaningful.

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, followed by trigger phrases and technical constraints. Every sentence earns its place with zero redundancy—efficiently packing invocation triggers, default behavior, and resolution instructions into a compact form.

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 lack of output schema, the description adequately covers invocation requirements: trigger conditions, default parameter values, and work_id resolution strategy. It misses documentation for note_type semantics, which prevents a perfect score for a 4-parameter tool with low schema coverage.

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 only 25% schema coverage, the description partially compensates by adding default semantics for visibility and reinforcing work_id resolution. However, it fails to document note_type (particularly when to use 'condition_note' versus the sibling create_condition_report tool) or provide content format guidance beyond the general purpose statement.

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 ('Add') and resource ('note'), clearly scoping it to 'a work'. It effectively distinguishes from siblings like create_condition_report by emphasizing informal use cases (annotations, research notes, contextual information) rather than formal structured reports.

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 TRIGGER section provides explicit when-to-use guidance with specific phrases ('note that,' 'remind me about'). It also explicitly references sibling tool search_natural_language for work_id resolution, giving clear instruction on prerequisite steps and alternative 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?

Annotations indicate this is a write operation (readOnlyHint=false) and non-destructive. The description adds valuable behavioral context about trigger phrases and optionality that annotations don't cover. However, it doesn't mention what happens if a place with the same name already exists (idempotentHint=false suggests duplicates possible) or what the tool returns.

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?

Perfectly structured with zero waste: first sentence establishes purpose, second provides trigger conditions, third gives exclusion criteria, and fourth advises on optional fields. Every sentence earns its place and the core action 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 lack of output schema, the description adequately covers the business logic (what constitutes a place, when to create it). The only gap is silence on return values (e.g., whether it returns the created place ID), which would be helpful for an agent invoking this tool in a workflow.

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 0% schema description coverage, the description compensates well: it lists place_type enum values ('studio, gallery, museum, storage facility'), explicitly mentions city/country should be included when known, and implies name through examples. Only the 'region' parameter is unaccounted for, making this strong compensation for the schema 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 opens with a specific verb ('Create') and resource ('place'), immediately followed by concrete examples ('studio, gallery, museum, storage facility') that map exactly to the place_type enum. It clearly distinguishes from sibling tools like create_work or create_entity by focusing on location/physical spaces.

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?

Excellent explicit guidance: the 'TRIGGER:' section lists exact natural language cues ('my studio in Bushwick,' 'stored at'), and it explicitly states 'Places are optional — only create when the user mentions locations,' providing clear when-not-to-use guidance. It also advises when to include optional parameters ('Include city/country when known').

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 indicate non-read-only, non-idempotent, non-destructive operation. Description adds critical return value disclosure ('download URL and UWI') absent from input schema and output schema. Explains conceptual nature of RAI. Does not explicitly clarify repeat-call behavior (idempotency implications).

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, zero waste: (1) action/purpose, (2) return values, (3) conceptual definition, (4) usage guideline. Front-loaded with specific verb. No redundancy with schema or annotations.

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 single-parameter tool with 100% schema coverage and no output schema, description fully compensates by documenting return values (URL/UWI) and providing clear workflow prerequisites. Annotations cover safety profile. Complete for complexity level.

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% coverage (baseline 3). Description adds significant workflow context beyond schema: instructs specifically to use search_natural_language by title to obtain the work_id parameter, adding operational semantics the schema cannot provide.

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?

Specific verb 'Generate' + resource 'Record of Art Identity (RAI) PDF' + scope 'for a work'. Distinguishes from generic 'create_work' sibling by specifying this creates a PDF identity document. Defines RAI conceptually as 'signed, portable, verifiable identity'.

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 directs to sibling tool 'search_natural_language' to find work_id by title, and explicitly prohibits asking the user ('never ask the user for it'). Clear when-to-use vs. alternative workflow.

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 establish write/non-destructive/non-idempotent properties. The description adds valuable workflow context: confirmation is required before calling, side effects include potential get_upload_url follow-up, and it clarifies the inference pattern ('present one summary — never ask field by field'). Does not contradict 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?

Information-dense but well-structured with logical flow: purpose → required fields → triggers → inference strategy → confirmation requirement → post-actions → alternatives. Every sentence conveys critical workflow 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?

Given 21 parameters, nested objects, and no output schema, the description provides excellent workflow completeness (prerequisites, confirmation, follow-ups). Minor gap: does not describe return values or success indicators, though 'After creating' implies the tool returns confirmation of creation.

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 only 14% schema description coverage (3 of 21 fields), the description partially compensates by identifying the two required fields (title, artist_id) and suggesting common optional fields to infer (medium, dimensions, date). However, it leaves 15+ parameters undocumented including edition fields, status semantics, and date field distinctions.

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 'Add a new work to the catalogue' with a specific verb and resource. It clearly distinguishes this from sibling tools by mentioning the batch/CSV alternative (app.raisonn.ai/import) and contrasting with get_upload_url as a follow-up rather than alternative.

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?

Exceptional guidance including: explicit TRIGGER conditions ('User shares a photo,' 'says add/catalogue this'), prerequisite tool (artist_id from get_profile), workflow constraints ('Wait for confirmation before calling'), post-creation actions ('proactively call get_upload_url'), and explicit alternatives for CSV files. Covers when, when-not, and how 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?

Beyond annotations (write operation, non-destructive), description adds batch size constraints (50), data extraction requirements (titles, media, dates, dimensions, series), and critical workflow context (must wait for confirmation). Does not specify error handling or return values, but annotations cover 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?

Dense but well-structured: opens with action and limits, followed by triggers, extraction guidance, workflow steps, alternative path, and parameter sourcing. Every sentence provides actionable guidance without 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?

Comprehensive for a complex batch operation with nested object parameters and no output schema. Covers trigger detection, data mapping guidance, confirmation workflow, and error prevention (artist_id sourcing). Minor gap in not describing success/failure outcomes, but sufficient for correct 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?

With 0% schema description coverage, the description compensates by listing specific data points to extract (titles, media, dates, dimensions, series) and explicitly stating artist_id sourcing from get_profile. Could further improve by acknowledging additional fields like status or inventory_number, but covers primary extraction targets effectively.

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?

Explicitly states 'Create multiple works at once (up to 50)' with specific verb, resource, and batch scope. Distinguishes from sibling 'create_work' via batch terminology and from CSV import workflows by directing users to app.raisonn.ai/import instead.

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 trigger conditions ('User pastes a spreadsheet, list, CSV, or describes multiple works'), example utterances ('I have a bunch of works'), and clear alternatives (direct CSV owners to import app instead of using this tool). Also specifies required workflow steps (present summary, wait for confirmation).

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 valuable behavioral context beyond annotations: it discloses that the action sends an email notification to the requester and requires confirmation before calling. Annotations cover idempotency (idempotentHint: true) and non-destructive nature (destructiveHint: false), but the description enhances this with real-world implications like email sending and confirmation steps.

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 the core action and outcome, followed by usage guidelines and behavioral details. Every sentence earns its place by providing essential information without redundancy, making it efficient and well-structured for quick comprehension.

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 (a decline action with email notification), annotations cover safety aspects, and the description adds crucial context like confirmation requirements and parameter sourcing. However, without an output schema, it doesn't detail return values (e.g., success/failure response), leaving a minor gap in completeness.

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 description coverage, the baseline is 3. The description adds meaningful context by specifying that request_id should be obtained from 'list_rai_requests' and never asked from the user, which clarifies the parameter's sourcing and usage beyond the schema's technical definition.

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 specific action ('Decline an RAI request') and the resource ('RAI request'), distinguishing it from sibling tools like 'accept_rai_request' and 'fulfill_rai_request'. It explicitly mentions the outcome ('the requester is notified'), making the purpose unambiguous and distinct.

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 on when to use this tool ('Use when the artist does not want to authenticate the described work') with specific examples (e.g., 'wrong attribution, not by them, declining to confirm'). It also includes trigger phrases like 'decline that request' and distinguishes it from alternatives by referencing 'list_rai_requests' for obtaining the request_id.

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 critical behavioral context beyond annotations: async processing details ('Polls up to 50s; job continues in background') and persistence model ('nothing is saved automatically'). Reinforces read-only nature safely 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?

Efficiently structured with zero waste: purpose statement, persistence disclaimer, workflow integration, performance characteristics, and fallback logic. 'FALLBACK' label aids scannability. 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?

Comprehensive despite no output schema. Explains return behavior ('Returns structured data'), temporal characteristics (polling/background), and integration points with two critical siblings. Sufficient for an async extraction 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%, so baseline applies. Description references URL implicitly ('from any URL') but does not elaborate on 'max_pages' parameter or provide usage examples beyond the schema's own documentation.

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?

Specific verb ('Extract') + resource ('structured artwork metadata') + concrete scope ('museum pages, gallery listings, auction results, portfolios'). Clearly distinguishes this extraction tool from sibling 'parse_artwork_page' and saving tool 'confirm_website_import' through explicit workflow references.

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 multi-step workflow ('Present results... then call confirm_website_import to save') clarifies when to use vs. sibling alternative. 'FALLBACK' section explicitly directs to 'parse_artwork_page' on failure, providing clear alternative selection 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 indicate this is a write operation (readOnlyHint: false) with no idempotency or destructiveness. The description adds valuable behavioral context beyond annotations: it discloses that the tool mints a PIN-protected shared view, emails the requester, hashes the PIN (requiring out-of-band sharing), and requires user confirmation. This enriches understanding of the tool's effects and constraints, though it doesn't detail rate limits or auth needs.

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 the core purpose, followed by usage guidelines and behavioral details in a logical flow. Every sentence earns its place by providing essential information without redundancy, such as trigger phrases, prerequisites, and PIN handling instructions. It's appropriately sized for a complex tool with three parameters.

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 (write operation with three required parameters) and lack of output schema, the description is mostly complete. It covers purpose, usage, behavioral traits, and parameter handling. However, it doesn't detail the return value or error cases, which could be helpful since there's no output schema. Annotations provide safety context, but the description could be slightly more comprehensive for full completeness.

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 well-documented in the schema (e.g., pin requires user input, work_id resolved via search_natural_language). The description reinforces this by mentioning 'Ask the user for the 4–32 character PIN' and 'Resolve work_id via search_natural_language,' but adds minimal new semantic information beyond what's already in the schema. Baseline 3 is appropriate given 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 clearly states the specific action ('Fulfill an RAI request by attaching one of the artist's works') and distinguishes it from siblings like 'create_rai_request' or 'accept_rai_request' by specifying it's about fulfilling existing requests with a PIN-protected shared view. It includes the verb 'fulfill' and resource 'RAI request' with precise 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?

Explicit guidance is provided on when to use this tool: triggered by phrases like 'send [requester] the RAI for [work]' and 'fulfill that request with the [work description].' It also specifies prerequisites (find request_id via list_rai_requests, resolve work_id via search_natural_language) and alternatives (never invent a PIN, ask the user). This covers when, when-not, and alternatives comprehensively.

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 as false, so safety profile is clear. The description adds that the tool returns linked records (RAI requests, consignment requests, etc.), which is useful context beyond annotations but does not disclose other traits like pagination or rate limits.

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?

A single, well-structured sentence that front-loads the action and resource, lists the linked record types efficiently, and contains no superfluous 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 low complexity (1 param, no output schema) and rich annotations, the description sufficiently explains what the tool returns (deal detail with linked records). It could hint at the return format (e.g., single object), but overall 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 coverage is 100% for the single parameter deal_id, and the description does not add any additional information beyond the schema's description. 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 'Get deal detail' with a specific verb and resource, and distinguishes from siblings like list_deals (for listing) and update_deal_state (for modification). It explicitly mentions the linked record types, adding 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 implies usage for retrieving detail of a single deal but does not explicitly contrast with alternatives (e.g., use list_deals for summaries). No when-not-to-use guidance is provided, leaving some 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 establish this is safe (readOnlyHint=true, destructiveHint=false) and idempotent. The description adds valuable workflow context (session caching behavior, sequencing relative to connect_catalogue) that annotations don't provide. It does not contradict the safety 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 with zero waste: sentence 1 establishes purpose, sentence 2 establishes primary usage timing, sentence 3 establishes secondary trigger and post-processing instruction. Front-loaded with the core action and appropriately terse for a parameterless tool.

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

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

For a simple read operation with no parameters, the description covers the essential contract: what it returns (artist_id), when to use it (conversation start/post-connect_catalogue), and session management (caching). While it doesn't enumerate all profile fields without an output schema, it captures the critical identifier needed for subsequent sibling tool calls.

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?

Input schema has zero parameters, which per calibration establishes a baseline of 4. The description correctly does not invent parameters, and the parenthetical mention of artist_id clarifies the return value rather than confusing it for an input 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 uses a specific verb ('Get') and clear resource ('artist profile'), and explicitly mentions the key return value ('artist_id'). It clearly distinguishes from sibling tools which are predominantly creation/update operations (create_work, update_work, etc.) versus this read operation.

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 temporal guidance ('Call at the START of every conversation — before responding') and references a specific sibling tool trigger ('Also call after connect_catalogue'). This is precise workflow instruction that tells the agent exactly when to invoke 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?

While annotations cover read-only/idempotent safety, description adds critical behavioral context: output is a 'readable narrative timeline' (not raw data/structured) and the tool 'Flag gaps as areas for research.' Could be 5 if it detailed what the chain contains (dates, owners, locations).

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 with zero waste: sentence 1 defines purpose, sentence 2 provides trigger phrases, sentence 3 covers presentation format, gap handling, and ID resolution. Perfectly front-loaded and appropriately sized.

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, description compensates by specifying the narrative format and gap-flagging behavior. Covers the essential workflow (search_natural_language prerequisite). Slightly short of 5 as it doesn't enumerate what provenance data points are returned (owners, dates, transactions).

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% coverage with the parameter already documented as 'Look up via search_natural_language.' Description reinforces this workflow instruction but does not add semantic meaning beyond what the schema provides, warranting the baseline score.

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 'Get the full provenance chain (ownership history) for a work' with specific verb and resource. It distinguishes from siblings like get_provenance_visual (emphasizes 'readable narrative' vs visual) and parse_provenance (emphasizes 'not raw 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?

Provides explicit TRIGGER phrases ('who owned this,' 'provenance,' 'ownership history'). Explicitly states to 'Resolve work_id via search_natural_language,' indicating the prerequisite workflow. Contrasts output format with raw data 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 declare readOnlyHint=true and idempotentHint=true; description adds the 'interactive' and 'visual' nature of the output (behavioral traits not captured in annotations). Does not contradict annotations. Minor gap: doesn't specify if output is a URL, embeddable HTML, or image data.

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 distinct, information-dense components: core function, trigger phrases, and sibling alternative. No filler text. Front-loaded with the essential capability, followed by actionable trigger guidance and clear disambiguation.

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 single-parameter, read-only visualization tool with rich annotations, the description is complete. It explains the output modality ('interactive visual timeline'), invocation patterns, and alternative tools. Absence of output schema does not detract given the descriptive clarity of what gets displayed.

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 description coverage, the schema fully documents the work_id parameter including lookup instructions ('Look up via search_natural_language'). The description doesn't add parameter details, meeting the baseline for high-coverage schemas without adding semantic value beyond the structured definition.

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

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

States specific action ('Display'), resource ('provenance'), and format ('interactive visual timeline'). Explicitly distinguishes from sibling get_provenance by contrasting 'visual' with 'text-only', leaving no ambiguity about which tool to select.

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 TRIGGER phrases ('show provenance,' 'ownership history,' 'who owned this') indicating exactly when to invoke. Clearly states the alternative tool ('use get_provenance instead') for the non-visual use case, creating perfect sibling 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=true and destructiveHint=false, covering safety. Description adds behavioral detail about working from either side of the relationship, enhancing transparency 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 each serve a distinct purpose: function, context, and workflow hint. No redundant information; 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?

For a simple read tool with one parameter and no output schema, the description covers purpose, parameter source, and use cases completely.

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 a clear description for request_id. Description reinforces the parameter's purpose by repeating the instruction to derive it from list_rai_requests, adding value.

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 explicitly states 'Read a single RAI request by ID,' clearly identifying the verb and resource. It distinguishes from siblings like list_rai_requests by specifying singular retrieval and the ability to work from either side of the relationship.

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 trigger phrases and explicit instruction to obtain request_id via list_rai_requests without asking the user, offering clear usage guidance. Lacks explicit when-not-to-use alternatives but context is sufficient.

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 indicate non-readonly and non-destructive nature. The description adds critical behavioral constraints beyond annotations: the 'no loop' warning suggests rate limits or side effects, and it clarifies this creates a single-use/upload context. Minor gap: doesn't describe link expiration or return format.

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 with zero waste: purpose definition, specific trigger condition, sibling alternative naming, and operational constraints. Front-loaded with the core action, making it 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?

Excellent coverage of decision-making context (when to use vs. upload_images) and workflow integration. Minor deduction for lack of output description—without an output schema, brief mention of what the link enables (e.g., temporary upload endpoint) would complete the picture.

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 83% schema description coverage, the baseline is 3. The description reinforces schema constraints ('Never ask about file format' aligns with mime_type schema description) but doesn't add significant semantic meaning beyond what the well-documented schema already provides.

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

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

The description opens with a specific verb ('Generate') and clearly identifies the resource (direct upload link) and scope (SINGLE image on a SPECIFIC work). It explicitly distinguishes from sibling tool 'upload_images' by contrasting single vs. general image uploads.

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 temporal workflow guidance ('immediately after creating a work'), clear when-not-to-use with named alternative ('For general image uploads... use upload_images instead'), and operational constraints ('Never call this tool in a loop').

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 establish read-only, idempotent, non-destructive safety profile. Description adds valuable behavioral context: specific fields returned (images, provenance, exhibitions, bibliography) and output formatting requirements (natural summarization vs raw field dumping). Does not contradict 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 sentences with zero redundancy: sentence 1 defines capability, sentence 2 defines triggers, sentence 3 defines ID resolution strategy, sentence 4 defines presentation rules. Information is front-loaded and every clause earns its place.

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

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

For a single-parameter retrieval tool with good annotations, the description is complete. It compensates for missing output schema by enumerating return data categories (images, provenance, exhibitions, bibliography) and includes presentation logic, leaving no critical 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?

Despite 100% schema coverage for the single work_id parameter, the description adds critical resolution semantics: 'Resolve work_id via search_natural_language — never ask the user.' This workflow instruction is essential context not present in the schema's technical format 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?

States specific verb ('Get') + resource ('work') + scope ('full details including images, provenance, exhibitions, and bibliography'). Clearly distinguishes from sibling search_works (finds works) and create_work/update_work (mutations) by emphasizing retrieval of comprehensive metadata for a specific work.

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 trigger phrases ('show me,' 'tell me about,' 'pull up') and clear workflow directive ('Resolve work_id via search_natural_language — never ask the user'). Also includes presentation instructions ('describe the image first... do not dump raw fields'), establishing clear boundaries for when and how to invoke versus 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 declare readOnly/idempotent hints, while the description adds crucial behavioral context about the returned data structure (listing specific components like 'trust metadata', 'attestation log', 'cryptographic credentials') since no output schema exists. It also explains resolution logic (workId vs uwi). Does not mention rate limits or error states, preventing a 5.

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

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

Six sentences, zero waste. Front-loaded with the core action, followed by enumerated return values, usage conditions with explicit alternatives, and workflow instructions. Dense but scannable, with no filler text.

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?

Excellent coverage given no output schema—the description enumerates all major data components returned. It also covers identification methods and sibling distinctions. Lacks only error-handling context (e.g., what happens if the workId is not found) to achieve a 5.

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

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

With 0 parameters, the baseline score is 4 per rubric. The description mentions 'workId' and 'uwi' as resolution methods, which creates a slight tension with the empty schema, but provides necessary context for how the tool identifies the target artwork (possibly via implicit context or undocumented 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 a specific verb ('Get') and resource ('full data bundle for an artwork'), then explicitly distinguishes from sibling tool 'get_work' by contrasting 'complete picture' vs 'lightweight queries'. The comprehensive list of included data fields (provenance, exhibition history, etc.) precisely defines the 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 states when to use ('complete picture for reasoning about an artwork — verification, purchase evaluation...') and when not to use with a named alternative ('For lightweight queries... use get_work instead'). Also provides clear workflow guidance ('To find the workId, use search_natural_language — never ask the user for 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 already indicate this is a mutable (readOnlyHint: false), non-destructive operation. The description adds valuable context beyond annotations: explains the authorization prerequisite, clarifies roster endorsements extend to future works automatically, and mentions it's typically used by galleries/dealers/institutions. 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?

Well-structured with purpose, prerequisites, parameter guidance, trigger phrases, and usage advice. Slightly verbose with the trigger examples, but every sentence adds value. Front-loaded with core functionality.

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 2-parameter mutation tool without output schema, the description provides excellent context about prerequisites, scope decisions, and typical use cases. Could benefit from mentioning what the tool returns or confirmation behavior, but covers most essential aspects given the annotations and schema coverage.

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 in the schema. The description adds semantic context about when to omit vs include work_id (roster vs per-work) and mentions resolution methods, but doesn't provide significant additional parameter details beyond what the schema already covers.

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 'countersigns an artist's RAI' (specific verb+resource), distinguishes it as a W3C Verifiable Credential, and specifies it's issued by the authenticated account. It explicitly differentiates from siblings like 'create_rai' (creates new) and 'revoke_endorsement' (removes).

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: 'Requires a prior authorization grant where the artist has enabled can_endorse for you.' Provides clear alternatives: 'Omit work_id for roster-level... Pass work_id to endorse a single RAI.' Includes trigger phrases and advises confirming scope before calling.

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 idempotentHint=true and destructiveHint=false, covering the technical safety profile. The description adds valuable domain context explaining that this creates a citation/illustration relationship rather than just a generic link. It does not contradict annotations, though it could explicitly mention the idempotent nature for clarity.

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 efficiently cover: (1) core purpose and semantics, (2) optional parameter usage, and (3) UUID resolution workflow. No redundant text; every clause provides actionable guidance or domain context.

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 an 8-parameter linking tool with no output schema, the description adequately covers the relationship semantics, prerequisite workflows, and optional data fields. It appropriately relies on annotations for mutation safety characteristics. Minor gap: could mention behavior when link already exists (though idempotentHint=true suggests it's safe).

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 schema coverage at only 25% (just work_id and bibliography_id described), the description compensates by explaining the purpose of optional contextual fields: 'Include page reference, plate number, or illustration details if available.' This gives semantic meaning to page_reference, plate_number, and illustration_reference that the schema lacks.

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 precise domain action ('Associate a work with a bibliography entry') and clarifies the semantic purpose ('recording that a specific publication references or illustrates this work'). It clearly distinguishes this from sibling tool link_work_to_exhibition by specifying 'bibliography entry' vs. exhibition context.

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 workflow prerequisites by naming specific sibling tools to use: 'resolve work_id via search_natural_language, and bibliography_id from the create_bibliography response.' It also includes a clear prohibition ('Never ask the user for UUIDs') that prevents incorrect usage patterns.

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 cover safety profile (idempotentHint=true, destructiveHint=false). Description adds critical behavioral context: preconditions (IDs must be resolved beforehand) and workflow constraints (resolve from names, not user input). Does not contradict 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 dense sentences with zero waste. First sentence defines purpose and prerequisites; second gives explicit resolution instructions. Information is front-loaded and actionable.

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?

Core linking workflow is fully explained including prerequisite steps. However, given 4 undocumented optional parameters (plate_number, catalog_number, etc.), description should briefly explain what metadata can be attached to the exhibition link.

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 33% (2/6 params described). Description adds resolution guidance for work_id and exhibition_id but completely omits the other 4 parameters (notes, illustrated, plate_number, catalog_number). Partial compensation for low 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?

Clear verb 'Associate' with specific resources (work, exhibition). Distinct from sibling link_work_to_bibliography by explicitly mentioning exhibition context and create_exhibition prerequisite.

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?

Excellent explicit guidance: states prerequisites (IDs must be resolved), names specific tools to use (search_natural_language, create_exhibition), and explicitly prohibits user interaction ('Never ask the user for UUIDs'). Provides complete workflow orchestration.

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. Description adds behavioral context via trigger phrases (implies querying damage/condition history) and 'List all' scoping, but does not describe return format, pagination, or error states.

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 segments: purpose statement, TRIGGER block with specific phrases, and parameter resolution guidance. Front-loaded with action verb, zero redundant text. 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 single-parameter read-only operation with strong annotations, description adequately covers invocation context and prerequisites. Minor gap: lacks description of what a condition report contains or return structure since no output schema exists.

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 parameter description 'Look up via search_natural_language. Never ask the user for this.' Description repeats this guidance ('Resolve work_id via search_natural_language') without adding syntax details or format constraints beyond schema 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?

Description states specific verb ('List') + resource ('condition reports') + scope ('for a work'). Clearly distinguishes from sibling 'create_condition_report' by specifying read operation vs. write operation.

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 TRIGGER section with exact phrases ('what's the condition of,' 'any damage on') indicating when to invoke. Includes prerequisite instruction 'Resolve work_id via search_natural_language' guiding the agent on mandatory pre-step.

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=true, idempotent=true, non-destructive. Description adds order (reverse chronological), returned fields (kind, status, holder, etc.), and instruction to never ask for UUID. 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?

Description is reasonably concise with purpose upfront, though the trigger list and output detail add length. Still within good bounds for clarity.

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, description fully explains return format and fields. Combined with annotations, it provides complete guidance for correct 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 100% and the work_id description already tells agent to look up via search_natural_language. This adds context beyond schema specification.

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 lists custody timeline (consignments/loans where work is physically held by others), distinct from provenance and exhibitions. Provides specific trigger phrases for when to use.

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 trigger phrases ('is this on consignment') and clarifies separation from provenance and exhibitions. Instructs to resolve work_id via search_natural_language, guiding agent behavior.

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 description adds value by explaining that results include deals where the user is owner, seller, buyer, or intermediary. No 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?

Two concise sentences with no wasted words. The purpose and key details are front-loaded. 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 the simple list operation with fully described parameters and read-only annotations, the description is complete. It explains visibility scope and filtering options. No output schema needed for this list 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 enum descriptions for state and direction. The description merely lists these filters without adding new meaning beyond the schema, 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 the tool lists deals and specifies filtering options (state, work_id, direction). It distinguishes from siblings like get_deal (single deal) or create_deal by focusing on listing and filtering.

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 indicates it lists deals the user can see based on roles, but does not explicitly mention when to use alternatives like search_works or get_deal. However, the context of 'list' vs 'get' or 'create' is implied.

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, non-destructive, idempotent, and closed-world behavior. The description adds valuable context: it includes revoked endorsements (not obvious from annotations) and clarifies filtering logic ('filter on revoked_at for currently active'), which enhances understanding beyond the structured 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?

Two sentences: the first defines purpose and scope efficiently, the second provides trigger examples. No wasted words; information is front-loaded with the core functionality stated immediately.

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 no parameters and good annotations, the description is nearly complete. It covers purpose, usage, and behavioral nuances. Minor gap: no output schema exists, and the description doesn't detail return format (e.g., list structure or fields), but this is partially mitigated by the clear scope.

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 0 parameters and 100% schema coverage, the baseline is 4. The description compensates by explaining implicit filtering aspects ('including revoked ones' and 'filter on revoked_at'), adding semantic context that the empty schema cannot provide.

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 ('List') and resource ('endorsements the current account has issued to other artists'), specifying scope ('roster-level and per-work, including revoked ones'). It distinguishes from sibling 'list_endorsements_received' by focusing on issued rather than received endorsements.

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 trigger phrases ('who have I endorsed,' 'show my endorsements,' 'which artists do I currently vouch for') provide clear when-to-use guidance. The mention of filtering on 'revoked_at for currently active' offers practical usage context, though no explicit alternatives are named beyond the sibling distinction.

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 cover read-only, non-destructive, idempotent, and closed-world behavior, so the description adds value by explaining that it includes revoked endorsements (with a filter hint) and specifies the account context ('current account as an artist'). It does not contradict annotations and provides useful context beyond them, though it could mention pagination or rate limits if applicable.

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 the core purpose, followed by details on endorser types and filtering, and ends with clear trigger phrases. Every sentence adds value without redundancy, and it's appropriately sized for a no-parameter tool.

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 0 parameters, rich annotations, and no output schema, the description is nearly complete. It covers purpose, usage, and behavioral nuances like revoked endorsements. A minor gap is the lack of explicit mention of output format or pagination, but this is mitigated by the annotations and simple nature of 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description adds semantic context by mentioning the 'revoked_at' filter for active endorsements, which is helpful for usage even though it's not a formal parameter. This exceeds the baseline of 3 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 clearly states the tool lists endorsements received by the current account as an artist, specifying the types of endorsers (galleries, dealers, institutions) and what they countersign (roster or specific works). It distinguishes from sibling 'list_endorsements_issued' by focusing on received endorsements, and from 'list_work_endorsements' by being account-centric rather than work-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?

The description explicitly provides trigger phrases ('who has endorsed me,' 'show my endorsements,' 'which galleries vouch for my work') that indicate when to use this tool. It also mentions the ability to filter on revoked endorsements, clarifying scope without needing to reference alternatives directly, as the tool name and context already differentiate it from issuance-focused siblings.

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 traits. The description adds valuable domain context about the catalogue scope and the specific workflow (finding IDs for updates) without contradicting the safety annotations. It clarifies that this operates on the artist's recorded location catalogue.

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 tightly constructed sentences with zero waste. The first sentence front-loads the core purpose with specific examples, while the second provides actionable usage context. Every word serves a distinct purpose in aiding tool selection.

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?

Adequate for a list tool but has gaps given the lack of output schema. It mentions finding 'place_id' which hints at return values, but fails to describe pagination behavior, search syntax, or the fact that all parameters are optional. Minimum viable for a 4-parameter 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?

With 0% schema description coverage, the description fails to compensate for undocumented parameters. While it implicitly hints at the place_type enum by listing example place types, it provides no explanation for page, per_page, or search parameters, leaving pagination and text search functionality undocumented.

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 specific verb (list) and resource (places in the catalogue), enumerates the exact place types supported (studios, galleries, museums, storage facilities, fair venues), and distinguishes from sibling tools like create_place by emphasizing this is a retrieval operation.

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 workflow guidance ('find a place_id before updating') and secondary use case ('see what locations the artist has recorded'), clearly indicating when to use this tool in the context of update operations. Lacks explicit 'when not to use' exclusions but effectively communicates its role in the data workflow.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false. The description adds valuable behavioral context beyond annotations: it specifies that returns include all statuses (pending, accepted, fulfilled, declined, expired) and that pending items need artist action, providing important operational details not covered by 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 efficiently structured with three sentences: purpose statement, usage triggers, and behavioral details about statuses and prioritization. Every sentence adds value with zero wasted words, making it easy to parse and understand quickly.

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 listing tool with comprehensive annotations and no parameters, the description provides excellent context about what's being listed, usage scenarios, and result interpretation. The only minor gap is no explicit mention of output format or pagination, but given the annotations and zero parameters, this is reasonably 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?

With 0 parameters and 100% schema description coverage, the baseline would be 4. The description appropriately doesn't discuss parameters since there are none, and instead focuses on what the tool returns and how to interpret results, which is the right emphasis for a parameterless tool.

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: listing incoming RAI requests, specifying it's an inbox of pull requests from various entities asking for verified records. It distinguishes from siblings like accept_rai_request and decline_rai_request by focusing on listing rather than actioning requests.

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 usage triggers with natural language examples ('show my requests', 'what RAI requests do I have', etc.) and clarifies that pending items need artist action and should be surfaced first, giving clear context for when to use 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?

Annotations already indicate this is a read-only, non-destructive, idempotent, and closed-world operation. The description adds valuable context beyond this by specifying that it lists only 'active (non-revoked) endorsements' and includes both per-work and roster-level endorsements, which clarifies the scope and filtering behavior not covered by 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 efficiently structured with two sentences: the first states the purpose and scope, and the second provides usage guidelines and triggers. Every sentence adds critical information without redundancy, making it front-loaded 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 tool's complexity (filtering active endorsements across scopes) and the absence of an output schema, the description is mostly complete. It clarifies what data is returned (active endorsements) and usage constraints, though it could benefit from mentioning the format or structure of the returned endorsements to fully compensate for the lack of output schema.

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

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

The input schema has 100% description coverage, fully documenting the single required parameter (work_id). The description reinforces the schema's guidance ('Look up via search_natural_language — never ask the user for this') but does not add significant semantic details beyond what the schema already provides, meeting 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 clearly states the specific action ('List'), resource ('active endorsements'), and scope ('for a specific work'), including both per-work and roster-level endorsements. It distinguishes this tool from sibling tools like 'list_endorsements_issued' and 'list_endorsements_received' by focusing on endorsements applied to a work rather than those issued or received by entities.

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 on when to use this tool (e.g., 'who has endorsed this work'), when not to use it (e.g., 'never ask the user for [work_id]'), and an alternative tool ('search_natural_language' for resolving work_id). It also includes trigger phrases to help the agent identify appropriate contexts.

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 critical behavioral context beyond annotations: clarifies it performs no URL fetching, explicitly warns that it 'has no job_id' (affecting workflow integration), and provides image handling instructions. Annotations cover safety (readOnly/idempotent), but description explains the extraction mechanics and workflow limitations.

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?

Information-dense with six distinct instructional sentences covering purpose, fallback conditions, manual fetching, review requirements, saving constraints, and image workflows. Slightly dense but no wasted words; front-loaded with the core function.

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?

Comprehensive for a parsing tool despite no output schema: mentions output is 'structured artwork records' for review, covers the complete workflow from fetching to saving, and addresses edge cases (images). Could benefit from describing the return structure explicitly given the lack of output schema.

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

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

With 100% schema coverage, the schema fully documents both parameters. The description adds workflow context ('fetch the page yourself... and pass the content here') but does not add semantic details about data formats or validation rules beyond what the schema already provides.

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

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

Clearly states the tool parses raw HTML/text into structured artwork records. Explicitly distinguishes from sibling 'extract_artwork_data' by noting 'no URL fetching' and positioning itself as a fallback, making the scope and differentiation precise.

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 when-to-use guidance ('fallback when extract_artwork_data returns zero works or fails'), instructs users to fetch content themselves via browsing/search, and specifies the correct downstream action ('save via create_works_batch (not confirm_website_import)').

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 declare readOnlyHint=true and destructiveHint=false, the description reinforces this ('Read-only — does NOT save') and adds critical workflow protocol: the requirement for a review step and confirmation before calling save_provenance. This behavioral constraint ('Never skip the review step') is not inferable from annotations and represents essential operational context for safe 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?

The description uses a disciplined structural pattern: safety warning first ('Read-only'), followed by trigger conditions, workflow sequence, and operational constraint. Every sentence serves a distinct function—defining scope, triggering context, process flow, or safety protocol—without redundancy. The front-loading of the read-only warning is particularly effective for agent decision-making.

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 comprehensively covers the tool's lifecycle by explaining it produces 'structured entries' for review and explicitly referencing the downstream save_provenance operation. Given the presence of sibling tools and the clear workflow orchestration provided, the description adequately compensates for missing return value documentation by defining the handoff to the next step in the sequence.

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 description coverage, the structured fields already document both the 'text' parameter (unstructured provenance input) and 'work_id' (optional UUID). The description aligns with these semantics by referencing 'provenance text' and the parsing operation, but does not add syntax details, format constraints, or examples beyond what the schema already provides. Baseline 3 is appropriate when schema carries the full descriptive 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 opens with a precise action ('Parse unstructured provenance text into structured entries') combining specific verb, input resource, and output format. It immediately distinguishes itself from sibling save_provenance by explicitly stating 'does NOT save' and clarifying its read-only nature, ensuring the agent understands this is a transformation/preview tool rather than a persistence operation.

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 TRIGGER conditions ('User pastes provenance text... or says "here's the provenance"'), a complete Flow diagram ('parse_provenance → present results for review → save_provenance'), and a mandatory exclusion ('Never skip the review step'). It explicitly names the alternative tool (save_provenance) for the write operation, creating a clear decision boundary 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 declare destructiveHint=true, but the description adds critical behavioral context: auto-creation of provenance entries, status mutation to 'sold,' and a required confirmation workflow ('explain the side effects before calling'). Deducted one point for lacking failure mode or rate limit disclosure.

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?

Information-dense and well-structured with logical flow: action → side effects → trigger conditions → workflow → prerequisites. Front-loaded with the core purpose. Slightly dense but every sentence earns its place by adding operational 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?

For a complex transactional tool with side effects and no output schema, the description adequately covers the operational contract: what changes (provenance, status), confirmation requirements, and ID resolution. Missing documentation for optional financial parameters prevents a perfect score.

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 only 15% schema description coverage (2 of 13 params), the description partially compensates by listing the 5 required parameters and explaining ID resolution strategies for UUID fields. However, 8 optional parameters (commission_rate, buyer_type, net_to_artist, etc.) remain completely undocumented in both schema and 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 explicitly states the core action ('Record a sale of a work') and distinguishes it from siblings by specifying unique side effects: 'Auto-creates provenance entry' and 'sets status to sold.' The resource (sale) and scope (of a work) are clearly 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?

Provides explicit trigger phrases ('I sold this,' 'a collector bought,' 'the gallery sold') indicating when to use the tool versus alternatives like create_work or update_work. Includes prerequisite guidance ('Resolve IDs via search_natural_language and get_profile') and workflow instructions ('Present a summary... before calling').

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 indicate destructiveHint=true and idempotentHint=true, which the description supports by implying irreversible action ('soft-revoke') and idempotence (no mention of errors on re-calls). It adds valuable context: the credential remains historically verifiable and is filtered from active endorsements, which annotations don't cover. 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?

Front-loaded with the core action, followed by effects, triggers, prerequisites, and a caution. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

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 (destructive mutation) and lack of output schema, the description is mostly complete: it explains purpose, usage, parameters, and behavioral outcomes. However, it doesn't detail the response format or error cases, which could be helpful for an agent. Annotations cover safety aspects, so this is a minor gap.

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 meaning by specifying that endorsement_id should come from 'list_endorsements_issued' and 'Never ask the user for this', which clarifies sourcing beyond the schema's UUID format. It doesn't detail the reason parameter, but this extra guidance justifies a score above 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 specific action ('soft-revoke an endorsement') and resource ('endorsement'), distinguishing it from siblings like 'issue_endorsement' or 'list_endorsements_issued'. It explains the effect: credential remains historically verifiable but is filtered from active endorsements.

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 when to use ('revoke my endorsement of [artist]', 'pull my countersign', 'I no longer represent [artist]'), prerequisites ('Find the endorsement_id via list_endorsements_issued'), and a caution ('Confirm before calling'). This gives clear context and 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?

Confirms WRITE nature (consistent with readOnlyHint:false) and adds critical safety context requiring user confirmation. Explains workflow sequencing and automatic sequence number assignment. Does not mention idempotentHint:false implications or duplicate 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?

Four sentences with zero redundancy. Front-loaded with safety warning and WRITE declaration. Workflow logic flows chronologically. Every sentence provides actionable guidance that cannot be inferred from schema/annotations alone.

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?

Adequate for complex nested structure given comprehensive schema coverage. Covers safety, workflow, and key parameter semantics. Could improve by noting idempotency behavior or confirming whether duplicate saves create duplicate entries given idempotentHint:false.

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?

While schema has 100% coverage, description adds crucial semantic guidance for 'source' parameter ('ai_parsed' vs 'manual') that explains the business logic behind the enum values. Elevates understanding beyond raw schema 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?

States specific action ('Save confirmed provenance entries to a work') with clear verb and resource. Explicitly distinguishes from sibling tool 'parse_provenance' by describing the workflow relationship.

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 workflow sequence ('Call parse_provenance first...present results for review, then use this tool'). Contains critical safety constraint ('NEVER call without user confirmation') that defines when NOT to use the 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 readOnly/idempotent safety, but the description adds valuable behavioral context about 'partial matches and title variations' and establishes it as the default entry point for ID resolution. Minor gap: doesn't describe return format despite no output schema.

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 dense sentences with zero waste: opens with role declaration ('DEFAULT search'), follows with capabilities, trigger conditions, workflow integration, and alternative routing. Every clause provides actionable 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?

Excellent coverage for a search tool given rich annotations and explicit sibling differentiation. Mentions ID resolution implying return content. Minor gap: doesn't specify result cardinality or pagination limits, though 'resolve work_ids' implies sufficient information for agent to proceed.

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 0% schema description coverage, the description fully compensates by providing rich semantic context for the 'query' parameter through concrete examples ('the blue painting', 'Self-Portrait', 'where's that piece I did last year') and explaining it accepts names, titles, or descriptive queries.

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 this is the 'DEFAULT search' for finding works by 'name, title, or any descriptive query' and clearly distinguishes it from the structured 'search_works' sibling tool by contrasting natural language queries versus structured filters.

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 TRIGGER examples ('Any mention of a work by name'), workflow guidance ('Use this to resolve work_ids before calling get_work...'), and names the specific alternative tool ('For structured filters... use search_works 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?

While annotations establish readOnlyHint=true and destructiveHint=false, the description adds critical behavioral context: the dual mode capability ('or get a count'), the conversational follow-up handling logic, and the strict architectural rule ('Never filter results in chat — re-call this tool for any filter change'). However, it omits details about pagination behavior or default sorting given the presence of page/sort parameters.

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 earns its place: purpose statement first, followed by trigger phrases, sibling differentiation, follow-up handling logic, and finally the critical instruction about recalling the tool. The dense, front-loaded structure uses exact trigger words ('TRIGGER:', 'Follow-ups:') for rapid agent parsing with zero redundant text.

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 12-parameter search tool with no output schema, the description adequately covers the primary use case (structured filtering) and critical constraints. It successfully explains the 'count' capability and conversational state management. However, it could improve by acknowledging the pagination or sorting parameters given their presence in the schema, and specifying what constitutes a 'work' in this domain 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?

With schema description coverage at only 25%, the description partially compensates by mentioning key filterable fields (status, date, medium, series). However, it fails to document the remaining 8 parameters including pagination (page, per_page), sorting (sort_by, sort_direction), artwork_type, or current_location_type, leaving significant gaps given the low schema coverage. It also doesn't clarify that date fields expect years despite the schema 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 opens with a specific verb+resource ('Filter works by structured fields') and explicitly lists the filterable dimensions (status, date, medium, series). It clearly distinguishes from sibling tool search_natural_language ('For title/name/descriptive queries, use search_natural_language instead'), ensuring the agent selects the correct tool for structured vs. natural language queries.

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 trigger phrases ('what do I have,' 'how many works') indicating when to invoke. Explicitly names the alternative tool for different query types. Includes concrete follow-up handling rules ('also/too → add filters; only/just → narrow') that guide multi-turn conversation flow, and a strict prohibition ('Never filter results in chat') that prevents incorrect usage patterns.

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/destructive hints. Description adds 'interactive visual grid' context which clarifies UI behavior not captured in annotations. However, omits pagination behavior (per_page max 50) and null-result 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?

Three sentences with zero waste. Front-loaded with purpose, followed by usage triggers, ending with alternative recommendation. 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?

Adequate for distinguishing the visual search modality from siblings, but incomplete given 11 parameters with low schema coverage. Lacks guidance on filter combinations, pagination limits, or search syntax despite complex filtering capabilities implied by the schema.

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

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

Schema coverage is only 27% (3/11 params described). Description fails to compensate—it mentions 'search results' generically but doesn't explain pagination (page/per_page), filtering options (status, medium), or sorting behavior despite these being undocumented in schema.

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

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

States specific action ('Display search results'), output format ('interactive visual grid'), and distinguishes from text-based sibling by emphasizing visual modality. Clear verb+resource combination.

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 the user wants to browse or see their works visually'), provides concrete trigger phrases, and names specific alternative tool ('use search_works instead') for text-only results.

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 significant behavioral context beyond annotations: it explains identity derivation, auto-invitation for artists not on the platform, gallery routing behavior, and where the fulfilled RAI lands. 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 well-structured, starting with the main purpose, then triggers, then special cases. It is slightly verbose but every section adds value. Could be slightly more concise.

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 (8 parameters, nested objects, no output schema), the description covers authentication, invitation, gallery routing, and confirmation. It lacks explicit error handling details but is otherwise 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 adds some context (e.g., work_description is loose, route_to_client is for galleries) but does not substantially extend the schema 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 submits a request for a verified RAI from an artist for a specific work. It includes specific verb+resource and distinguishes it from sibling tools like accept_rai_request and cancel_rai_request. The trigger phrases further clarify the use case.

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 trigger phrases and advises to confirm with the user, offering clear context. However, it does not explicitly compare to other RAI-related tools like accept_rai_request or fulfill_rai_request, which would strengthen 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 indicate read-only, safe, idempotent behavior. The description adds valuable context about data scope ('~2,500 major galleries, museums, and auction houses') and return behavior ('Returns matching entities') that annotations don't cover. Does not mention rate limits or auth requirements.

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 with zero waste: (1) Core function, (2) Usage context and data scope, (3) Return behavior and alternative. Information is front-loaded and efficiently 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?

For a search tool with no output schema, the description adequately explains the return purpose ('matching entities for autocomplete-or-create'). Annotations cover the safety profile. Could benefit from mentioning result limits or ranking, but sufficient 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?

With 0% schema description coverage, the description compensates effectively by indicating 'q' is for name search ('by name') and listing all enum values for 'entity_type' in the prose (people, galleries, museums, etc.).

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 for existing entities by name, lists all supported entity types (people, galleries, museums, etc.), and explicitly distinguishes this from the create_entity sibling tool by stating it's for checking duplicates before creation.

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 ('before creating a new entity to check for duplicates') and names the exact alternative tool ('create_entity') for the 'no match' case. Also describes the intended workflow ('autocomplete-or-create flow').

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?

Describes the state machine and that close_reason is required for closed_lost. However, it lacks details on side effects (e.g., whether changes are reversible, any notifications). Annotations are all false, so description carries burden; more depth would improve 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?

Two sentences plus an IMPORTANT note. Every word adds value. Front-loaded with purpose. 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?

Sufficient for a simple mutation tool with no nested objects or output schema. Describes state transitions and confirmation requirement. Missing details like return value or preconditions (e.g., deal existence), 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% with adequate descriptions. The description adds the ordering of states and reinforces the close_reason condition, but does not significantly expand beyond the schema. 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?

Clearly states the tool advances or closes a deal's state with specific transitions. The verb 'advance' and 'close' are precise, and the resource 'deal state' is unambiguous. It distinguishes from sibling deal tools like record_sale or get_deal.

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 to present the transition and get confirmation before calling. This is a strong usage guideline. However, it does not mention when not to use or compare to alternatives like record_sale.

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 declare idempotentHint=true and destructiveHint=false, the description adds crucial behavioral context: it specifies partial-update semantics ('Send only the fields that are changing'), clarifies the soft-delete/archive pattern versus hard deletion, and documents the ID resolution workflow. Does not contradict 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?

Every sentence serves a distinct purpose: operation definition, payload pattern, trigger examples, deletion handling, and ID resolution. No redundancy or filler text. The TRIGGER formatting efficiently communicates usage patterns without verbose prose.

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 high complexity (21 parameters, nested dimensions object) and lack of output schema, the description successfully covers the critical path: partial updates, status transitions including archiving, and the mandatory ID resolution workflow. Minor gap in not detailing the dimensions object structure or return behavior, but adequate for an update operation with idempotent 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?

With schema description coverage at only 5% (only work_id is documented in schema), the description partially compensates by referencing specific fields via trigger examples (title, dimensions, medium, status). However, it fails to document the remaining ~16 parameters (dimensions object structure, price_currency, edition fields, etc.), leaving significant semantic gaps the agent must infer from schema property names alone.

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 the specific action 'Update fields on an existing work,' clearly distinguishing it from sibling tools like create_work (which creates new records) and get_work (which retrieves). The verb-resource combination is precise and 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?

Provides explicit trigger phrases ('actually it's oil on canvas,' 'mark it as sold') indicating when to use the tool. Critically distinguishes deletion semantics by instructing to set status to 'archived' for 'delete/remove/clean up' requests rather than using a hypothetical delete tool. Also mandates the workflow 'Resolve work_id via search_natural_language — never ask the user,' establishing clear prerequisites.

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 states 'Upload images' which implies a write operation, but annotations declare `readOnlyHint: true`. This is a direct contradiction regarding the tool's mutability. While the description adds useful context about filename auto-matching and resolution preservation, the contradiction makes the safety profile unclear.

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 efficiently structured with clear sections (TRIGGER, IMPORTANT). While the trigger phrase list is lengthy, it serves a distinct purpose for agent routing, and the warning about chat compression is critical workflow 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?

Without an output schema, the description adequately explains the return value (link to upload page) and downstream behavior (drag-and-drop, filename matching, resolution preservation). It could be improved by mentioning error cases or supported file formats, but covers the essential workflow.

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 zero parameters, the baseline score is 4 per evaluation rules. The description appropriately focuses on behavioral semantics rather than parameter documentation since no inputs are required.

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 'Upload images to the catalogue' using a specific verb and resource. It distinguishes from sibling tools like `get_upload_url` by clarifying this returns a drag-and-drop page link for artists rather than a programmatic upload endpoint.

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 when-to-use guidance ('Use this tool for ANY image upload request') and specific TRIGGER phrases. Critically, it includes when-not-to-use guidance: 'Never ask the artist to send or attach images in chat,' preventing incorrect usage patterns.

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