Grabblist

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

Beyond annotations, the description discloses two key behaviors: Grabblist does not monitor prices or auto-update data, and the server attempts to fetch og:image if no image is provided. These add meaningful context. It does not mention duplicate handling or return values, but annotations already indicate idempotentHint=false, reducing the need.

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

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

The description is three concise sentences, each providing valuable information without filler. It front-loads the main purpose and then adds essential behavioral notes, 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?

For a tool with 21 parameters and no output schema, the description covers the most significant non-obvious aspects: static snapshot semantics, price non-monitoring, and image fetching. It does not explain what the response looks like or how duplicates are handled, but given the rich schema and annotations, it 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?

All 21 parameters have descriptions in the schema, giving 100% coverage. The description adds a general instruction to only include fields with values available from the source, but this is not parameter-specific. The image auto-fetch behavior is already stated in the image parameter description, so the description adds little beyond the schema.

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

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

The description clearly states the tool saves an item to the user's Grabblist, with the specific verb 'Save' and resource 'item'. It distinguishes itself from sibling tools like update_item by emphasizing it creates a static snapshot. The scope is 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?

The description provides strong context on usage through 'Only include fields with values available from the source' and explains the static snapshot behavior, which implies when this tool is appropriate. It does not explicitly name alternatives like update_item, but the context is clear enough for an agent to infer.

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

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

Annotations already provide idempotentHint, destructiveHint, and readOnlyHint, covering the safety profile. The description adds useful behavioral context by stating that the item and collection must already exist, clarifying that this operation does not create new entities. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with no fluff. Every word contributes to understanding the tool's function and prerequisites.

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 mutation tool with no output schema, the description covers the essential context: action and preconditions. It doesn't explain error behavior or return values, but those are not required given the tool's simplicity and existing 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?

The input schema has 100% coverage, with descriptions for all parameters (item_id, collection_id, reason). The description itself does not add parameter-specific information beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action: 'Add a saved item to a collection.' It uses a specific verb and resource, and the requirement that both must already exist distinguishes it from sibling tools like add_item (which creates a new item) and create_collection.

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

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

The description gives clear context by stating that both the item and collection must already exist, which serves as a prerequisite and implies when to use the tool (not for creation). It does not explicitly name alternative tools or exclusions, but it is sufficient for this straightforward operation.

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 discloses the agent's behavior (knows user's data, can answer/compare/advise/analyze) and an important prerequisite (requires Anthropic API key in Settings). Annotations already indicate non-read-only, open-world, non-idempotent behavior; the description adds dependency and capability context without contradicting the annotations.

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

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

Four concise sentences, each earning its place: function, capabilities, usage directive, and prerequisite. No filler or repetition. The most important information is front-loaded.

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

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

For a tool with only two well-documented parameters and no output schema, the description covers the essential context: what it does, what it can assist with, when to use it, and a required configuration. The lack of response format or side-effect details is a minor gap, but the open-world annotation suggests unpredictability that is implicitly captured.

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

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

