Grabblist

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

Adds real behavioral context beyond the annotations: the save is a static snapshot with no price monitoring or auto-updating, and the server auto-fetches og:image when none is supplied. This is exactly the kind of consequence disclosure annotations can't carry. It omits duplicate/idempotency behavior, which matters given idempotentHint=false, so it is not 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?

Four short sentences, front-loaded with the core action and the snapshot caveat before the field-level advice. Efficient, though the price and image notes duplicate the schema and could have been dropped.

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 21-parameter mutation with no output schema, the description covers the essential snapshot semantics and the image fallback, but says nothing about what is returned, whether duplicates create new items (idempotentHint=false), or auth requirements. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, and the description largely repeats it — the price-optional and image auto-fetch notes are already present in the schema property descriptions. 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?

States a specific verb+resource: 'Save an item to the user's Grabblist.' An agent knows this is a create operation on a single item. It does not, however, distinguish itself from close siblings like add_to_collection or update_item, so it stops short of a 5.

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

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

Gives conditional guidance about parameters ('omit price for videos', 'only include fields with values available from the source') but says nothing about when to choose add_item over add_to_collection or how it relates to update_item. Usage is implied rather than contextualized against alternatives.

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

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

Annotations already 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?

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 already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds the crucial nuance that the destruction is scoped to collection membership — items survive in the Grabblist — which resolves the apparent tension with destructiveHint. It does not mention the reason field's side effect 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?

Three short sentences, front-loaded with the core action, then the batch mechanism, then the critical non-destructive clarification. Every sentence earns its place with no filler.

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

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

For a 3-parameter mutation tool with full schema coverage and annotations that already carry the safety profile, the description covers the one genuinely ambiguous point (membership removal vs. deletion). No output schema exists, so return values need not be explained. Only the reason parameter's provenance is unaddressed.

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 all three parameters are already documented in the schema. The description restates the single-vs-array behavior of item_ids but adds no syntax or format detail beyond it, and says nothing about the reason parameter. Baseline 3 applies when 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?

States a specific verb (Remove) and resource (items from a collection), and immediately disambiguates from the destructive sibling delete_item by clarifying that items are NOT deleted. An agent can tell this apart from delete_item without opening either schema.

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

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

It explains the mechanics of batch vs single removal (single item_id or array), which implies the intended calling pattern, but gives no explicit guidance on when to prefer this over delete_item or restore_item beyond the 'not deleted' note. Usage is implied rather than stated.

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

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

Annotations already 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 destructiveHint=true, readOnlyHint=false and non-idempotent, so the safety profile is partly covered. The description adds a behavioral requirement annotations cannot express: confirm the message content with the user before sending. It does not describe what happens after submission (acknowledgement, ticket id), leaving a modest gap.

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 action, then the qualification for calling it. Slightly dense in the second sentence with the parenthetical triggers and the confirmation instruction, but every clause carries 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 fire-and-forget submission tool with no output schema and full schema description coverage, the definition covers purpose, gating conditions and content expectations. It omits what the caller should expect back or whether duplicate reports are deduplicated, which is a minor but real 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 coverage is 100% with per-field descriptions and an enum for `type`, so the schema does the heavy lifting. The description only gestures at parameters vaguely ('be specific about what went wrong and where'), adding no format or mapping detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb plus three concrete resources (feedback, bug report, feature request) and names the recipient (Grabblist team). No sibling tool overlaps with this, so the agent can identify it immediately from the name and first clause.

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 constrains invocation: only when the user asks to report something or agrees after an offer, with the concrete triggers enumerated (parsing failure, broken URL, missing feature). It also imposes a pre-call step ('show them the message first'), which is exactly the kind of when/how guidance most definitions omit.

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 this as a non-read-only, destructive, idempotent write, so the safety profile is covered. The description adds the max-3 cap and the fact that pins surface on the share page, but does not say that existing pins are replaced or what happens on overflow.

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, zero filler, with the core action and its hard constraint front-loaded before the secondary note about share-page highlighting.

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 annotations carry the write/destructive/idempotent profile and the schema fully documents all three parameters, the description covers what the tool does and its key limit. Only the replacement semantics and permission prerequisites are left implicit.

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 collection_id, item_ids and reason are already documented (including display order for item_ids). The description only adds the max-3 constraint, which is a marginal increment over the 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?

