Razuna DAM MCP

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

Annotations already signal a mutating (readOnly=false), non-destructive (destructive=false) operation, and the description matches that. It adds no detail beyond the schema about idempotency, duplicate labels, or what happens when the label is already applied, but for a simple additive operation this is minimally acceptable.

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

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

A single front-loaded sentence with no filler. Every word contributes to the meaning.

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

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

With two well-documented parameters, an output schema, and safety annotations, the basic context is adequate. Still, the description omits preconditions and failure behavior, leaving an agent to infer whether the label must already exist and how duplicate applications are handled.

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 file_ids and label_id are already documented. The description adds only a synonym clarification ('label' = 'tag') and confirms batching via 'one or more files', which does not substantially increase semantic value.

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

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

The description uses a specific verb ('Add'), an object ('label/tag'), and a resource ('files'), making the operation clear. It is distinguishable from siblings such as remove_tag_from_file and create_tag by meaning, but it does not explicitly contrast itself with them.

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: an agent can infer this tool is for applying an existing tag to files. However, there is no explicit guidance on prerequisites (e.g., the tag must exist via create_tag) or when to prefer remove_tag_from_file.

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 (readOnlyHint=false, destructiveHint=false) indicate mutation without destruction, which aligns with the description. The description adds the scoping constraint 'within the same workspace' but does not disclose potential behavioral details such as partial failure handling, overwrite behavior, or permission requirements. Given sparse annotations, the description could offer more behavioral context, but it is not contradictory.

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 immediately conveys the action and scope. There is zero filler, and the most important information (multiple files, move, folder, same workspace) is front-loaded.

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

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

The tool is a straightforward bulk move operation with a fully documented schema and an output schema (as indicated by context). The description covers the essential action and scope. Potential nuances like file count limits or partial success reporting are not mentioned, but the output schema likely covers return values, making the description adequately complete 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%, with all four parameters (file_ids, target_folder_id, workspace_id, workspace_name) documented. The description adds no additional semantic meaning beyond what the schema already provides, so it does not enhance parameter understanding. Baseline 3 is appropriate when the schema fully covers parameters.

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

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

The description clearly states the action (move), the resource (multiple files), and the target (a different folder within the same workspace). It distinguishes itself from siblings like move_file (single file) and move_files_to_workspace (cross-workspace), making the tool's 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 phrase 'within the same workspace' implicitly excludes cross-workspace moves, and 'multiple files' excludes single-file moves. However, it does not explicitly name alternatives or provide when-not-to-use guidance. The context is clear enough for an agent to infer appropriate usage, but explicit alternatives would be stronger.

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

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

Annotations already indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the semantic context of restoring from trash, but does not disclose side effects such as where files are restored, conflicts, missing IDs, or permission requirements. It is acceptable but minimal.

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 clear, front-loaded sentence with no filler. It states the action and target condition efficiently, which is ideal for a tool with a simple purpose.

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

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

The description is minimally adequate for a three-parameter bulk operation with an output schema, but it omits useful context about workspace resolution, behavior for already-restored or invalid file IDs, and the relationship to bulk_trash_files and empty_trash.

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. The description does not add parameter-specific meaning beyond the action of restoring, so the baseline score 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 (restore) with a clear resource (files) and a condition (previously moved to trash), making the tool's purpose unmistakable. This also distinguishes it from sibling tools like bulk_trash_files, bulk_move_files, and empty_trash.

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 phrase 'previously moved to trash' implies the tool should be used for trashed files, but there is no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or warn against using this after empty_trash or for non-trashed files.

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

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

The description adds useful behavioral context beyond annotations by disclosing that tags already existing in the destination are skipped based on name matching. This informs the agent about idempotent behavior and conflict handling, which is valuable for a write 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 two short sentences with no filler. The core action is front-loaded, and the deduplication caveat is included without extra verbosity.

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

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

The description is mostly complete given the output schema and annotations. It explains the main behavior and the important skip-existing rule. A minor gap is that optional source/destination defaults are not clarified, especially since only to_host_id is required, but the schema covers parameter definitions well.

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 all parameters with 100% coverage. The description does not add meaning beyond the schema, such as defaults or resolution behavior for workspace names. 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 a specific action: 'Copy all tags from one workspace to another.' It also specifies the deduplication behavior, making the tool's purpose unambiguous and distinguishable from sibling tag tools like create_tag or add_tag_to_files.

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

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

The description provides clear context for when to use this tool: when all tags from one workspace need to be copied to another. It does not explicitly mention alternatives or when-not conditions, so it stops short of a 5, but the use case is evident.

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 signal this is a write operation (readOnlyHint=false, destructiveHint=false), so the description need not restate that. It does add the useful 'owner-private' visibility constraint. But it fails to disclose what happens when no workspace is specified, whether folder placement is required, or the nature of the created note beyond the label.

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 single sentence is lean with no filler, which is structurally fine, but the brevity works against it: it compresses the entire behavioral contract into one clause and omits the parameter semantics that a longer description should carry.

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

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

With five parameters, partial schema coverage, and an output schema present, the description still leaves critical gaps: no explanation of the required 'name' field, no behavior for the optional workspace parameters, and no statement about error conditions. For a creation tool this is under-specified for reliable agent use.

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

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

Schema coverage is only 40% – 'name', 'note', and 'folder_id' have no descriptions. The description does not compensate: it never explains that 'name' is the note title, 'note' is the body content, or what 'folder_id' does. With the description carrying none of this burden, an agent must guess the semantics of three undocumented parameters.

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

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

The description uses a specific verb-resource pair ('Create ... Collect+ note') and adds the 'owner-private' qualifier, which distinguishes it from the generic sibling 'create_note'. However, it never explicitly names the sibling it is not, so differentiation is implied rather than stated.

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 given on when to choose this tool over 'create_note', 'save_url_to_collectplus', or 'update_collectplus_item'. There is no context about prerequisites (e.g., needing an existing workspace), nor any exclusions or alternatives mentioned.

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

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

Annotations already indicate this is a non-read-only, non-destructive operation, so the description does not need to restate that. It adds useful placement behavior ('root level or inside an existing folder'), but it does not mention duplicate-name handling, permission requirements, or other edge-case behavior. The added value beyond annotations is modest but present.

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

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