Schema covers 100% of parameters with meaningful descriptions (model enum with speed/cost notes, message with max length and content description). The description adds little beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb ('Delegate') and resource ('Grabblist's built-in AI assistant'), then immediately lists concrete capabilities (answer questions, compare items, give shopping advice, analyze saved products). This clearly distinguishes the tool from sibling CRUD tools like add_item or update_item.

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

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

Provides explicit usage direction: 'Use this when you want a second opinion or a specialized shopping assistant perspective.' This clearly signals when to invoke the tool. It stops short of naming specific alternatives or giving when-not-to-use guidance, but the context is clear enough.

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 a non-readonly, non-destructive mutation, but the description adds no additional behavioral context beyond what annotations already convey. It does not mention side effects, limits, or authentication 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?

The description is a single, clear sentence with no redundancies, front-loading the core purpose and resource.

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 create operation with a well-described schema, the description is adequate, but it lacks any mention of return value, success behavior, or usage context. The absent output schema and minimal behavioral guidance leave room for improvement.

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

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

The input schema provides detailed descriptions for all 7 parameters (100% coverage), so the description does not need to compensate. It adds no extra parameter meaning, but the baseline 3 is appropriate given the schema richness.

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 action (create) and resource (new collection/folder) within the user's Grabblist, with the purpose of organizing saved items. This distinguishes it from sibling tools like update_collection, delete_collection, and list_collections.

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

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

Usage is implied—use this when you need to create a new collection—but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or 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?

Annotations already mark this as destructive, but the description adds valuable context: the deletion is permanent and items within the collection are unaffected. This goes beyond the annotation hints and clarifies side effects.

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

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

The description is a single, front-loaded sentence that conveys both the action and the key exception. No wasted words.

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

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

For a simple two-parameter tool with strong annotations and full schema coverage, the description is complete. It covers purpose, destructive nature, and the non-destructive effect on items, which is 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?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds no additional parameter semantics 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?

The description states a specific action ('Permanently delete a collection') with a clear resource. It also distinguishes from sibling tools like delete_item and remove_from_collection by clarifying that items inside are not deleted, which is a key scoping detail.

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 context by explaining that items stay in the Grabblist, but it does not explicitly mention alternatives or when not to use the tool. The guidance is inferred rather than stated.

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

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

Annotations already mark this as destructive and non-read-only. The description adds valuable context beyond those hints by specifying 'soft-delete' (indicating the operation is recoverable) and noting that the reason parameter is shown to the user in change history. 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 sentences, front-loaded with the main purpose, no redundancy. Every word 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 simple mutation tool with 2 parameters and solid annotations, the description is complete. It explains the core behavior (soft-delete), batch support, and the schema covers the reason field. No output schema exists, so return-value detail is not required.

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

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

Schema coverage is 100%: both id and reason have descriptions. The description restates id flexibility ('single id or array') but adds no new semantic detail beyond what the schema already provides. 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 action: 'Remove one or more items from the user's Grabblist (soft-delete).' It specifies a concrete verb and resource, distinguishing it from sibling tools like delete_collection (targets collections) and restore_item (the inverse 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 clear context that this is for removing items and mentions batch operations, which is useful guidance. However, it does not explicitly name alternatives or exclusion cases (e.g., 'use delete_collection for collections' or 'use restore_item to undo'), though the soft-delete hint implies reversibility.

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, and idempotentHint=true, so the safety profile is fully disclosed. The description adds the list of event types, which is useful behavioral context, but it does not mention return format, ordering, pagination, or any side effects beyond what annotations imply.

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

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

The description is a single sentence with minimal words, front-loading the action and resource. It is concise with 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?

For a simple read-only tool with good annotations and schema, the description is adequate. It communicates the purpose and event types, but could be slightly more complete by hinting at the return format or default ordering. The absence of an output schema is mitigated by the straightforward nature of the 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?

Schema description coverage is 100%, so both limit and collection_id are documented in the schema. The description does not add any parameter-specific information, warranting the baseline score of 3.

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

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

The description clearly states the tool retrieves recent activity on a collection, specifying event types (additions, removals, edits). This verb+resource structure is specific and distinguishes it from sibling tools like get_item_history, which target item-level activity.

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

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

The description provides clear context: it is for collection-level activity events. However, it does not explicitly mention alternatives or exclusion conditions, so it stops short of the highest rating. The context is unambiguous enough for an agent to infer when to use it.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint). The description adds useful context such as 'static snapshot' and 'user's Grabblist', but does not disclose details about error handling or the exact contents of the snapshot.

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 short sentences with no wasted words. The action and target are front-loaded, making the purpose immediately apparent.

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 1-parameter read tool with robust annotations, the description is adequate. It states what it does and the nature of the return ('static snapshot'). The lack of an output schema leaves the exact fields ambiguous, but given the simplicity, 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 has 100% coverage for the single parameter 'id', described as 'The item ID'. The description only repeats 'by ID' and adds no additional semantic meaning, 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 uses a specific verb ('Get') and clearly specifies the resource ('full details of a saved item by ID'). It explicitly mentions 'static snapshot', which differentiates it from sibling tools like get_item_history or get_item_graph.

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 a clear read-only use case but does not explicitly compare with alternatives or state when not to use it. The phrase 'static snapshot' hints at a distinction, but direct guidance on tool selection is missing.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds value by disclosing the return structure ('Returns the item and all connected items with their relation types'), giving behavioral insight beyond the safety profile without contradicting annotations.

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

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

The description is one concise sentence, front-loaded with the primary action and specific relation types. Every word contributes to understanding, with no filler or redundancy.

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

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

For a low-complexity, single-parameter read-only tool with rich annotations, the description adequately states what it does and what it returns. It could specify whether the graph is recursive or direct, but this ambiguity is acceptable given the simple schema and supportive 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?

