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

With no annotations, the description carries full burden for behavioral disclosure. 'Add or update' implies upsert behavior, but nothing is said about whether notes are overwritten, permissions required, or return 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?

One sentence that is direct and front-loaded. No wasted words.

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

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

The tool is simple with only 2 parameters and no output schema. The description is adequate for a basic note operation, but lacks usage guidance and detail about overwrite behavior, making it minimally 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%, so the baseline is 3. The description does not add additional parameter meaning beyond what the schema already provides for bookmark_id and notes.

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 a specific action ('Add or update') and resource ('personal notes on a bookmark'). It distinguishes from siblings like update_bookmark by focusing on notes specifically.

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

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

No guidance on when to use this tool versus alternatives such as update_bookmark. The description implies note-specific functionality but does not state when to choose it over other 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?

With no annotations, the description carries the full burden for behavioral disclosure. It only states the action without mentioning side effects, return values, permissions, or whether the operation is idempotent. This is minimal for a mutation tool.

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 sentence, concise and front-loaded with the action. No wasted words, though it could benefit from one clause about behavior without losing efficiency.

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 operation, the description is minimally adequate. However, it lacks any context about idempotency, errors, or expected outcomes, which would be useful for an agent to invoke and interpret results.

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

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

Schema coverage is 100% with clear property descriptions ('The bookmark/tweet ID to add', 'The collection ID'). The description adds no new parameter-level meaning but confirms the relationship, which is adequate given the schema's clarity.

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

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

The description clearly states the verb ('Add') and the resource ('bookmark to a collection'), which distinguishes it from sibling tools like delete_bookmark or create_collection. It is specific and unambiguous, though it doesn't explicitly differentiate 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?

No guidance is provided on when to use this tool over alternatives. It does not mention scenarios, prerequisites, or exclusions, leaving the agent to infer usage from the action alone.

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?

With no annotations, the description carries the full transparency burden. It discloses that the tool uses AI and focuses on saved tweets, which is helpful, but it does not mention any side effects, limitations, or behavior when no relevant bookmarks are found. No contradiction exists, but more detail on the AI-driven behavior could be added.

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 long, front-loaded with the core action ('Ask a question about your bookmarks'), and contains no filler. Every word adds value, making it highly concise and well-structured.

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

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

For a simple one-parameter tool with no output schema, the description adequately explains the purpose and mechanism. It covers the what and how, though it omits details about the response format or edge cases. This is acceptable given the low 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 already documents the single 'question' parameter with 100% coverage, so the description adds no extra semantics beyond what the schema provides. The baseline of 3 applies because the schema fully clarifies the parameter.

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

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

The description clearly states the tool's purpose: asking a question about bookmarks and using AI to answer based on relevant saved tweets. This distinguishes it from sibling tools like search_bookmarks, which presumably does keyword filtering rather than semantic Q&A.

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 a user has a natural-language question about their bookmarks, but it does not explicitly contrast with alternatives or state when not to use it. Since search_bookmarks is a sibling, a brief note distinguishing them would strengthen this dimension.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action without revealing behavioral traits like whether duplicate names are rejected, what happens on success/failure, or whether any side effects occur. This is a significant gap for a mutation tool.

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 five-word sentence, which is optimally concise and front-loaded. There is zero wasted text; however, it could be slightly more informative without losing conciseness.

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

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

The tool is simple (2 params, no output schema), but the description omits return behavior and error handling. Given the simplicity, a one-line description is borderline; it is adequate but lacks closure on outcomes like what the created collection object looks like or how errors are reported.

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 documentation covers 100% of parameters, so the baseline is 3. The description adds no extra meaning about 'name' or 'description' beyond their existence, so it does not exceed the baseline.

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

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

The description uses the specific verb 'create' with the resource 'bookmark collection,' clearly distinguishing it from siblings like update_bookmark or delete_bookmark which target bookmarks, not collections. It is a precise verb+resource statement.

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 the use case (when you need a new collection) but does not explicitly contrast with alternatives or state prerequisites. While no sibling tool creates collections, the intended usage is clear yet not explicitly articulated.

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?

No annotations are provided, so the description carries the burden. The word 'permanently' discloses irreversibility, which is valuable behavioral context. However, it does not mention side effects, authorization requirements, or failure behavior, leaving some transparency gaps.

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 wasted words. It effectively communicates the core action and key qualifier (permanently) in a minimal, front-loaded format.

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 one-parameter delete tool, the description and schema together provide adequate context: what is being deleted, the required parameter, and the irreversible nature. The lack of an output schema and detail on edge cases is acceptable given the tool's simplicity.

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 already fully describes the single parameter with a clear description, achieving 100% coverage. The tool description adds no additional parameter-level detail, 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 uses a specific verb 'Delete' and a clear resource 'bookmark', with 'permanently' clarifying the irreversibility. This clearly distinguishes it from siblings like update_bookmark and get_highlights.

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 permanently deleting a bookmark, making it obvious when to use it. It does not explicitly rule out alternatives, but no exclusions are needed given the tool's specific destructive purpose.

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?

With no annotations, the description carries the full burden of behavioral disclosure. It only states 'Get all bookmarks' and does not mention response format, pagination behavior, permissions, or error conditions. This is a read operation but lacks necessary details for an agent to fully anticipate the tool's behavior.

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

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

The description is a single, concise sentence with no redundant or filler content. It efficiently conveys the core action and 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?