The description is two short sentences with no filler. The core operation is front-loaded, and the optional nesting behavior is stated in a single additional clause.

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 a rich schema, full parameter descriptions, and an output schema, so the description does not need to explain return values or parameter syntax. It is sufficient for an agent to understand the tool's role and primary usage. A small gap is the lack of guidance on workspace resolution, but that is already handled in the schema's parameter descriptions.

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 input schema already documents all five parameters well. The description's placement statement mirrors what parent_folder_id already says ('If omitted, folder is created at root level'), adding little new semantic information beyond the schema.

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

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

The description uses a specific verb and resource: 'Create a new folder in a workspace.' It also clarifies the two placement modes (root level or inside an existing folder), making it easy to distinguish from sibling tools like create_document, create_tag, or update_folder.

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 for when the tool applies: when a new folder is needed, with the choice between root-level or nested creation. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous enough for selection.

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

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

Annotations indicate readOnlyHint=false, destructiveHint=false, which is consistent with a create operation. The description adds useful behavioral context: notes are indexed for search and AI retrieval, and workspace name resolution is automatic. It doesn't mention potential side effects like overwriting or required permissions, but for a create tool this is adequate.

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

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

The description is concise and well-structured. It front-loads the core purpose, then explains what notes are, when to use them, and the workspace resolution behavior. Every sentence adds value without redundancy.

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

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

The description covers the tool's purpose, use cases, and key behavioral nuances. With an output schema present and 100% parameter coverage, the agent has enough context to invoke the tool correctly. Minor gap: it doesn't mention that document_type defaults to 'markdown' (though the schema does), and it doesn't explicitly state the relationship between workspace_id and workspace_name when both are provided.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining the workspace_name resolution behavior and the distinction between labels (IDs) and document_tags (free-form). It also clarifies that folder_id is optional and defaults to workspace level, which is not fully explicit in the schema.

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

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

The description clearly states the tool's purpose: 'Create a new note in Razuna.' It specifies what notes are (rich text knowledge objects), where they are stored (alongside media files), and how they are used (indexed for search and AI retrieval). It also distinguishes this from sibling tools like create_document and create_collectplus_note by emphasizing notes as knowledge objects.

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: 'Use this to store meeting notes, research, project documentation, or any knowledge content.' It also explains the workspace resolution behavior (by ID or name). However, it doesn't explicitly state when NOT to use this tool or mention alternatives like create_document or create_collectplus_note, which are siblings.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds only the general purpose of tags, not behavioral details like duplicate-name handling, workspace resolution, or hierarchy effects. No contradiction, but minimal added value.

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

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

Two concise sentences with the action stated first and no filler. Every sentence serves a purpose, though it is minimal.

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

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

Adequate for a create operation with a well-documented schema and output schema, but it does not address workspace resolution or hierarchical tag behavior beyond what the schema provides. It also gives no guidance for choosing among related tag tools.

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% description coverage, so all parameters are already documented. The description does not add semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Create a new tag in a workspace') and clarifies the purpose of tags. It clearly distinguishes from sibling tools like create_folder, create_note, and update_tag.

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_tag, delete_tag, or add_tag_to_files. It does not mention prerequisites like default workspace configuration or conditions for using parent_id.

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

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

Annotations already mark the tool as destructive and non-readOnly, so the description adds valuable context by specifying that the item is only moved to trash rather than permanently erased. It also discloses an owner-private scope that is not present in the annotations or 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?

A single, clear sentence with no filler. The action and resource are front-loaded, and every word contributes meaning.

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

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

Given the output schema, return values need no explanation. The description identifies the action, the resource type, the owner-private scope, and the trash side effect, which is sufficient for a relatively simple deletion tool. It leaves alternative routing to the usage dimension rather than making the tool uncallable.

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 description adds no direct parameter details beyond identifying the target as a Collect+ item. The required item_id has no schema description, while the workspace parameters are already documented in the schema; there is no extra format, uniqueness, or workspace-resolution guidance.

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 ('move to trash'), a specific resource ('Collect+ item'), and a scope qualifier ('owner-private'). It clearly distinguishes this tool from siblings like read_collectplus_item, move_collectplus_item, and bulk_trash_files, and it clarifies that 'delete' means a soft-delete trash 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?

There is no explicit guidance about when to use this tool versus alternatives such as bulk_trash_files or empty_trash. The 'owner-private' qualifier implies a restriction, but the description never states conditions, prerequisites, or alternative routes for other item types or bulk operations.

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

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

The description reveals a key behavioral nuance: deletion is actually a move to trash, not a permanent erase. This adds value beyond the destructiveHint annotation, which only signals destructiveness. It doesn't mention reversible/restore behavior explicitly, but the 'move to trash' phrase implies recoverability, which is helpful 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, tight sentence with no fluff. The core action is front-loaded ('Delete'), and the clarifying note about trash is included without clutter. Every word adds value, making it highly efficient.

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

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

For a simple single-parameter delete tool with annotations and an output schema present, the description covers the essential action and a crucial behavioral detail. It doesn't explain return values, but the output schema covers that. It could have briefly noted that it operates on documents (not files) or contrasted with bulk operations, but the name and description already make the target resource clear.

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 (document_id) with 100% coverage. The description merely restates the ID concept without adding new semantic details such as format, origin, or validation. Given schema coverage is high, 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 states a specific verb ('Delete') and resource ('document') with a clarifying parenthetical ('move to trash') that adds precision. It clearly distinguishes this from related tools like empty_trash or permanent deletion, 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 provides no guidance on when to use this tool versus alternatives like delete_file, bulk_trash_files, or delete_note. It doesn't mention occasions when this tool is the right choice or when a sibling should be used instead, leaving the agent to infer from the name 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?

Annotations already signal destructive intent, and the description adds the key nuance 'move to trash', indicating the operation is not a permanent erase. It does not contradict the annotations and gives useful context about the operation's effect.

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 with no filler. It delivers the action, resource, and behavior in a compact form.

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

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

For a single-parameter delete tool with an output schema and destructive/read-only annotations, the description is sufficient. The 'move to trash' clarification addresses the operation's practical consequences; no critical information is missing.

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

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

Schema description coverage is 100%, so the schema already documents note_id. The description's 'by its ID' merely echoes the schema without adding extra meaning such as format, constraints, or idempotency.

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 ('Delete'), resource ('note'), and a clarifying behavior ('move to trash'). The phrase 'by its ID' distinguishes this from bulk or document-deletion siblings like bulk_trash_files and delete_document.

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 its use for deleting a single note by ID but does not explicitly state when to prefer it over related tools such as bulk_trash_files or delete_document. No exclusions or alternative conditions are mentioned.

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, indicating a destructive operation. The description adds valuable behavioral context beyond the annotation by stating that the tag is also removed from all files that have it. This is a critical side effect an agent must know before invoking, and it is not captured in the annotations alone.

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 only two sentences, with the core action stated first and the side effect immediately after. It is efficient, front-loaded, and contains no filler. Every sentence adds necessary 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?