The single parameter 'id' is fully described in the schema ('The item ID to get relations for'), so the description adds no additional semantic meaning. With high schema coverage, the baseline score of 3 is appropriate.

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

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

The description uses specific verb 'Get' with resource 'all relations for an item' and explicitly lists relation types (alternatives, complements, upgrades, duplicates). This clearly distinguishes it from siblings like get_item, which fetches a single item.

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

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

The description provides clear context: use this tool to retrieve all relations for an item. It does not explicitly name alternatives or give when-not-to-use guidance, but the scope is evident from the phrase 'all relations', making it distinct from get_item, link_items, and similar sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result includes 'who changed what and when' but does not disclose pagination behavior, ordering, or that the default limit is 20 (though the schema covers the limit parameter). This is useful context but not rich behavioral disclosure 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?

The description is a single, front-loaded sentence with no filler. Every word adds value: 'Get', 'change history', 'saved item', and 'who changed what and when'.

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

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

The tool is a simple read-only history lookup. The schema covers both parameters, annotations cover safety and idempotency, and the description precisely explains the nature of the returned data. No output schema is needed because the return type is clear from the description. It is complete for its complexity.

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

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

The input schema has 100% coverage, with both item_id and limit fully described. The description does not add additional parameter-level meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get') and a specific resource ('change history for a saved item'), and further clarifies the payload ('who changed what and when'). This clearly distinguishes it from sibling tools like get_item (current state) and get_collection_activity (collection-level activity).

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

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

It clearly implies the tool is for retrieving change history of an individual item, which gives context for when to use it. However, it does not explicitly mention alternatives or situations where a different tool (e.g., get_item for current state) would be preferable, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable context beyond that: items are static snapshots, so prices reflect the save time, not current values. This warns users about potential staleness, which is critical behavioral information.

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 exceptionally concise, with two sentences that deliver a clear purpose and a key behavioral caveat. It is front-loaded with the verb and resource, with no wasted words.

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

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

For a simple read-only list tool with no output schema, the description is adequately complete. It explains what is returned (all saved items) and the snapshot nature, but does not describe the return format or default ordering. The lack of output schema is partially mitigated by the simplicity and annotations.

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

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

Input schema covers 100% of parameter descriptions (limit and platform), so the description does not need to add parameter details. Baseline of 3 is appropriate; no additional semantic value is provided.

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') with a clear resource ('all saved items from the user's Grabblist'), immediately differentiating it from sibling tools like search_saved. The added note about static snapshots further clarifies the tool'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?

The description implies when to use it (when you need all saved items) but provides no explicit guidance on when not to use it or alternatives like search_saved for filtered queries. It lacks exclusions or comparative 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=false and idempotentHint=true, so the description doesn't need to restate that this is a write operation. The description adds value by explaining the semantics of each relation type and the single/bulk modes, but it doesn't disclose behaviors like whether existing links are overwritten, whether items must exist, or what happens on duplicate attempts. With annotations covering the core safety profile, this is adequate but not enriched.

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

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

Two sentences, front-loaded with the primary action, and every phrase earns its place: the first sentence lists the relation types with brief definitions, and the second sentence covers both invocation modes. No filler or redundancy.

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

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

The tool has 5 parameters, no output schema, and annotations. The description covers all parameter semantics, explains the relation enums, and distinguishes single vs bulk usage, which is sufficient for an agent to invoke it correctly. Minor gaps like return behavior or error handling are not explicitly mentioned, but the annotation set and schema provide good context, making this fairly 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% (every parameter has a description in the schema), so baseline is 3. The tool description adds meaningful semantics beyond the schema by explaining the enum values with parentheticals (e.g., 'alternative (A or B)', 'upgrade (B replaces A)') and clarifying how 'pairs' relates to bulk mode versus individual from_id/to_id/relation. This extra context pushes it 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 uses a specific verb ('Create') and clear resource ('typed relations between items'), enumerates the exact relation types (alternative, complement, upgrade, duplicate, same_seller), and distinguishes this tool from siblings like unlink_items and add_to_collection by focusing on typed relational links rather than generic collection membership.

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 by showing two modes (single pair and bulk) and explains the meaning of each relation type, but it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions like 'use unlink_items to remove relations'. The context of creating links is clear, but no explicit when/when-not guidance is provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds behavioral context: it explains the two modes and what is returned ('counts/values' vs 'metadata and all items inside'). This goes beyond the annotations and helps the agent predict the tool's output shape.

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

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