States a specific verb (Set) and resource (pinned "Top Picks" items for a collection), plus the scoping rule (max 3) and the user-visible effect. It is distinguishable from siblings like add_item or update_collection, though it does not name an alternative explicitly.

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?

No when-to-use guidance, no prerequisites (e.g. ownership of the collection), and no mention of how this differs from update_collection or add_item. The only usage-shaped detail is the max-3 constraint, which is a limit rather than guidance.

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

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

Annotations already declare 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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=true), so the bar is lower. The description still adds real value beyond them: partial-update semantics for omitted fields, and the side effect that is_public=true returns a public URL while false revokes it. It does not explain what makes the operation "destructive" (i.e., that supplied values overwrite existing ones) or any permission 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 tightly written sentences, front-loaded with the mutation scope and followed by the two pieces of guidance an agent most needs. The is_public clause partially restates the schema description, but nothing is padded.

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 nine-parameter partial-update tool with annotations present and no output schema, the description covers the essentials: what can change, that omissions are preserved, and the sharing side effect with its return value. An agent has enough to call this correctly without further 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?

Schema coverage is 100%, so all nine parameters including color, reason, and budget_currency are already documented in the schema, making 3 the correct baseline. The description adds a little meaning for is_public (URL generation on true, unshare on false), but the other fields get no detail beyond their names.

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?

Opens with a specific verb+resource ("Update a collection") and enumerates the mutable fields, so an agent knows exactly what this tool changes versus siblings like create_collection or delete_collection. It stops short of explicitly contrasting itself with sibling tools, but 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 patch guidance ("Only provide the fields you want to change — omitted fields stay unchanged") tells the agent how to call it, and the is_public note explains when to set true vs false. However, there is no guidance on when to prefer this over alternatives such as update_item or set_pinned_items, and no prerequisites are stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description earns credit for disclosing batch-specific behavior beyond the annotations: attributes are REPLACED rather than merged, and the og:image fallback is skipped. It does not mention permissions or what happens to unspecified fields on a single update.

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

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

Three short sentences, front-loaded with the core action, followed by the id contract and then the batch caveats. No filler and nothing that restates the schema.

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

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

For a 15-parameter destructive mutation with no output schema and annotation coverage of the safety profile, the description supplies the critical batch semantics an agent could otherwise get wrong. It leaves gaps around permission requirements, single-item merge behavior, and update_price vs update_item routing.

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

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

Schema coverage is 100% and the schema itself documents replacement semantics for tags and images, so baseline 3 applies. The description adds genuinely new parameter behavior by clarifying that attributes are REPLACED for batch calls while the schema description says 'Merge into existing attributes' — a distinction only the description supplies.

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

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

States a specific verb and resource ('Edit fields on one or more saved items') and immediately defines the single-vs-batch id contract, which separates it from update_collection and add_item. Sibling differentiation is implicit through 'saved items' rather than an explicit contrast, so it stops short of a 5.

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

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

It tells the agent how to invoke it for one or many items, but gives no when-to-use guidance or exclusions. Notably, a sibling update_price exists and this tool accepts target_price, yet nothing says which one to prefer — the agent must 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 declare the risk profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), and the description adds that old and new values are recorded for comparison — useful context on persistence. It does not state that the existing price is overwritten, nor whether history entries can be undone, so the destructiveHint=true implication is softened rather than explained.

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

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

Three short sentences, with the action front-loaded and the clarifying constraint (manual correction, not tracking) last. Nothing is redundant and every sentence carries distinct 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 single-field mutation with full schema coverage and annotations carrying the safety profile, the description covers purpose, scope, and the side effect of recording history. Only minor gaps remain: overlapping responsibility with update_item and any authorization requirement.

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 id, price, reason, and source, and the description adds no format or value guidance for any of them. Baseline 3 applies when 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 gives a specific verb and resource ("Manually update the price on a saved item") and scopes it as a price-only mutation, which implicitly separates it from the broader update_item sibling. It never names the sibling explicitly, so an agent must infer which of update_item vs update_price to pick.

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?

"This is a manual correction, not automatic price tracking" sketches when the tool applies, which is more than nothing. However, it names no alternative tool and gives no precondition (e.g., when to prefer update_item for other fields), so the routing guidance stays implied.

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