The tool is a simple destructive action with a single parameter and an output schema present. The description covers the essential behavioral side effect and the annotation covers destructiveness. It could mention error handling (e.g., what happens if the tag does not exist) but that is not critical for selection. Overall, it is sufficiently complete for an agent to call it correctly.

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

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

The input schema fully documents the single parameter tag_id with a clear description ('The tag ID to delete'). Since schema coverage is 100%, the description does not need to add parameter-specific details. The description adds no extra meaning, but the schema already provides sufficient guidance, 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: 'Delete a tag.' The verb 'delete' and resource 'tag' are specific. The added side effect, 'remove the tag from all files that have it', distinguishes it from sibling tools like remove_tag_from_file, which removes only from one file. This makes the purpose unambiguous and differentiates it from alternatives.

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

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

The description implies when to use this tool by noting the global side effect, which contrasts with remove_tag_from_file for partial removal. However, it does not explicitly state 'use this when you want to permanently delete the tag' or mention alternative tools. The guidance is inferred rather than explicit, leaving some room for ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds minor context by explaining what custom fields are and that the tool returns a schema/template, but it does not disclose any additional behavioral aspects such as default workspace resolution or error handling. With annotations carrying the burden, this is acceptable 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, with the core action front-loaded and the second sentence providing helpful context. No filler or redundancy; every word contributes to understanding.

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

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

For a simple read-only tool with two optional parameters, an output schema, and safety annotations, the description covers the essential purpose. Default workspace behavior is already documented in the schema, so nothing critical is missing. It could mention the relationship to file-level custom fields, but that's a minor gap.

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

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

Schema description coverage is 100% – both workspace_id and workspace_name have thorough descriptions, including the optionality and default-workspace behavior. The tool description adds nothing about parameters, so the baseline of 3 is appropriate since 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 a specific verb+resource: 'Get the custom fields schema/template defined for a workspace.' It clearly distinguishes itself from sibling tools like get_file_custom_fields by scoping to workspace-level definitions, and from set_file_custom_fields by being a read operation.

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

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

The description gives clear context by specifying the workspace scope, which implies usage for workspace-level schema retrieval. It does not explicitly state exclusions or name alternatives (e.g., 'for file-level custom fields, use get_file_custom_fields'), but the context is unambiguous enough for correct selection.

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

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

Annotations already declare this read-only and non-destructive, so the safety profile is covered. The description adds useful context about the categories of metadata returned, but does not disclose error behavior, authorization needs, or any other behavioral nuance.

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 covers the core operation and then enumerates the returned metadata categories without fluff. The length is justified by the metadata-rich nature of the tool.

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

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

With one documented parameter, an output schema, and read-only annotations, the description is almost sufficient on its own. The main missing piece is guidance on when to pick this tool over the many sibling getters for file metadata.

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?

There is only one parameter, file_id, and the schema already explains it fully (100% coverage). The description adds no extra meaning about the parameter format, requiredness, or constraints, so the 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 opens with a specific verb and resource ('Get detailed metadata about a specific file'), and the field list makes the scope tangible. It does not explicitly differentiate itself from close siblings such as get_file_custom_fields or get_file_usage_stats, so it stops short of 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?

No when-to-use or when-not-to-use guidance is provided. There are no references to alternatives or exclusions, even though the sibling list contains several closely related getters (get_file_custom_fields, get_file_usage_stats) that an agent could confuse with this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context such as missing-file behavior or authentication, but it does not contradict the annotations and the operation is a straightforward read.

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 with no filler and no repetition of the schema. Every word contributes to understanding the tool's purpose.

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

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

For a one-parameter read-only getter with annotations and an output schema, this is nearly complete. The only gap is the lack of an explicit pointer to sibling tools like get_custom_fields or set_file_custom_fields for agents deciding between them.

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%, and the file_id parameter already explains its purpose. The tool description adds no new parameter semantics, placing it at 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 names a specific action ('Get'), a precise resource ('custom field values'), and a scope ('set for a specific file'). This clearly distinguishes get_file_custom_fields from siblings like get_custom_fields and set_file_custom_fields.

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 verb and object imply this is the read-only tool for per-file custom field values, so usage is reasonably clear. However, it never explicitly says when to choose this over get_custom_fields or when to use set_file_custom_fields, so there is no direct alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that this returns aggregated statistics rather than raw events, which is mildly useful, but it does not add material behavioral context beyond what annotations and the output schema 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?

Two sentences with no filler. The first sentence states what the tool returns and the metric categories; the second provides usage context. Everything earns its place.

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

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

Given the 100% schema coverage, an output schema, and read-only annotations, the description is complete for an agent to decide when to call and what to expect. Specific parameter defaults and date/workspace behavior are already fully specified in the input schema.

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

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

Schema description coverage is 100%, with each parameter already documented and the metrics enum fully expanded in the schema. The description adds no new parameter-level meaning, 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 ('Get') with a clear resource ('file usage and engagement statistics') and enumerates concrete metric categories: download counts, view counts, active users, search trends, and geographic/browser/OS analytics. This distinguishes it from all siblings, none of which appear to offer analytics-style aggregation.

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

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

The description explicitly says 'Use this to answer questions about file popularity, engagement, user activity, and access patterns,' giving clear guidance on when to invoke the tool. It does not enumerate exclusions or alternatives, but there are no close sibling tools competing for this use case.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the return scope (metadata, permissions, file count) but does not disclose additional behavioral traits like auth requirements, error cases, or pagination; with the output schema present this is acceptable but not rich.

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, front-loaded with the action and resource, and the parenthetical list adds useful detail without redundancy. 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 single-parameter read tool with an output schema and read-only annotations, the description is sufficient: it names the resource, the key return categories, and the required input is in the schema. Nothing critical is missing for invoking it correctly.

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

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