The description is a single, well-structured sentence with two clear conditional clauses. It front-loads the main verb and resource, and there is zero wasted text. It is concise yet informative.

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

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

The tool has 8 optional parameters and no output schema. The description covers the core behavior and return content for both modes. While it doesn't describe the exact response structure for items or collections, the schema and the phrase 'optional filters' provide sufficient context for an agent to invoke the tool correctly. It is complete enough for a read-only list/get 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?

Schema description coverage is 100%, with each parameter explained in the schema (e.g., 'only when id is provided'). The description adds only a generic mention of 'optional filters,' which adds little meaning beyond the schema. Since the schema already carries the parameter semantics, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's dual purpose: 'List all collections OR get a specific collection with its items.' It uses specific verbs ('List', 'get') and identifies the resource ('collections'), making it distinct from sibling tools like get_item or search_saved. However, it doesn't explicitly contrast itself with siblings, so I deducted one point.

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

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

The description provides clear usage context: 'Without id: returns all collections... With id: returns that collection's metadata and all items inside.' This tells the agent when to omit or provide the id, and that filters apply only with id. It doesn't mention exclusions or alternatives explicitly, but the guidance is clear and practical.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, lowering the bar. The description adds that the tool returns the service version, which is a useful behavioral detail beyond the annotations. There is no contradiction between description and 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?

A single, front-loaded sentence that conveys the essential action and return value. Zero wasted words; every part 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 zero-parameter, simple connectivity test with comprehensive annotations, the description is fully complete. It states the action and the return value, and no output schema is needed. There are no gaps.

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

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

The tool has zero parameters, so the description has no parameter semantics to explain. The schema is trivially covered (100%). Baseline for zero parameters is 4, and the description adds nothing needed.

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

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

The description clearly states the tool's function with a specific verb ('Test') and resource ('connectivity to Grabblist'), and also indicates the return value ('service version'). This distinguishes it from all sibling tools, which focus on item/collection management, not connectivity.

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 purpose is self-evident: use this tool when you need to verify connectivity to Grabblist. No alternatives are mentioned, but none exist among the siblings. The description implies a clear use case without explicit exclusions, which is sufficient for a simple ping 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 provide readOnlyHint=false, destructiveHint=false, and idempotentHint=true, but the description adds crucial behavior beyond these: it clarifies that items are NOT deleted, which is a key nuance that could otherwise be misunderstood. It also discloses batch removal behavior, adding value beyond the structured 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 two concise sentences, front-loaded with the main action, and includes a critical caveat. Every sentence adds value, with 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?

Given the tool's moderate complexity, full schema coverage, and presence of annotations, the description is complete. It explains the core operation, the batch capability, and the non-destructive nature. No output schema exists, so not explaining return values is acceptable.

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

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

The schema covers all parameters with descriptions (100% coverage), so the baseline is 3. The description merely restates the batch/array option already present in the schema ('Pass a single item_id or an array of item_ids') but adds no new meaning for the 'reason' or 'collection_id' 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 clearly states the action: 'Remove one or more items from a collection.' It distinguishes from sibling tools like delete_item by explicitly noting that 'Items are NOT deleted — they stay in the Grabblist.' This provides a specific verb+resource+scope and differentiates it from similar operations.

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

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

The description gives clear usage context: it explains batch removal via a single item_id or array, and the non-deletion warning tells users this is not the tool for permanent deletion. However, it does not explicitly name alternatives like delete_item or restore_item, so it misses the 'explicit when-not' threshold for a 5.

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

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

Annotations already provide key behavioral traits: readOnlyHint=false (mutation), destructiveHint=false (non-destructive), and idempotentHint=true. The description adds the nuance that items are 'deleted (archived)' and supports batch restore, but it does not disclose additional side effects, prerequisites, or response behavior. Since annotations cover the safety profile, the description offers some extra context but not much beyond the 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?

The description is two concise sentences with no filler. It front-loads the core action ('Restore one or more deleted (archived) items') and immediately clarifies usage for batch restore. Every word 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 simple restore tool with only two parameters and no output schema, the description covers the essential purpose and batch capability. It does not explain return values or failure scenarios, but given the low complexity and the presence of sibling tools like delete_item that provide context, the description is sufficiently complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, with the id parameter described as 'Item ID or array of item IDs to restore' and reason as 'Why this change was made'. The description reinforces the id parameter by saying 'Pass a single id or an array of ids', which adds minor clarity but largely repeats the schema. No additional meaning is provided for the reason parameter, so the baseline of 3 is appropriate.

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

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