Given the tool's simplicity (one parameter, no annotations, no output schema), the description is mostly complete for an agent to invoke it. However, the lack of any hint about the return structure or potential caveats (e.g., pagination) leaves a small gap, but it is adequate for a straightforward getter.

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 already describes collection_id as 'The collection ID' with 100% coverage. The tool description references 'a specific collection' but adds no extra meaning beyond the schema. The baseline of 3 applies because the schema fully documents the parameter.

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

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

The description 'Get all bookmarks in a specific collection' uses a specific verb ('Get') and resource ('bookmarks') with a clear scope ('in a specific collection'). It clearly distinguishes from siblings like search_bookmarks (search) and get_highlights (highlights) by focusing on retrieving all bookmarks from a given 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 implies usage when you need all bookmarks from a particular collection, but provides no explicit guidance on when to prefer this over search_bookmarks or when not to use it. There are no exclusions or alternative tool mentions, leaving the usage context implicit 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?

With no annotations, the description carries the full burden of behavioral disclosure. It only states the core function and does not mention return format, pagination, or read-only nature. While the name implies a safe read, the description lacks explicit behavioral context.

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

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

The description is a single, direct sentence with no superfluous information. It is front-loaded and effective.

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

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

The tool is simple and the description covers its primary purpose, but it lacks details about output structure and usage relative to sibling tools. Given zero parameters and no annotations, the description is adequate but not rich enough to fully guide an agent.

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

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

The input schema has zero parameters, so schema coverage is trivially complete. No parameter description is needed, and the baseline for zero parameters is 4.

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 'Get all your highlighted passages from bookmarks' uses a specific verb and resource, clearly indicating the tool's function. It differentiates from siblings like search_bookmarks by focusing on highlights rather than search or 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?

No guidance is provided on when to use this tool versus alternatives such as search_bookmarks or get_collection_bookmarks. There are no exclusions or alternative recommendations, leaving the agent without contextual decision-making support.

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?

With no annotations, the description carries the burden of behavioral disclosure. It clearly implies a read-only listing operation and defines the scope ('all your bookmark collections'), which is transparent for a simple list tool. However, it does not describe return format, pagination, or other behavioral details, though these are less critical for a parameterless list operation.

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, succinct sentence that fully conveys the purpose, enhanced by a helpful analogy. There is no redundancy, filler, or unnecessary detail.

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

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

Given the simplicity of the tool (0 parameters, no output schema, no annotations), the description is mostly complete. It explains what the tool does and its scope. It could optionally mention what a collection contains or point to related tools, but these are already implied by sibling names the agent receives. The lack of output schema slightly increases the burden, but the description's clarity compensates.

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, and the schema covers 100% of them (vacuously). Per the rubric, 0 params gives a baseline of 4. The description does not need to explain parameters, and it appropriately focuses on the tool's purpose.

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 'List' with a clear resource 'bookmark collections' and provides an analogy ('like playlists for tweets') that makes the concept immediately understandable. It distinguishes from siblings like get_collection_bookmarks (which lists bookmarks within a collection) by clarifying this lists the collections themselves.

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

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

The description implies usage for retrieving all bookmark collections but does not explicitly state when to use this tool versus alternatives. There is no mention of when not to use it or pointers to siblings such as get_collection_bookmarks or create_collection, so the guidance is only implicit.

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?

With no annotations, the description must fully disclose behavior. It mentions full-text and semantic search but omits key details like what results look like, default limits, pagination behavior, or any side effects. The schema provides some parameter details, but the description adds little behavioral context.

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

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

The description is exceptionally concise: two sentences that are front-loaded with the action and scope. There is no redundant or filler content.

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

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

For a search tool with no output schema, the description should at least indicate what is returned and how pagination works. The tool has offset and limit parameters, but the description does not explain pagination or result format. Sibling differentiation is also missing. The description is under-specified for effective use.

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

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

Schema description coverage is 100%, so baseline is 3. The description's mention of 'keyword, topic, or author' aligns with the query parameter but adds no new semantics beyond what the schema already states. No additional syntax or interaction details are 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 clearly states the tool's function: searching saved Twitter/X bookmarks by keyword, topic, or author. It uses a specific verb ('search') and a well-defined resource, distinguishing it from sibling tools like 'get_collection_bookmarks' or 'ask_bookmarks'.

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

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

The description implies usage for general bookmark search but provides no explicit guidance on when to prefer this tool over alternatives like 'ask_bookmarks' or 'get_collection_bookmarks'. No exclusions or alternative recommendations 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?

With no annotations to rely on, the description must disclose behavioral traits. It only states 'update', but does not explain whether tags are replaced or appended, whether the bookmark must exist, or any authentication requirements. The phrase 'category or tags' may misleadingly suggest exclusivity, while the schema allows both.

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 that immediately conveys the action and target. There is no extraneous detail, making it highly concise and front-loaded.

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

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

Given the simple nature of the tool and 100% schema description coverage, the description is minimally sufficient. However, it lacks behavioral context around the update semantics (merge vs replace) and no output schema exists. This is a modest gap, not a severe deficiency.

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

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

Schema description coverage is 100% for all three parameters, each with clear descriptions ('New tags', 'New category', 'The bookmark/tweet ID'). The tool description only restates 'category or tags', adding no additional semantics about how to use the parameters (e.g., whether both can be supplied simultaneously). Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description uses the verb 'update' with a clear resource ('bookmark') and specific fields ('category or tags'). This distinguishes it from sibling tools that delete, search, create collections, or add notes, making the purpose unambiguous.

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

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

The description provides no guidance on when to use this tool instead of alternatives like add_notes or delete_bookmark. There are no mentions of prerequisites, exclusionary scenarios, or appropriate use cases.

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