Schema coverage is 100% and the only parameter folder_id is already described in the schema. The tool description adds no extra meaning about the parameter's format, source, or constraints, so baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('specific folder'), and lists concrete return contents (metadata, permissions, file count). This differentiates it from siblings like get_folder_tree or list_folder_files, which target trees or file listings rather than a single folder's details.

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 choose this over siblings such as get_folder_tree, list_folder_files, or get_workspace. The only implied context is needing details for one folder; there are no exclusions or alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the hierarchical/subtree behavior context, which is useful beyond the annotations, but doesn't describe output shape, pagination, or recursion depth limits. The description does not contradict the annotations.

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

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

Two sentences, front-loaded with the core purpose, and the optional subtree behavior is the only additional detail. It is efficient and focused, though it could slightly expand on workspace resolution without much cost.

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

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

For a read-only, zero-required-parameter traversal tool with a full output schema, the description is adequate. The workspace_id/workspace_name optionality is captured in the schema, and the description conveys the main behavior. Missing context like default workspace fallback details or output ordering is non-critical given the schema and annotations.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters. The description adds minimal extra meaning: it confirms folder_id can request a subtree and workspace alternatives, but this largely restates the schema. Baseline 3 is appropriate when the schema carries the parameter documentation burden.

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 names a specific verb ('Get') and resource ('hierarchical folder structure for a workspace'), and distinguishes the subtree option from the full-tree behavior. It clearly differentiates from siblings like get_folder and list_folder_files by specifying the hierarchical structure rather than a single folder or flat file listing.

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

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

The description explicitly notes the optional subtree starting point and that all parameters are optional when a default workspace is configured. It clearly states the main use case but does not explicitly mention when to prefer an alternative tool like get_folder or list_folder_files, leaving some contextual comparison to the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with them. The description adds no extra behavioral context beyond 'get detailed information,' but for a simple read operation with an output schema, this is acceptable.

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

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

The description is a single, direct sentence with no filler. It front-loads the action and resource while incorporating the key parameter information efficiently.

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

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

For a one-parameter getter with an output schema and safety annotations, the description is nearly complete. It tells the agent what the tool does and how to target a tag; only explicit guidance about sibling alternatives like list_tags is absent, but that is not a significant gap here.

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 the single tag_id parameter, so the schema already documents it. The description only restates the parameter's purpose ('by its ID') without adding format, constraints, or relationship details.

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'), a clear resource ('detailed information about a specific tag'), and the unique identifier ('by its ID'). It is easily distinguished from siblings like list_tags, which enumerate tags, and update_tag, which modifies them.

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 phrase 'by its ID' clearly indicates this tool is for fetching a single known tag rather than listing or creating tags. It does not explicitly name alternatives such as list_tags, but the context is straightforward for an agent with a tag ID.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the result includes metadata, permissions, and statistics, giving some expectation of response content, but it does not disclose edge-case behaviors such as error handling or default workspace resolution behavior beyond what the schema already provides.

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, front-loaded with the verb and resource. It contains no redundant or vague filler, and every phrase ('detailed information', 'metadata, permissions, and statistics') 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?

An output schema exists, so return values need not be explained. Annotations cover read-only behavior, and the schema covers parameter details. The description sufficiently conveys the tool's role for a simple getter, though explicit usage guidance would improve completeness.

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

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

Schema description coverage is 100%, with both workspace_id and workspace_name fully described including optionality and default workspace behavior. The description itself adds no additional parameter semantics, so the baseline 3 applies.

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

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

The description states a clear verb and resource: 'Get detailed information about a specific workspace.' It inherently distinguishes from list_workspaces by specifying 'specific' and from other getter tools by workspace scope. However, it does not explicitly name any sibling tool or contrast itself with alternatives, so it misses the top differentiation bar.

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 offers no guidance on when to use this tool versus alternatives like list_workspaces, nor does it mention how to choose between workspace_id and workspace_name. It simply states what the tool does, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'authenticated user's owner-private' scope, which is useful context, but does not disclose pagination, ordering, or workspace selection behavior 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?

A single sentence that front-loads the action, resource, and scope. Every word earns its place; no redundancy or filler.

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

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

The output schema covers return values, and read-only annotations reduce the need for safety disclosure. However, pagination behavior and the meaning of 'owner-private' in multi-workspace contexts are not explained, and filter parameters like type and limit lack semantic detail.

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 40%, with workspace_id and workspace_name described but page, type, and limit only having types/enums. The description adds no new meaning for these parameters. Baseline 3 applies because the uncovered parameters are somewhat self-explanatory from 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?