The description uses the specific verb 'Restore' with the resource 'deleted (archived) items' and clearly states the action of bringing them 'back to the Grabblist'. It distinguishes itself from siblings like delete_item and update_item by specifying the exact scope (restoring deleted/archived items) and supports batch via arrays.

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 implicitly conveys when to use the tool: when items are deleted/archived and need to be brought back. It also clarifies the two modes (single id or array) for batch restore. However, it does not explicitly state exclusions or alternative tools (e.g., 'use delete_item to remove items'), but the context is clear enough given sibling tool names.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds no additional behavioral details (e.g., pagination, sorting), but for a simple search operation, the annotations sufficiently disclose behavior. 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?

The description is a single, concise sentence with no filler. It front-loads the action and resource, making it easy to parse. Every word 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 simple search tool with only two parameters and no output schema, the description is mostly complete. It identifies the scope ('saved items') and the action ('keyword search'). The only minor gap is not defining what 'saved items' includes, but given the sibling tools and context, this is sufficient.

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

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

Schema description coverage is 100%, with both 'query' and 'limit' having descriptions. The description adds no extra semantics beyond the schema, so the baseline of 3 applies. The schema already explains the parameter meanings.

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

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

The description clearly states the tool's function: searching the user's saved items by keyword. It uses a specific verb and resource, distinguishing it from sibling tools like get_item or list_collections. No ambiguity in what it does.

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: when you need to search saved items. It doesn't explicitly mention alternatives or exclusions, but the context is clear enough for a search tool. No when-not-to-use guidance is provided, but it's not misleading.

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=false, so the agent knows this is a mutating action. The description adds context ('The team reads these to improve the product') and a directive to be specific, but does not disclose details like whether the operation is fire-and-forget, returns a confirmation, or has rate limits. With annotations covering the safety profile, a score of 3 is appropriate.

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

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

The description is three sentences, each with clear value: purpose, when to use, and how to write a good message. Information is front-loaded, with the most critical element (what the tool does) first. No wasted words.

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

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

For a simple feedback tool with no output schema, the description covers the essential aspects: what it does, when to use it, and what content to provide. It could optionally mention whether any response is expected, but this is a minor omission. The schema covers all parameters, and sibling tools are clearly distinct, so the tool is adequately contextualized.

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's advice to 'Be specific about what went wrong and where' reinforces the 'message' field but does not add new parameter-level information. The schema already documents each parameter thoroughly, including enum meanings for 'type'.

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 clear verb ('Send') and resource ('feedback, bug report, or feature request'), explicitly naming the target ('Grabbit team'). It distinguishes itself from sibling tools, which all focus on items/collections, by being the only feedback channel.

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

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

The description provides explicit when-to-use scenarios: 'encounter parsing failures, missing features, broken URLs, or have improvement suggestions.' It does not mention alternatives or exclusions, but since it is the only feedback tool among siblings, this is not a significant gap. The context is clear and actionable.

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

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

The description discloses that the operation sets the pinned items (implying replacement), enforces a maximum of 3, and results in sharing-page highlighting. While annotations already mark it as idempotent and non-destructive, the description adds the effect and limit, giving the agent expectations beyond the 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?

Two short sentences with no filler. The first sentence states the action and constraint; the second explains the effect. 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 write operation with a 3-parameter schema and no output, the description covers the purpose, constraint, and effect. It could be slightly more explicit about replacing the entire pinned list, but 'Set' conveys that. Overall sufficient.

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

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

All three parameters are fully documented in the schema with descriptions. The description doesn't add parameter-specific details, but since schema coverage is 100%, the baseline of 3 is appropriate. No additional semantics are needed.

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

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

The description clearly states the specific action ('Set the pinned "Top Picks" items') and resource ('for a collection'), with a critical constraint ('max 3'). It distinguishes from sibling tools like add_item or update_collection by naming the unique Top Picks feature.

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 when to use it (to set pinned Top Picks) but does not explicitly contrast with alternatives or state when not to use it. The 'max 3' limit provides a usage rule, but there is no mention of exclusions or prerequisites like collection ownership.

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 destructiveHint and idempotentHint, so the description adds no additional behavioral context. It doesn't clarify what happens if the relation doesn't exist or whether the removal is permanent. With no extra disclosure beyond the annotations, this falls short.

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

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