The description states a specific verb ('List') and resource ('authenticated user's owner-private Collect+ items') and scopes it to 'one workspace.' This is clear, but among many sibling list tools, the qualifier 'owner-private Collect+ items' only partially differentiates it from search_collectplus_items and read_collectplus_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 implies usage: use this when the agent needs to list owner-private Collect+ items in a workspace. It does not explicitly state when not to use it or name alternatives such as search_collectplus_items. Schema notes about default workspace are helpful but not usage guidance.

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

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

The annotations already mark the tool as read-only and non-destructive, so the description does not need to carry that burden. The description adds workspace-scoped listing and filtering behavior, but it does not disclose pagination behavior, result size, or whether metadata versus full content is returned. This is adequate but not richly transparent.

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

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

The description is two sentences with no fluff. It front-loads the main action and scope, then lists the relevant filters and workspace-resolution options in a compact, scannable way.

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

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

With seven optional parameters, full schema coverage, an output schema, and read-only annotations, the description is largely sufficient for correct invocation. It captures the most important filtering dimensions and workspace selection, though it omits mention of tag filtering and default pagination in prose; these are covered by the schema, so the gap is minor.

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 all seven parameters. The prose mentions folder, document type, text search, and workspace ID/name selection, which mirrors the schema rather than adding new meaning, so it stays at the baseline 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 opens with a specific verb and resource, 'List documents in a workspace,' which clearly defines the operation and scope. It adds useful filter categories, though it does not explicitly differentiate itself from the sibling search_documents tool beyond the list-versus-search distinction.

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 listing or filtering documents within a workspace, which is adequate contextual guidance. However, it does not state when to prefer this tool over search_documents, list_notes, or list_folder_files, and it offers no explicit exclusions or alternative routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that results are scoped to a workspace, but it does not disclose further behavioral traits such as default workspace fallback, pagination behavior, or result limits. There is 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 compact and front-loaded with the primary action. The two sentences are efficient, though the workspace-by-ID-or-name sentence is partially redundant with the schema descriptions.

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

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

For a read-only list operation with rich schema descriptions, annotations, and an output schema, the description covers the core invocation semantics: scope, filters, and workspace selection. The main gap is not disambiguating from similar list/search sibling tools, but the structured data fills most other 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 baseline is 3; the schema already documents every parameter. The description adds a useful grouping of filters and the id/name workspace choice, but it omits page and document_tags from the prose without adding meaning beyond what the schema provides.

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

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

The description opens with a specific verb and object: 'List notes in a workspace,' and enumerates filter dimensions. However, it does not explicitly distinguish list_notes from sibling tools like search_notes or list_documents, which could also return notes in a workspace.

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?

There is no guidance about when to choose list_notes over search_notes, list_documents, or search_documents. The description only lists filter options and mentions workspace-by-ID-or-name resolution; it does not name alternatives or state when this tool should or should not be used.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds modest context about tags being file labels and the returned fields, but does not disclose behavior like pagination, ordering, or limits on what 'all' means.

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 short sentences with no filler. The action and scope are front-loaded, and the additional context about tags 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 read-only list operation, this is sufficient: it states scope, describes the output fields, and annotations plus output schema cover safety and return shape. No critical information needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both workspace_id and workspace_name are already documented. The description's 'in a workspace' notion aligns with the parameters but adds no extra meaning beyond the schema.

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

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

The description uses a specific verb ('List'), names the resource ('tags'), and scopes it ('in a workspace'). This clearly distinguishes it from siblings like get_tag (single tag), create_tag, and update_tag.

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 clearly implies this is the tool for retrieving all tags in a workspace, but it does not explicitly state when to use it versus alternatives such as get_tag or search/copy tag tools. There is no direct when-to-use or when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint true and destructiveHint false. The description adds useful access-scoping context ('that the user has access to'), but it does not discuss paging, ordering, or other behavioral details. For a simple read-only list with an output schema, this is acceptable but not rich.

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

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

The description is two sentences with no filler: the first states the action and scope, the second provides necessary domain context. Every sentence earns its place.

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

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

This is a zero-parameter, read-only listing tool; annotations cover the safety profile and an output schema exists. The description states the scope and the resource type, so nothing needed for correct invocation is missing.

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

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

The input schema is empty, so there are no parameters to document and schema coverage is effectively complete. The description adds domain context about workspaces, but no parameter semantics are needed. This matches the baseline for zero-parameter tools.

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') and resource ('all workspaces') and includes the scope 'that the user has access to'. It also defines workspaces as top-level organizational units, which helps distinguish them from folders or collections and from the single-item sibling get_workspace.

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 clearly implies use when an agent needs to enumerate the user's accessible workspaces, but it does not explicitly state when to use this tool versus get_workspace or other workspace-related operations. No alternatives or exclusions are named.

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

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

The description does not contradict annotations, but it adds minimal behavioral context beyond the annotations. Since readOnlyHint and destructiveHint are both false, the agent knows this is a mutating operation but lacks details on permissions, reversibility, or side effects. The description adds the 'owner-private' nuance but doesn't explain consequences or 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 concise sentence that is front-loaded with the core purpose. Every word adds value, with no filler or 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 move operation with annotations indicating a mutation, the description is minimally sufficient. It lacks information about return values (though output schema exists), prerequisites, or error conditions. However, the output schema exists, so the description doesn't need to explain return values. The description 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?

The description does not elaborate on parameters beyond what the schema provides. With 50% schema coverage, the schema already describes workspace_id and workspace_name. The description adds no semantic detail about item_id or folder_id. Since the schema covers half, 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 verb (move), the resource (owner-private Collect+ item), and the target (normal workspace folder). This distinguishes it from siblings like delete_collectplus_item or read_collectplus_item. It also adds the key scope constraint 'owner-private', which is not in the name.

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 tool is for moving owner-private items, but it does not explicitly say when to use it versus alternatives like move_file or move_files_to_workspace. It lacks exclusions or conditions that would route the agent to a different sibling. It is clear enough for the specific case but not comprehensive.

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

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

Annotations already indicate it's a mutating operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds the 'same workspace' scope but no additional behavioral details such as effects on permissions or reversibility. Given annotations cover the safety profile, this is adequate but minimal.

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, focused sentence that conveys the core purpose without redundancy. It is appropriately front-loaded with the action and constraint.

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 operation (2 required params, output schema present), the description covers the essential usage. It doesn't mention edge cases like moving to the same folder, but these are likely handled by the API and reflected in the output schema, so not necessary.

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

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

Schema coverage is 100% with both parameters described in the schema, though the descriptions are basic ('The file ID to move' and 'The destination folder ID') that merely restate the parameter names. The description adds no extra meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the action (move a file) and the scope (to a different folder within the same workspace). It distinguishes from sibling tools like bulk_move_files (plural) and move_files_to_workspace (cross-workspace) by specifying the 'same workspace' constraint.

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

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

It provides clear context that this tool is for intra-workspace moves, which implies not for moving across workspaces. However, it does not explicitly name alternatives or state when not to use it, leaving some inference to the agent.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. It adds the tag-mapping behavior and the default for keep_tags, which is useful. However, it does not disclose potential side effects (e.g., whether moving removes files from the source, whether tag mapping overwrites existing tags, 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?

The description is a single concise sentence that front-loads the primary action and mentions the optional behavior. It is efficient and easy to parse, though it could benefit from a brief note on when to use it over siblings.

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 6 parameters, an output schema, and annotations, but the description is minimal. It doesn't explain the relationship between 'workspace_id' and 'to_workspace_id' clearly (source vs destination), nor does it clarify the 'to_host_id' requirement. The output schema exists, so return values are covered, but the description leaves some operational ambiguity.

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 all parameters. The description adds context for 'keep_tags' (mapping by name) and implies 'workspace_id' is the source, but it doesn't add significant meaning beyond the schema. 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 ('Move one or more files to a different workspace') and the optional tag-mapping behavior. It distinguishes itself from the sibling 'move_file' by indicating it handles multiple files, though it doesn't explicitly name the sibling or contrast with 'bulk_move_files'.

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 moving files between workspaces and optionally mapping tags, but it does not explicitly state when to use this tool versus alternatives like 'move_file' or 'bulk_move_files'. The presence of siblings with overlapping names suggests a need for clearer differentiation, which 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 readOnlyHint, openWorldHint, and destructiveHint, so the safety profile is covered. The description adds a scoping detail ('owner-private', 'in a workspace') that hints at access restrictions, but it does not elaborate on what happens for non-owner-private items or workspace resolution.

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 that front-loads the verb and object, with no filler. Every word contributes meaning, and the sentence is immediately parseable.

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 read operation, annotations, and output schema, the description is adequate for basic invocation but leaves the term 'owner-private' and workspace default behavior unexplained. It does not reference sibling tools for locating an item_id before reading.

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 67%, with workspace_id and workspace_name already explained in the schema; item_id is self-explanatory from the tool name. The description adds no additional parameter context, so it neither helps nor hurts beyond the schema.

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

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

The description uses a specific verb ('Read') with a precisely scoped resource ('one owner-private Collect+ item') and a location ('in a workspace'). It clearly differentiates this tool from sibling read tools like read_document or read_note, and from list_collectplus_items via the singular 'one'.

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 this tool is for retrieving a single known Collect+ item, but it does not state when to prefer it over list_collectplus_items or search_collectplus_items, nor does it explain the 'owner-private' precondition. Usage guidance is present only by implication.

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

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

Annotations already establish read-only, non-destructive behavior. The description adds meaningful behavioral detail by stating exactly what a successful call returns, including that content is HTML plus plain text and metadata. It does not cover errors or size limits, but for a simple read operation this is sufficient.

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 focused sentence front-loads the verb and object, then lists the return payload types. Every clause earns its place with no filler, redundancy, or unnecessary background.

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

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

For a one-parameter read tool with read-only annotations and an output schema, the description is nearly complete. The only notable gap is the absence of explicit routing relative to siblings like list_documents or search_documents, so agents must infer when this tool is the right choice.

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 documents document_id at 100% coverage. The description only repeats the obvious 'by its ID' relationship and adds no new parameter-level detail, so the schema carries the semantic weight and the baseline score 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 clear action ('Read'), exact resource ('document'), retrieval scope ('full content'), and the key selector ('by its ID'). Enumerating the returned data (title, HTML content, plain text, metadata) further distinguishes it from list, search, and creation tools even without naming a sibling.

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 the tool: when the agent has a document ID and needs the full document content. However, it gives no explicit when-to-use/when-not-to-use guidance or alternatives such as list_documents or search_documents, leaving the routing decision mostly to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context by specifying what the read returns (title, HTML content, plain text, metadata), which goes slightly beyond the annotations. However, since an output schema exists, much of this return format is already structured, so the description's incremental behavioral value is modest but non-contradictory.

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 tight sentences with zero filler. The verb and resource are front-loaded, and the return payload is stated in one compact list. Every sentence earns its place.

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

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

For a single-parameter, read-only tool with a fully documented schema and an existing output schema, the description is nearly complete. The mention of return fields is helpful even though the output schema covers it, and nothing required to invoke the tool correctly is missing. Slightly redundant given the output schema, hence not a 5.

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

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

Schema description coverage is 100%, and the note_id parameter is already described as 'The note ID to read'. The description's 'by its ID' reinforces but does not extend the schema. The description adds no formatting, constraints, or usage nuance beyond what the schema documents, so it stays at 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 states a specific verb ('Read'), a clear resource ('note'), and the access method ('by its ID'). This cleanly separates it from siblings like list_notes and search_notes, which list and search rather than fetch a single note. The added return payload details (title, HTML content, plain text, metadata) further pin down what the tool 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 the use case — fetch a single note's full content when you have an ID — but never names alternatives or when-not conditions. With siblings like get_note-like list_notes and search_notes available, the description leaves choosing between them to inference rather than making the selection explicit.

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 readOnlyHint=false. The description adds that the destructive action is removing a tag/label association from one file rather than deleting the file or the tag itself. It does not disclose reversibility or side effects, but the annotation coverage softens the 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?

A single front-loaded sentence contains the action, object, and scope with no filler or repetition. 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 two-parameter removal operation with full schema coverage, an output schema, and safety annotations, the description is operationally sufficient. No important invocation detail appears to be missing.

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

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

Schema description coverage is 100%, with both file_id and label_id clearly documented. The description adds no parameter-level detail beyond the schema, so the schema carries the parameter semantics; 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 ('Remove'), a clear resource ('label (tag)'), and a scoping qualifier ('from a single file'). This cleanly distinguishes it from sibling tools like add_tag_to_files and delete_tag.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. The phrase 'single file' implies a scope limitation, but the description does not help an agent choose between this and related tag/file operations.

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

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

The description adds meaningful behavioral detail beyond the annotations by stating 'This stores conversion settings only; converted bytes are generated on download.' This clarifies the key side effect: no converted bytes are produced at save time. The annotations declare readOnlyHint=false, which is consistent with saving, and there is 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 two sentences, front-loaded with the core purpose and followed by the crucial behavioral qualifier. Every sentence earns its place, and there is no redundant or vague 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?

With a complete input schema, annotations, and an output schema present, the description covers the essential purpose and behavior. It does not explain edge cases like overwriting an existing recipe of the same name, but for a moderate-complexity recipe-save tool, the description is sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, with all five parameters described in the schema. The description correctly summarizes them as 'conversion settings only' but adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Save a reusable image download format recipe for an image file.' The clarifying phrase 'converted bytes are generated on download' distinguishes this from a sibling like transform_image, which likely performs conversion immediately. This gives an agent a clear idea of what the tool is for.

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 phrase 'reusable' and 'generated on download' imply this is for defining persistent conversion presets rather than performing immediate conversions, but the description never explicitly says when to use this versus transform_image or upload_file. Alternatives are not named, and no exclusion conditions are 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 include readOnlyHint=false, destructiveHint=false, and openWorldHint=true, which indicate this is a write operation (creates a file) and not destructive. The description adds behavioral details: fetches URL server-side, extracts content, stores full page text for indexing, and supports workspace by name or ID. This enriches the annotations without contradicting them, but it does not disclose potential side effects like rate limiting or site access issues.

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 concise paragraph that front-loads the primary behavior and then lists secondary details. Every sentence adds information except perhaps the last sentence about workspace specification, which could be inferred from parameters. It is well-structured and not overly verbose.

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

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

Given the tool has an output schema and high schema coverage, the description covers the essential behaviors: fetching, content extraction, thumbnail generation, and storage. It does not mention error cases or limitations, but for a creation tool, the description is sufficient for an agent to invoke it correctly. Slight deduction for not mentioning that the URL might be inaccessible or that it could be a slow 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 all parameters are documented in the schema. The description adds value by explaining the 'name' parameter (defaults to page title) and the workspace resolution by name, which is beyond the schema. However, since schema already covers every parameter, 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 action (save a URL as a file), the target resource (Razuna), and the specific behaviors (fetches URL, extracts content, generates thumbnail). It distinguishes itself from siblings like 'save_url_to_collectplus' by mentioning Razuna and file record, but does not explicitly name that sibling. A score of 4 because it is clear but lacks explicit sibling differentiation.

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 (saving a web URL as a file) and mentions how workspace can be specified, but does not explicitly state when NOT to use it or provide alternatives. For example, it does not mention that for CollectPlus notes, 'save_url_to_collectplus' should be used. However, the context is fairly clear from the description 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?

Annotations already mark this as a non-read-only, non-destructive operation, so the description doesn't need to restate mutation. It adds useful behavioral details beyond the schema – the item is owner-private and created in a workspace – but leaves side effects such as duplicate handling or workspace resolution unexplained.

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 front-loads the verb and object and contains no filler. Every phrase contributes meaning: 'owner-private' and 'in a workspace' are substantive constraints.

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 5-parameter mutating tool, this one-sentence description is too thin. It doesn't explain the optional name/folder_id behavior, how workspace selection works when both workspace_id and workspace_name are absent, or what the output means, even though an output schema exists.

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

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

Schema description coverage is only 40%, and the description compensates only for 'url' and workspace context. The name and folder_id parameters have no schema description and are not mentioned in the description, so an agent cannot infer their purpose or allowed values.

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 names a specific action ('Save'), the resource ('a URL'), and the result ('an owner-private Collect+ item in a workspace'). It distinguishes the tool from sibling save_url by specifying Collect+ and owner-private visibility, and from create_collectplus_note by indicating a URL rather than a note.

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 sentence tells an agent when to prefer this over save_url, create_collectplus_note, or any other sibling. The only implied clue is the 'Collect+' qualifier, but there are no explicit conditions, 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 declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it searches only owner-private items, only within a single workspace, and uses Typesense as the backend. It does not mention pagination or query limits, but the presence of an output schema reduces the need for return-format disclosure.

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

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

The description is a single sentence with no filler. The verb and resource are front-loaded, and the qualifying constraints are packed efficiently without sacrificing clarity.

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

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

For a read-only search tool with an output schema, the description conveys the essential scope: authorized user, privacy level, workspace restriction, and search backend. It does not explain query syntax or pagination, but given the low complexity, existing schema descriptions, and read-only annotations, it is largely 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 only 50%; the page and query parameters have no descriptions. The description implies query is the search text but provides no syntax or behavior details, and page is not mentioned at all. The workspace_id and workspace_name parameters are already explained in the schema, so the description adds little over structured fields.

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

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

The description uses a specific verb ('Search'), names the resource ('Collect+ items'), and adds meaningful scope: the authenticated user's owner-private items within one workspace. This distinguishes it from siblings like list_collectplus_items and read_collectplus_item, which imply listing or reading without the search/query focus.

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 clearly implies when to use the tool: when searching the authenticated user's private Collect+ items in a workspace. However, it does not explicitly contrast with alternatives such as list_collectplus_items or search_notes, nor does it state when not to use it. The context is present but exclusions are absent.

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 the tool read-only and non-destructive; the description adds that results come from an AI semantic/vector pipeline and that conversation_id enables follow-ups. It does not detail pagination, latency, or rate limits, but those are secondary given the safety annotations and output schema.

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

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

Three short sentences with the core action front-loaded. The Typesense/embedding sentence is somewhat implementation-specific but earns its place by setting expectations about semantic matching; there is 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?

With the output schema available and all parameters documented in the schema, the description plus annotations give enough to invoke correctly. It lacks explicit guidance for choosing among sibling search tools, but that gap is about routing rather than completing this tool's contract.

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

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

The schema already describes all four parameters with 100% coverage, so the bar is a baseline of 3. The description only reinforces natural-language querying and conversation follow-up, adding no new format, default, or filter semantics.

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

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

The first sentence names the exact verb and resource ('Search documents') and adds scope ('across all accessible workspaces'), plus the natural-language/semantic mode. It is clear enough to be mistaken for neither list_documents nor simple keyword search, though it does not explicitly name sibling search tools.

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

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

The description implies this is the tool for natural-language/semantic search across all workspaces and for follow-up queries, but it never states when to use search_files or search_notes instead. No exclusions or alternative routing are 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=true and destructiveHint=false, so the bar for additional disclosure is lower. The description adds meaningful behavior beyond that: results come from a semantic/vector pipeline rather than exact keyword matching, search spans all accessible workspaces, and conversation context persists via conversation_id. 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?

Three sentences with zero waste: core purpose front-loaded, then the search mechanism, then the follow-up capability. Nothing repeats schema content or annotation data.

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

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

Annotations cover the safety profile, an output schema exists, and all parameters are documented, so the description only needed to cover scope, mechanism, and follow-up mechanics — which it does. It falls just short of 5 because it leaves unresolved what within a note is searched (content vs. title vs. metadata) and provides no alternative routing guidance.

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 four parameters are already documented in the schema; per calibration, the baseline is 3. The description lightly reinforces conversation_id's follow-up role and implies query should be phrased as natural language, but adds little meaning 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?

'Search notes using natural language' pairs a specific verb with a distinct resource and states the search approach and scope: 'across all accessible workspaces,' with 'semantic/vector search powered by Typesense embeddings.' This clearly differentiates it from sibling search tools targeting other resources, such as search_documents, search_files, and search_collectplus_items.

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 establishes clear usage context: it is for natural-language semantic search over notes across workspaces, and for follow-up questions via conversation_id. However, it never explicitly says when to prefer this over the four sibling search tools or when not to use it, leaving the routing decision entirely to inference.

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

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

The description discloses substantive behavioral traits beyond the readOnlyHint annotation: normalization, plural stemming, and fuzzy matching. It also gives concrete examples ('apples' matches 'apple', 'help monks' matches 'helpmonks') that clarify edge-case behavior. This adds real context about how the tool operates, well beyond the annotation's read-only signal.

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

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

The description is two sentences with high information density. The first sentence states the core purpose, and the second adds behavioral and usage context with examples. Every word earns its place, with no redundancy or filler.

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

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

For a simple single-parameter read-only tool with an output schema and annotations, the description is nearly complete. It covers purpose, usage timing, matching behavior, and examples. It doesn't describe the response format, but the existing output schema would cover return values, so this is a minor gap.

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

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

The schema already provides 100% coverage of the single 'query' parameter with the description 'Tag text to search for suggestions'. The tool description mentions 'given input' but does not add additional parameter-level semantics beyond what the schema already states. The examples illustrate matching behavior but not parameter format, so the 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 a specific action ('Suggest') on a specific resource ('existing document tags') for a given input. It distinguishes itself from tag creation and listing tools by emphasizing 'existing' tags and using examples that show fuzzy matching behavior. The purpose is immediately understandable and unambiguous.

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

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

The description explicitly instructs to 'Call this BEFORE adding tags to check if a similar tag already exists', which is strong when-to-use guidance. It provides illustrative examples for matching behavior. However, it does not explicitly name alternative tools (e.g., create_tag) or state when not to use it, so it falls just short of a 5.

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

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

Annotations already indicate this is a read-only, non-destructive operation, and the description adds meaningful behavior beyond that: normalization, plural stemming, fuzzy matching, and duplicate prevention. Concrete examples ('apples' matches 'apple', 'help monks' matches 'helpmonks') make the matching behavior tangible.

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

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

The description is two sentences with no filler: it front-loads the tool's purpose, then provides usage context and illustrative examples. Every sentence earns its place.

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

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

For a single-parameter, read-only suggestion tool with an output schema and annotations already present, the description fully covers what the tool does, when to call it, and how matching behaves. Nothing critical is missing.

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

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

The schema fully describes 'query' as 'Tag text to search for suggestions', and the description supplements this with the matching semantics and examples. It clarifies that the query is the input text to match against existing tags, adding useful behavioral context beyond the bare schema.

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

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

The description states a specific action ('Suggest existing note tags') for a specific resource ('a given input'), and clarifies it finds existing tags rather than creating new ones. This differentiates it from siblings like create_tag and suggest_document_tags by scoping to note tags and to lookup/suggestion behavior.

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

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

The description explicitly says to call this tool 'BEFORE adding tags to check if a similar tag already exists', giving clear when-to-use guidance. It does not enumerate alternatives or explicitly say when not to use it, but the context is strong enough for an agent to select it appropriately.

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 destructiveHint=false, so the description doesn't need to repeat those. The addition of 'owner-private' provides some scope/behavior context beyond the schema. However, it does not disclose whether the update is partial or full replacement, whether it is reversible, or any permission requirements. With annotations covering the basic safety profile, the description adds minimal extra value.

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 sentence, which is concise and front-loads the action ('Update'). However, it is so brief that it omits valuable information. It earns its place as a clear purpose statement, but the structure is not used to convey any additional guidance. It is appropriately sized for a minimal purpose statement, but not for a tool with 8 parameters.

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

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

The tool has 8 parameters, 7 optional, and an output schema. The output schema covers return values, so that is not a gap. However, the description does not explain what fields are updateable, what 'owner-private' means, or how workspace_id/workspace_name relate to the item. Given the low schema coverage and the number of ambiguous parameters, an agent would not have enough information to call the tool correctly without additional external knowledge.

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

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

Schema description coverage is only 25% (only workspace_id and workspace_name have descriptions). The description does not compensate by explaining any of the other six parameters (name, note, labels, keywords, description). An agent has no idea what 'name' or 'note' mean in this context, or whether 'labels' and 'keywords' are lists of tags. The description adds zero parameter meaning, so the low schema coverage is unmitigated.

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

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

The description states a specific verb ('Update'), a specific resource ('Collect+ item'), and two scope qualifiers ('owner-private' and 'in a workspace'). This clearly distinguishes it from other update tools like update_document and update_note, which operate on different resource types. An agent can tell exactly what this tool acts on.

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 implies the tool is used when you need to modify an existing owner-private Collect+ item. However, there is no explicit guidance on when to prefer this over alternative tools, no mention of prerequisites (e.g., need for owner access), and no exclusion cases. The usage context is implied by the verb and resource name, but not explicitly 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 indicate this is not read-only and is not destructive. The description adds context that moving affects the folder tree, but it does not disclose side effects such as whether child folders/files move along with the folder or whether rename affects existing references. The bar is lower because annotations supply the safety profile, but additional behavioral detail is still limited.

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 covers the capabilities in a front-loaded list and then supplies a practical use case. There is no redundancy, filler, or repeated schema 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 simple update tool with full schema coverage Hua output schema present, the description is largely sufficient. The only notable gap is not explaining recursive effects of moving a folder, but the agent can infer the main purpose and call 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 description coverage is 100%, so the input schema already documents all four parameters and their meanings. The description adds the mapping of rename to name, move to parent_id, and color to color, but does not add format, constraints, or interaction details beyond the schema.

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

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

The description names a specific verb and resource ('Rename a folder, move it under a new parent, or change its color') and clearly enumerates the operations. This distinguishes it from sibling tools like create_folder or move_file, so an agent can identify what this tool is for.

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 concrete usage contexts: 'fix typos in folder names or reorganize the folder tree without opening the web UI.' It does not explicitly state when not to use it versus file-moving siblings, but the folder-specific wording and operation list make the alternatives reasonably clear.

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 readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate that this is a mutation. The description adds the specific fields that can be updated, which is useful. However, it doesn't disclose any side effects, such as whether updating a parent affects child tags or whether changes are reversible. With annotations covering the basic safety profile, a 3 is appropriate.

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

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

The description is a single, efficient sentence that front-loads the action and lists the updatable fields. It earns its place with no wasted words, though it could be slightly more explicit about usage context.

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

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

The tool has an output schema and full schema coverage, so the description doesn't need to explain return values or parameters. However, for a mutation tool, it would be helpful to mention any side effects or prerequisites, such as whether the tag must exist or what happens to child tags when the parent changes. The description is adequate but not complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description lists the fields (name, color, parent) but doesn't add meaning beyond what the schema provides. The parent_id parameter's special value '0' is documented in the schema, not the description, so the description adds minimal value here.

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 clear verb and resource: 'Update a tag's name, color, or parent.' This distinguishes it from sibling tools like create_tag and delete_tag, though it doesn't explicitly name them. The scope is specific enough for an agent to understand the tool's function.

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 listing the updatable fields, but it doesn't explicitly state when to use this tool versus alternatives like create_tag or delete_tag. There is no mention of prerequisites or context, so the agent must infer when this tool is appropriate.

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