The description is a single, concise sentence that is front-loaded with the key action. No wasted words.

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

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

While the description is clear, it lacks context about side effects, prerequisites, or interaction with the change history (though the reason parameter is described in the schema). Given the simplicity of the tool, this is adequate but not rich.

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 no additional parameter meaning beyond the schema, but it doesn't need to since the schema is comprehensive.

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 ('Remove') and resource ('a relation between two items'), clearly conveying the tool's function. It contrasts with the sibling tool 'link_items', making the purpose unmistakable.

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 states the operation but provides no explicit guidance on when to use it versus alternatives. The usage is implied by the verb 'remove' but no exclusions or alternative references are given.

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

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

Annotations already indicate a non-read, non-destructive, idempotent operation. The description adds valuable behavioral context: omitted fields remain unchanged, and setting is_public=true generates a public URL while false unshares. This goes beyond the annotations without contradicting them.

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

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

Two sentences front-load the action, list the updatable fields, and provide key usage instructions. No filler or redundancy; 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?

For a 9-parameter update tool with no output schema, the description covers the main semantics, partial update behavior, and the public URL side effect. It doesn't address error cases or return values, but the annotations and schema cover safety and parameter details, making the description adequate.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the partial-update semantics ('only provide fields you want to change') and clarifying the sharing behavior, which is not obvious from individual parameter 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 updates a collection's name, icon, description, budget, or sharing status. This is a specific verb+resource with a clear list of updatable attributes, distinguishing it from create/delete/list siblings.

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

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

The description provides clear context that this is for updating existing collections and explicitly instructs to include only changed fields, defining partial-update usage. It doesn't explicitly compare with alternatives, but the purpose clarity makes the use case obvious.

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

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

Annotations already establish the tool as mutating, non-destructive, and idempotent. The description adds valuable batch-specific behavior: attributes are REPLACED not merged, and og:image fallback is skipped. These are important edge-case disclosures that go beyond the annotations.

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

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

The description is two sentences with no redundancy. The first sentence states purpose and scope; the second sentence covers batch-specific gotchas. Every word 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 tool with 15 parameters, batch behavior, and no output schema, the description covers the most critical caveats: how to batch, replacement semantics, and the og:image fallback skip. It does not mention error handling or return format, but the schema and annotations are already rich, and the description provides enough to use the tool safely.

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

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

The schema already covers all 15 parameters with detailed descriptions (100% coverage), so the baseline is 3. The description adds meaningful nuance by clarifying that the 'attributes' parameter behaves differently in batch mode (replaced, not merged), which is not obvious from the schema's 'Merge into existing attributes'.

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 'Edit fields on one or more saved items,' which is a specific verb+resource+scope. It clearly distinguishes itself from siblings like add_item, update_collection, and update_price by focusing on editing existing items, and further specifies single vs. batch updates.

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

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

The description provides clear context for when to use this tool (editing saved items) and explains batch vs. single usage. It does not explicitly name alternatives (e.g., 'use add_item to create'), but the verb 'edit' and 'saved items' makes the intended use unambiguous.

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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by stating that it 'records old and new price for comparison' and clarifying it is a manual correction, which goes beyond the raw annotation values.

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

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

The description is three concise sentences, front-loaded with the primary action. Every sentence adds distinct value: what it does, side effect (recording old/new), and a clarification of its scope.

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 mutation tool with full schema coverage and clear annotations, the description is nearly complete. It explains the purpose, the side effect, and the intended context. A minor gap is lack of explicit mention of required fields or prerequisites, but the schema covers those.

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 descriptive parameter details (e.g., 'New current price', 'Why this change was made'). The description adds minimal parameter meaning beyond clarifying that the update writes the new price and preserves the old for comparison, 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's function: 'Manually update the price on a saved item.' It uses a specific verb ('update') with a specific resource ('price on a saved item') and distinguishes this from automatic price tracking, which separates it from siblings like update_item.

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

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

The description provides clear context for use: it is a manual correction rather than automatic price tracking. While it does not explicitly name alternative tools like update_item for editing other fields, the 'not automatic price tracking' exclusion helps an agent decide 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.