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

With no annotations provided, the description takes on the full burden of behavioral disclosure. It thoroughly explains the return dict and all possible modes, including error handling and upgrade_url. While it doesn't explicitly state 'this is read-only', the consistent 'Return' language and lack of side-effect indications make the behavior sufficiently 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 concise and excellently structured. It opens with a clear purpose, includes a usage note, and lists return keys in a readable format. Every sentence and line adds value, and the organization makes it easy to scan.

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

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

For a zero-parameter tool with no output schema, the description is complete: it specifies the exact return dict, explains each key's meaning, and covers error scenarios. It also provides usage context, making it fully self-contained.

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

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

The tool has zero parameters, which sets a baseline of 4. The description adds no parameter information because there are none, which is appropriate. The return structure is described instead, but that's covered under other dimensions.

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 identifies the action and resource: 'Return the current LoreDocs license tier and status.' It also specifies a key use case: 'confirm whether the Pro license key is loaded and valid.' However, it does not explicitly differentiate this tool from sibling tools like vault_tier_status, so it doesn't earn a 5.

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

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

The description provides a direct usage instruction: 'Use this to confirm whether the Pro license key is loaded and valid.' This gives clear contextual guidance for when to use the tool. It does not mention alternatives or when not to use it, which prevents a higher score.

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

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

With no annotations provided, the description carries the full burden of disclosure. It goes beyond a simple statement by detailing the return structure: product version, SDK version, tested version, compatibility status, and a dict with specific keys. It even explains the 'error_detail' field is set only on 'internal_error,' which is transparent about conditional behavior.

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

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

The description is compact: three sentences that lead with the main action, then a use-case note, then a structured list of return fields. Every sentence adds value, and the information is front-loaded. No fluff or repetition.

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 there is no output schema, the description fully documents the return values, including possible statuses and when error_detail appears. It also communicates the operational context (diagnosing version mismatches) and the fact that no restart is needed. The tool is simple, and this description covers all necessary aspects.

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

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

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for 0 parameters is 4, and the description does not need to compensate. The empty schema is fully covered, and the description focuses on the output instead.

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 starts with a specific verb and resource: 'Return MCP compatibility status for this LoreDocs server.' This clearly distinguishes it from vault-centric siblings and even the related vault_get_server_capabilities by focusing on version and compatibility. The purpose is unambiguous and immediately understandable.

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

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

The description states 'Useful for diagnosing version mismatches on running servers without requiring a restart,' which gives a clear, concrete use case. It does not explicitly mention alternatives or when not to use it, but the context is strong enough to guide selection. The phrase 'without requiring a restart' adds practical value.

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

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

Beyond the annotations (idempotentHint true, destructiveHint false), the description discloses that existing data is never modified, details what gets created, and notes the reference doc is queryable. This provides richer behavioral context than 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 well-structured: a lead sentence, call guidance, a bulleted list of creations, and parameter explanations. The additional tag/priority information is contextual and earns its place by explaining the created setup.

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 usage, behavior, parameters, and created artifacts comprehensively. The only minor gap is that all parameters are optional in the schema, but the description does not clarify what happens when called with no arguments (e.g., whether only the Config vault is created).

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 0%, but the description explains each parameter (name, domains, agents, tag_style) with examples and default values. It fully compensates for the missing schema descriptions.

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

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

The description clearly states 'Set up or update your LoreDocs workspace configuration' and enumerates the concrete artifacts created (Config vault, per-domain vaults, per-agent report vaults). This distinguishes it from sibling vault_* tools, which handle individual documents or vault operations.

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

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

Explicit usage guidance is provided: 'Call once after installing LoreDocs to get a recommended vault structure. Call again to add new domains or agents -- existing data is never modified.' This tells the agent exactly when to invoke it and reassures about non-destructive behavior.

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

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

The description discloses that documents are 'full-text indexed' and 'stored with version tracking', adding value beyond the annotations (all false). However, it does not clarify critical behavioral traits such as what happens if both content and path are supplied, whether existing documents with the same name are overwritten or versioned, or any permissions required. Annotations are minimal (all false), so the description carries more burden but still leaves gaps.

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

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

The description is four sentences, each conveying distinct information: purpose, indexing/versioning, content input options, and the binary-file alternative. No fluff or repetition.

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 mutation tool with a moderate parameter count and an output schema, the description provides the essential operational context: text-only, content via inline or path, metadata support, and the correct alternative for binaries. It falls short on parameter interplay (e.g., path vs content precedence) and what 'name' represents, but overall it equips an agent for typical use.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions content, path, and metadata fields (tags, category, priority, notes), but does not explain the role of 'name' vs 'filename', the relationship between content and path, or the vault parameter. With 9 parameters and zero schema descriptions, this partial coverage leaves ambiguity.

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 'Add a text document to a vault with metadata', a specific verb+resource statement. It also distinguishes from binary-file imports by pointing to vault_import_dir, making the scope (text documents) explicit.

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

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

It clearly states when to use this tool vs alternatives: 'For binary files (PDF, DOCX, etc.), use vault_import_dir to import from a directory.' It also explains the two content input modes (inline content or file path), which guides usage choices.

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

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

Annotations already provide key behavioral hints (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description does not contradict these and adds a note on the intended use of notes, but it does not disclose whether notes are appended, replaced, or how repeated calls behave beyond the annotations. With annotations covering safety, the description adds minimal extra transparency.

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

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

The description is concise, with exactly two sentences. It front-loads the action and adds a purposeful explanatory sentence without any redundant fluff. Every sentence contributes value.

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

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

The tool is simple (two string params) and has an output schema, so the description need not explain return values. However, it leaves ambiguity around whether notes overwrite existing notes or are appended, and it does not specify the doc_id format. These gaps prevent it from being fully 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 0%, so the description must compensate. It gives some hint about the 'notes' parameter ('contextual note... when/how to use this document') but does not clarify 'doc_id' or the expected format/structure of notes. This is insufficient for fully understanding the 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: 'Attach a contextual note to a document.' This specifies the verb (attach), resource (document), and distinguishes it from sibling tools like vault_add_doc or vault_tag_doc. The second sentence provides additional context about the note's purpose, reinforcing clarity.

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

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

The description explains the purpose of notes ('help you and your AI assistant understand when/how to use this document') but does not explicitly state when to use this tool versus alternatives or any exclusions. Usage is implied rather than stated, so it falls short of clear 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?

Adds valuable behavioral context beyond annotations: soft delete, hidden from default vault_list, and restorable. This complements the idempotentHint and destructiveHint annotations without contradiction.

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

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

The description is a single, front-loaded sentence that conveys the essential action and key side effects without any wasted words.

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

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

For a one-parameter tool with an output schema and annotations, the description covers the most important user-visible behavior. It could mention how to restore, but that is not essential for selecting/invoking the tool.

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

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

With zero schema description coverage, the description should explain what the 'vault' parameter accepts (ID, name, path). It does not go beyond the schema's basic title, leaving ambiguity for an agent.

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

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

Description uses specific verb 'Archive' plus resource 'vault' and clarifies it's a soft delete. It clearly distinguishes from permanent deletion tools like vault_delete by stating archived vaults can be restored.

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 (for soft deletion) and notes that archived vaults are hidden from vault_list by default, providing context. It does not explicitly name an alternative like vault_delete for permanent deletion but the implication is 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 already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds no additional behavioral detail (e.g., how add/remove interact, whether existing tags are affected). The bar is lower given annotations, but the description adds minimal context beyond what annotations already convey.

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, no filler. The first sentence states the core function, the second gives a usage scenario. 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 3-parameter tool with output schema, the description is too thin. It omits parameter semantics and the relationship between add_tags and remove_tags. While the output schema covers return values, the input side is severely under-documented.

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 0%, so the description carries full burden for explaining parameters. It fails to mention doc_ids, add_tags, or remove_tags. The agent gets no guidance on how to structure the bulk operation or what each field means.

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

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

The description opens with a specific verb+resource+scope: 'Apply tag changes to multiple documents at once.' This clearly distinguishes it from the sibling tool 'vault_tag_doc' (which is singular) and immediately conveys the batch nature of the 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 second sentence provides concrete context: 'Useful for organizing a batch of documents after import or reclassification.' This tells the agent when to reach for this tool, although it doesn't explicitly mention alternatives or when not to use it.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is known. The description adds no additional behavioral context such as overwriting behavior, permission requirements, or side effects. It merely restates the action without going beyond the structured annotations.

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

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

The description is a single sentence that is direct and front-loaded, containing no filler. It efficiently conveys the tool's purpose and the allowed values without excess verbiage.

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 setter with annotations and an output schema, the description is largely adequate. It covers the core function, though it omits nuanced details like whether an existing category is overwritten. Given the low complexity, this is a minor gap.

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

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

Schema description coverage is 0%, so the description must compensate. It lists the category enum values (which is redundant with the schema) but does not explain the doc_id parameter or clarify the parameter semantics beyond what the schema names. Minimal additional meaning is provided.

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

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

The description clearly states the action 'Set a document's category' and lists all allowed categories, making it specific and distinguishable from sibling tools like vault_tag_doc (tags) and vault_set_priority (priority). It precisely identifies the resource and the 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 implies usage for categorizing documents but provides no explicit guidance on when to use this tool versus alternatives (e.g., tagging or setting priority). It lacks exclusions or alternatives, so usage context is only implied by the category list.

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 tool is known to be a non-destructive mutation. The description adds the useful detail that all metadata is copied, but does not disclose behavior like whether an existing document in the target vault is overwritten or idempotency (annotations already say idempotentHint=false). No contradiction between annotations and description.

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

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

The description is a single, well-structured sentence that starts with the action verb and packs in the source, destination, and scope. 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 relatively simple tool with two parameters and an existing output schema, the description covers the core intent and metadata handling. It does not explain edge cases like behavior if doc_id does not exist or if target_vault is invalid, but annotations and output schema partially compensate. Overall, adequate for the tool's complexity.

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

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

Schema description coverage is 0%, and the description only indirectly maps 'doc_id' to 'a document' and 'target_vault' to 'another vault'. It does not explain parameter formats, constraints, or behavior (e.g., whether target_vault must exist). The param names are self-explanatory, but the description adds minimal semantic value beyond that.

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 operation (copy), the resource (a document), and the scope (from one vault to another, including all metadata). It distinguishes itself from siblings like vault_move_doc by specifying 'copy' rather than 'move'.

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 use when a duplicate copy is needed while preserving the original. However, it does not explicitly mention alternatives like vault_move_doc or provide when-not-to-use guidance. The context is clear but lacks explicit exclusions.

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

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

The description discloses the core behavior (creation) and the return value (ID and metadata), adding context about vault independence and project linking. However, it doesn't mention potential side effects, permissions, or behavior on duplicate names, and the annotations provide no positive safety signals (all false), so the description carries the burden but leaves some gaps.

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

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

The description is two short paragraphs that are front-loaded with the core purpose, followed by a brief explanation of the vault concept and the return value. Every sentence contributes value, with no filler or excessive detail.

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

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

The description explains the core concept and return value, which is good given the output schema. However, with five parameters and zero schema descriptions, the lack of parameter explanation leaves the tool only partially documented. It also doesn't address usage boundaries with related vault tools, though the simple create operation reduces the need for extensive context.

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

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

The schema has 0% parameter descriptions, so the description must compensate. It adds meaning only to 'name' (implied) and 'linked_projects' (via the linking explanation), but ignores 'tags', 'description', and 'response_format', leaving the agent to guess their semantics from names alone.

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

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

The description clearly states the specific action ('Create a new knowledge vault') and the resource being created. It explains what a vault is, effectively distinguishing this tool from the many related vault_* operations that operate on documents or sessions.

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 on when to use the tool: to create a vault that can be linked to Claude Projects, emphasizing that vaults are independent and reusable. It doesn't explicitly say when not to use it or name alternatives, but the purpose is unambiguous enough that an agent can infer appropriate usage.

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

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

Beyond the destructiveHint annotation, the description discloses that the action is permanent ('cannot be undone'), affects ALL documents, and requires explicit confirmation via confirm=true. This adds crucial behavioral context that annotations alone do not provide.

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, front-loaded sentences. Each sentence earns its place: what happens, a critical warning, and a required condition plus an alternative. No wasted words.

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

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

The description is complete for a destructive tool: it covers purpose, irreversibility, the confirmation requirement, and points to a safer alternative. Given the output schema exists, it doesn't need to explain return values. The agent has all necessary context to invoke 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 0%, so the description must add meaning. It explains the confirm parameter's role ('must set confirm=true to proceed'), which is essential and not obvious from the schema alone. However, it provides no additional detail about the vault parameter format, so it doesn't fully compensate.

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: 'Permanently delete a vault and ALL its documents.' This is specific with a verb and resource, and it distinguishes itself from siblings by emphasizing permanent deletion and the alternative 'vault_archive'.

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 explicitly says 'Consider using vault_archive instead,' providing an alternative for non-permanent needs, and states the required condition 'You must set confirm=true to proceed.' It could be improved by explicitly saying when not to use, but the context is 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 already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds useful context about automatic version saving, which is beyond annotations. However, it does not detail other behaviors like whether it returns metadata or content diffs, which the annotations do not explicitly cover.

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 wasted words. It front-loads the purpose, adds one contextual fact, and names the alternative. Perfectly concise.

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

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

The tool is simple, has an output schema, and annotations cover safety. The description explains the automatic versioning behavior and points to restore for reverting. It omits details like whether history is ordered or includes timestamps, but the output schema likely covers that. Sufficiently 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 0%, so the description must compensate. It only implies that 'doc_id' refers to a document but does not explicitly explain how to obtain it, its format, or that it identifies the document whose history is viewed. This adds minimal meaning beyond the schema's 'Doc Id' title.

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 'View the version history for a document' with a specific verb and resource. It distinguishes itself from sibling tools like vault_doc_restore (revert) and vault_get_doc (current content), 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 description provides explicit context: when a document is updated, previous versions are saved automatically. It also names the alternative for reverting (vault_doc_restore), giving clear guidance on when to use this tool versus the sibling.

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 only indicate readOnly=false and destructive=false. The description adds valuable behavior: current version is saved to history first, then the specified version becomes current. This clarifies that existing data is preserved before change, going beyond annotation hints.

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

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

Two concise sentences: the first states the purpose, the second adds behavioral context. No filler or redundancy. Front-loaded and 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?

With an output schema present, return values are covered. Tool complexity is low, but the description lacks parameter semantics and guidance on when to use this over siblings. It provides adequate behavioral context but has clear informational gaps for an AI agent.

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

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

Schema coverage is 0% and the description does not explain doc_id or version. The phrase 'previous version' implies the version parameter, but there is no detail on version numbering, format, or doc_id identification. This fails to compensate for missing schema descriptions.

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

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

Description uses specific verb 'Restore' with resource 'document version', clearly distinguishing it from siblings like vault_doc_history (view history) and vault_update_doc (edit current content). The purpose is immediately obvious.

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

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

The description states what the tool does but gives no explicit when-to-use or alternatives. Implied use is rollback to a previous version, but it does not reference sibling tools like vault_doc_history for selecting a version or exclude alternative scenarios.

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 idempotentHint=true, and the description reinforces no side effects by saying 'without injecting documents'. It adds useful behavioral details such as the 500-document limit and the estimation approach (tiktoken with fallback to char-based), which go beyond the annotations.

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

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

The description consists of two sentences, front-loaded with the main purpose, and contains no redundant phrases. It efficiently communicates the core function and key limitations without unnecessary detail.

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

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

The description provides a clear overall purpose and mentions the 500-document limit and return of per-document token counts, but leaves parameter semantics entirely unexplained. With an output schema present, return values are partially covered, yet the lack of parameter context makes the tool not fully self-contained for a new agent.

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

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

Schema description coverage is 0%, and the description fails to explain the three parameters. It mentions 'max_tokens' as an output use case, but the actual parameter is 'max_single_doc_tokens', and there is no explanation for 'vault_name' or 'query'. This is a significant gap for parameter understanding.

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 begins with a specific verb 'Preview' and resource 'token count of a vault injection', clearly distinguishing it from the injection operation. It also states 'without injecting documents' to differentiate from the actual injection tool, and mentions the 500-document limit, making the purpose unambiguous.

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

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

The description explicitly states the tool is used 'before calling vault_inject' to choose an appropriate max_tokens value, providing clear context for when to use it. It does not list exclusions or alternatives, but the reference to vault_inject serves as a direct sibling comparison.

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 non-destructive and idempotent behavior. The description adds valuable detail that goes beyond annotations: it copies original files rather than extracted text, and exports all documents. It does not mention overwrite behavior or directory creation, but the annotation profile reduces the need for more.

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

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

The description is three concise sentences: it states the action, clarifies the copy behavior, and indicates a use case. It is front-loaded with the essential purpose and contains no fluff or redundancy.

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

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

The tool is simple (two parameters) and has an output schema, so return values are already covered. The description covers the core functionality, the type of data copied, and typical use cases. It could mention whether the directory must pre-exist or if structures are preserved, but overall it is sufficient for an agent to invoke 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?

With schema description coverage at 0%, the description must compensate. It implicitly maps parameters by saying 'from a vault to a local directory,' which clarifies vault and directory roles. However, it does not define parameter formats, accepted values, or path conventions, leaving a gap that a more detailed description could fill.

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 verb and resource: 'Export all documents from a vault to a local directory.' It distinguishes from siblings like vault_export_manifest by specifying 'Copies the original files (not extracted text)' and 'all documents,' which separates it from manifest or single-doc export 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?

It provides clear context for when to use the tool: 'Useful for backing up or sharing vault contents.' However, it does not explicitly exclude alternatives or mention when not to use it, such as when only a manifest is needed (vault_export_manifest). This is a clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the returned contents (tag frequency index, category counts, link count), which is useful. However, it does not disclose any potential pitfalls, prerequisites (e.g., session token), or edge cases, so it adds only moderate behavioral context beyond the annotations.

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

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

The description is concise and well-structured: one opening purpose sentence, a bullet-like list of returned content, and two short sentences on format selection. Every sentence adds value and the most critical information is front-loaded. No unnecessary words or repetition.

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 fairly complete for a read-only export tool: it covers purpose, return contents, and format options. The presence of an output schema reduces the need to explain return value structures. It lacks differentiation from sibling tools and any caveats, but given the output schema and annotations, it provides sufficient context for an agent to invoke it correctly in most situations.

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 0%, so the description must compensate for parameter meaning. It does address the 'format' parameter by explaining json vs markdown outputs. The 'vault' parameter is not explained, but it is self-evident from the tool name and the phrase 'a vault's contents.' Thus, the description partially compensates but leaves the vault parameter underspecified, justifying a mid-range score.

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

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

The description clearly states the tool's function: 'Export a complete manifest of a vault's contents' and enumerates the returned data (vault metadata, document list, tag frequency index, etc.). It uses a specific verb and resource, making the purpose clear. However, it does not explicitly differentiate from sibling tools like vault_export, which could be similar, so it falls short of a full 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?

The description provides format guidance ('Use the json format for machine-readable output. Use the markdown format for human-readable summaries.') but offers no guidance on when to choose this tool over alternatives such as vault_export or vault_list_docs. There is no explicit when/when-not or mention of alternative tools, making this a weak dimension.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful context: the 'Pro only' restriction and the specific fields returned (vault, category, tags, link label), which go beyond the structured fields.

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

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

Four short sentences, each providing essential information: purpose, restriction, return summary, and an alternative tool. No waste.

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 simple single-parameter API, output schema, and safe annotations. The description covers the purpose, return fields, and Pro-only restriction, making it fully adequate for an agent to use 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 schema has 0% description coverage, so the description must compensate. It only vaguely refers to 'a given document' and does not clarify the doc_id parameter format or semantics beyond what the schema title 'Doc Id' implies. For a single param this is adequate but still minimal additional 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 the specific verb 'find' and clearly identifies the resource: documents linked to a given document. This distinguishes it from sibling tools like vault_link_doc (create links) and vault_get_doc (retrieve a single 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?

It names the alternative vault_link_doc for creating links, giving clear direction on when to use this tool vs that one. However, it doesn't explicitly state exclusions or broader use cases, so it falls 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 declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is clear. The description adds behavioral nuance about the include_content option and its performance implication (loading the full text), which is not 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?

Two sentences: the first states the core purpose, the second gives a specific usage tip. No unnecessary words, and the most important information is front-loaded.

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

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

The tool is simple with 3 parameters and an output schema. The description covers the main behavior and the optional content parameter; annotations handle safety. It doesn't mention response_format, but the schema's enum provides that information.

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

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

With 0% schema description coverage, the description compensates by explaining include_content's effect ('to get just the metadata without loading the full text'). doc_id is inferable from the tool name, and response_format has enum values, so the description adds meaningful value for the key boolean parameter.

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

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

The description uses the specific verb 'Retrieve' and the resource 'document's metadata and optionally its text content', clearly distinguishing it from tools like vault_list_docs or vault_search. It clearly states the tool's primary 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?

It provides clear context that this tool retrieves a single document and gives explicit advice on when to set include_content=false to avoid loading the full text. It doesn't name alternative tools or exclusions, but the context is understandable without them.

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

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

Annotations already declare read-only and idempotent hints, so the safety profile is known. The description adds valuable behavior: the fallback chain to environment variables and the default cap, plus the 'not set' return condition. This goes beyond what annotations cover and helps the agent predict outcomes.

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 primary action and including only essential fallback details. Every sentence earns its place, with no fluff or repetition.

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 getter with one parameter and an output schema, the description explains the main behavior (return cap, 'not set' case, fallback chain). It is complete for typical usage, though it does not discuss error handling for invalid vault names, which may be covered by the output schema or error messages.

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 has 0% description coverage, so the description must compensate. It mentions 'per-vault' which implies vault_name identifies a specific vault, but it does not explicitly define the parameter or explain edge cases (e.g., nonexistent vault). Since the parameter is simple and self-explanatory from the tool name, a score of 3 is acceptable.

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

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

The description clearly states the tool's purpose: 'Return the stored per-vault injection token cap (or 'not set' if none).' This uses a specific verb ('return') plus resource ('per-vault injection token cap') and distinguishes it from sibling tools that handle injection or configuration differently.

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 the tool is used: to retrieve the stored cap for a specific vault, including fallback behavior when unset. However, it does not explicitly name alternatives or state when not to use it, though the purpose is specific enough to make usage obvious.

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

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

With no annotations, the description carries the full burden and does well: it discloses the underlying table, source/target behavior, auto/manual link handling, Pro tier requirement, and return structure reference. It could be more explicit about failure behavior or non-Pro behavior, but overall it provides meaningful operational 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 compact and well-structured: a purpose sentence, a short behavioral paragraph, an Args list, and a return reference. Every sentence adds useful information without redundancy or bloat.

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 only 2 parameters, no annotations, and no output schema, the description covers the essential ground: purpose, data source, link types, Pro tier constraint, parameter semantics, and return structure via a reference to vault_get_session_links. Minor gaps remain around error handling and non-Pro behavior, but the core context is solid.

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

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

The input schema has 0% description coverage, but the description fully compensates by explaining both parameters: session_id is a LoreConvo session UUID, and limit is max results with a default of 5. This adds clear meaning 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 opens with a specific verb and resource: 'Return LoreDocs documents linked to a given LoreConvo session.' It clearly distinguishes this from sibling tools like vault_get_session_links by explaining it queries the cross_product_links table and returns both auto and manual links.

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

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

The description implies usage context by explaining what the tool does and the Pro tier requirement for auto-links, but it does not explicitly state when to use this tool vs. alternatives like vault_get_session_links. There is no direct 'use this when...' or 'instead of...' 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, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds behavioral context by specifying exactly what the summary includes (injection capabilities and token estimation settings) and why it would be used (diagnostics, feature verification). No contradictions.

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

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

Two sentences, with the main action and scope in the first sentence and a brief use case in the second. No fluff or redundancy; every word earns its place.

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

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

Given the zero parameters, rich annotations, and presence of an output schema, the description fully covers what the tool does and when to use it. The simplicity is appropriate for the tool's complexity.

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

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

This tool has zero parameters, so the baseline is 4. There is nothing to document beyond schema, and the description correctly focuses on the tool's purpose rather than 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 ('Return a summary') and names the exact resource ('LoreDocs server's injection capabilities and token estimation settings'). It clearly distinguishes this from sibling tools like vault_get_injection_cap and vault_estimate_tokens by presenting a consolidated overview rather than a specific value.

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

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

The description states it is 'Useful for diagnosing injection behavior or verifying which features are active,' which gives clear context for when to call it. However, it does not mention when not to use it or explicitly point to alternatives, so it falls short of a perfect 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?

With no annotations, the description carries the burden of behavioral disclosure. It reveals prerequisites, tier gating, and the exact return dict structure including fields like tier_gate and is_stale. It does not explicitly state that it is a read-only operation, but the 'Return' language and lack of side-effect language imply safety, and the return schema is well documented.

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

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

The description is well-organized with a clear intro, an Args section, and a Returns section. Every line adds relevant information with no fluff, making it efficient and easy to scan.

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

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

Given the absence of annotations and output schema, the description is remarkably complete. It covers prerequisites, tier behavior, and the full return payload including schema_version for version negotiation. No critical operational 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?

The input schema has no descriptions (0% coverage), but the description compensates by explaining doc_id as the LoreDocs document ID and limit as max results with a default of 5. This adds meaningful semantics beyond the bare schema, though it does not elaborate further on edge cases or formatting.

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

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

The description opens with a precise verb and resource: 'Return cross-product LoreConvo sessions linked to a LoreDocs document.' This clearly identifies the tool's function and distinguishes it from siblings like vault_get_linked_sessions by specifying the cross-product nature and the LoreDocs document linkage.

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 by stating that both LoreConvo and LoreDocs must be installed, and that Pro tier is required for auto-links while manual links are always returned. It does not explicitly name alternative tools or when not to use it, but the prerequisites and conditions give solid practical 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 only provide false hints for readOnly, idempotent, and destructive, leaving the description to explain behavior. It does so by disclosing that the token is a fresh UUID4, that it scopes per-session cache, and that cache validity ends when any vault document is updated. This adds meaningful behavioral context without contradicting annotations.

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

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

The description is three sentences, each with a clear role: generation, usage instruction, and cache validity. No wasted words; all information is front-loaded and directly relevant. It is exceptionally concise while covering purpose and usage.

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 that there are no parameters and the tool relies on an output schema (not shown), the description covers the essential context: what the token is, how to use it, and when it becomes invalid. It leaves no significant gaps for the agent's decision-making.

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

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

The tool has zero parameters, so the schema is trivially complete. The description correctly mentions no parameters but explains how the return value should be used (passed as session_token), which is useful additional semantics. Baseline for 0 params is 4, and the description meets it.

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

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

The description clearly states the tool's function: 'Generate a fresh session token (UUID4) for use with vault_inject / vault_prime.' This is a specific verb (generate) with a concrete resource (session token) and its intended downstream use, distinguishing it from sibling tools like vault_link_session or vault_get_server_info.

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 when to use the token: 'Pass the returned token as session_token in subsequent injection calls' and ties the usage to vault_inject/vault_prime. It provides clear context for why this tool is needed (scoping cache to a conversation), effectively guiding the agent on when to call it relative to other tools.

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

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

Beyond the annotations (all false, no safety hints), the description adds valuable behavioral details: files over 30MB are skipped, hidden files are skipped, subdirectories are traversed recursively by default, and YAML frontmatter tags are merged into documents. This gives the agent a good sense of what will happen during import, though it doesn't clarify behavior for existing documents or partial failures.

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: a clear purpose statement followed by relevant bullet-like behavior details. Every sentence adds value, no fluff, and it's front-loaded with the primary action.

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 bulk import tool with 5 parameters and an output schema, the description covers key aspects: supported formats, size limits, hidden files, recursion, and frontmatter handling. It doesn't explain the 'category' parameter or what happens on naming conflicts, but these are minor gaps given the output schema exists and the description is otherwise informative.

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 0%, so the description must explain parameters. It clarifies 'directory' (the source path) and 'recursive' (set recursive=False for single-level) and partially describes tag handling via frontmatter. However, 'vault' and 'category' are not explained, and the 'tags' parameter's meaning (likely tags applied to all imported docs) is ambiguous—it might be confused with frontmatter tags.

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 'Bulk import all supported files from a directory into a vault,' using a specific verb (import), resource (directory into vault), and scope (bulk). It also lists supported file types and clearly distinguishes itself from siblings like vault_add_doc (single file) or vault_import_notion (Notion-specific).

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

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

The description provides clear context for when to use this tool: when you need to bulk import files from a directory into a vault. It mentions recursive traversal and the ability to set recursive=False for single-level imports. However, it doesn't explicitly mention alternatives or when not to use it (e.g., for single-file import), but the purpose is unambiguous enough.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation. The description adds substantial behavioral context: token is read from environment/keychain and never passed as a parameter, vault ID is stable vs name case-insensitive, UUID formats are specified, continuation token semantics and invalidation are explained, block depth cap produces truncated_pages, and MCP host cancellation may leave partial checkpoints with a resumption path. There is no contradiction with annotations; in fact, the deduplication note reinforces idempotency.

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 multi-paragraph and fairly long, but it is well structured. It opens with the core purpose and then dedicates paragraphs to token handling, vault identification, ID formats, continuation tokens, block depth cap, and cancellation behavior. Every sentence adds value, though a few details (e.g., 'Both null/omitted = rejected') could be phrased more succinctly. Overall, the length is appropriate for the tool's complexity.

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

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

Given the tool's complexity—9 parameters, external token retrieval, resumption, cancellation handling, and block depth limits—the description covers a remarkable amount of context: security (token logging), input validation (UUID format), error handling (truncated_pages, partial checkpoints), and deduplication. It does omit explanations for several parameters and assumes familiarity with Notion IDs, but since an output schema exists, return values are likely documented elsewhere. This is nearly complete but has minor 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 0%, so the description must fully compensate. It explains vault, page_ids, database_ids, and continuation_token in detail, and checkpoint_file is referred to indirectly. However, four key parameters—tags, category, max_pages, and resume—are completely unexplained. For a 9-parameter tool, leaving 4+ parameters undocumented in both schema and description is a significant gap that forces the agent to guess.

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

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

The description clearly states the tool's function: 'Import Notion pages and databases into a LoreDocs vault.' The verb 'import' is specific, and both the source (Notion pages/databases) and destination (LoreDocs vault) are named. This distinguishes it from sibling tools like vault_import_dir (local directory import) and vault_import_notion_setup (setup, not import).

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

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

The description provides clear context: it explains the import-once-and-own model and explicitly states 'No live sync dependency,' which serves as a when-not-to-use signal for users needing live sync. It also gives practical guidance on vault identification (ID vs name) and required page_ids/database_ids. However, it never names alternative tools (e.g., vault_import_dir or a hypothetical sync tool), so it stops short of fully explicit exclusions/alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with "Read-only." It adds value beyond the annotations by explicitly stating "Does not install or modify any packages," which clarifies that the tool avoids any side effects beyond reading, a useful detail for agents concerned about system changes.

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 extremely concise: two short sentences that front-load the core purpose. Every word earns its place, with no filler or redundancy. The structure is efficient and immediately understandable.

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

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

Given the tool's low complexity (no parameters, no output schema, read-only annotations), the description is fully sufficient. It explains what the tool does, emphasizes its non-invasive nature, and the sibling list clarifies how it differs from `vault_import_notion`. No additional context is needed for an agent to invoke 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 tool has no parameters, so schema description coverage is 100% by default. The description does not need to explain parameter meanings, and the baseline of 4 is appropriate for a zero-parameter tool since no additional semantic guidance is required.

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

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

The description clearly states the tool's function: "Report Notion import readiness and how to enable it." This specifies a verb (report) and a resource (Notion import readiness), and it distinguishes this tool from the sibling `vault_import_notion`, which actually performs the import.

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 as a preflight diagnostic by noting "Read-only" and "Does not install or modify any packages," which strongly suggests it should be used before the actual import. However, it does not explicitly name alternatives or state when not to use it, leaving the guidance somewhat implied rather than 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 readOnly, idempotent, and non-destructive behavior. The description adds that the tool returns a document manifest, which is useful output context. However, it does not disclose any additional behavioral traits beyond what annotations provide, so it only modestly enhances transparency.

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

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

The description is two concise sentences with no unnecessary words. It front-loads the purpose and includes a helpful input note, making it highly efficient and well-structured.

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

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

The tool is simple and has an output schema, so the description doesn't need to detail return values. It covers the core purpose but omits response_format semantics and explicit usage context, which are relevant to fully leveraging the tool.

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

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

The description adds meaning to the 'vault' parameter by clarifying it accepts either an ID or name, which is helpful for a schema with 0% coverage. However, it completely ignores the 'response_format' parameter, leaving a gap. The partial compensation earns a middle score.

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

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

The description states a clear action ('Get detailed information about a vault') and specific resource ('vault') with a concrete output detail ('full document manifest'). This distinguishes it from mutation tools, though it doesn't explicitly differentiate from similar read tools like vault_list_docs or vault_export_manifest.

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 only mentions input flexibility ('Accepts either a vault ID or vault name') but provides no guidance on when to use this tool versus alternatives. No exclusions or alternative tool references are given, leaving the agent without clear selection criteria.

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

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

Despite annotations already declaring readOnly, idempotent, and non-destructive behavior, the description adds substantial details: ranking algorithm, greedy packing, effective cap calculation, cap_behavior modes, per-session caching, and per-doc truncation. These go well beyond annotations.

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

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

The description is well-structured: a crisp one-line summary, a concise explanatory paragraph, and a clear Args list. Every sentence carries meaningful information 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 tool with 7 parameters and complex ranking/budget behavior, the description covers all key aspects: selection criteria, token budget enforcement, caching, and truncation. The presence of an output schema obviates the need to describe return values, so the description is complete for its complexity.

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

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

The schema itself has no descriptions (0% coverage), but the description's Args block fully explains every parameter, including max_tokens overriding vault DB cap, safety_factor's default and effect, cap_behavior's two modalities, session_token as a cache key, and max_single_doc_tokens truncation 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 description states a specific verb ('Load ranked vault documents') and resource ('into conversation context') with a clear purpose ('token-budget enforcement'). It distinguishes from siblings like vault_inject_by_tag and vault_inject_summary by emphasizing ranking by FTS5 relevance and priority.

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 the tool (when ranked injection with token budgeting is needed) but does not explicitly mention alternatives or exclusion scenarios. It implies use cases but lacks direct 'use this instead of X' 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 description provides rich behavioral detail beyond annotations: ranking by priority weight and recency, greedy packing within token cap, effective cap = max_tokens * safety_factor, cap_behavior modes (best_effort vs strict), truncation via max_single_doc_tokens, and per-session caching via session_token. This goes well beyond the readOnly/idempotent annotations.

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

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

The description is well-structured: a concise one-sentence summary first, followed by a brief behavior explanation, then a clear Args block. It is slightly long but every part is necessary given the schema lacks descriptions. Efficient and front-loaded.

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

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

The description covers the core complexity: selection logic, ranking, packing, token caps, safety_factor, truncation, and session caching. However, it does not clarify what 'strict' cap_behavior actually does (does it fail or just inject nothing?) nor edge cases like empty results. Otherwise quite complete, with an output schema present to cover return values.

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 0%, but the description's Args block thoroughly explains all 7 parameters, including semantics (OR logic for tags, defaults for safety_factor and cap_behavior, purpose of session_token). This fully compensates for the absent schema descriptions.

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

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

The description uses a specific verb+resource+scope: 'Load all documents matching any of the given tags into the current conversation context.' This clearly distinguishes it from siblings like vault_search_by_tag (which searches but does not inject) and vault_inject (general injection without tag 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 implies its use case clearly: when you need to inject documents based on tags. It does not explicitly name alternatives or state exclusions, but the context is unambiguous given the 'by_tag' suffix and the clear action. It just misses explicit 'use when' 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the specific output content (categories, tags, priorities, notes) and the orientation purpose, but does not disclose additional behaviors like potential response size or vault resolution details. It adds moderate value beyond annotations.

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

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

The description is three sentences, front-loaded with the main action, and each sentence provides meaningful information without redundancy. It is appropriately concise for the tool's simplicity.

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

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

Despite the low schema coverage, the description covers the tool's purpose, the content of its output, and the appropriate usage context. With an output schema present and strong annotations, the description does not need to elaborate on return values or safety, making it complete for this straightforward tool.

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

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

Schema description coverage is 0% for the single 'vault' parameter, and the description does not compensate by explaining the expected format (e.g., name vs. ID). The only hint is 'a vault's contents,' which is insufficient for a parameter lacking schema-level documentation.

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

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

The description clearly states the tool generates a summary overview of a vault's contents and lists documents with categories, tags, priorities, and notes. However, it does not explicitly differentiate from sibling tools like vault_list_docs or vault_inject, relying instead on the phrase 'for conversation orientation' to imply its unique role.

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

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

The description provides explicit usage context by stating 'Useful at the start of a conversation,' which clearly indicates when to use it. It does not mention when not to use it or offer alternatives such as vault_list_docs or vault_inject_by_tag, but the usage guidance is 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 already declare idempotentHint and non-destructive, but the description adds important behavioral details: links are bidirectional, labelled with examples, and existing links are reported rather than duplicated. This goes beyond the structured annotations and clarifies side effects.

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

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

The description is concise and well-structured: the first sentence states the core action, followed by supporting details about bidirectionality and labels, a note on existing links, and a pointer to a related tool. No filler or redundancy.

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

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

With an output schema present, return values need not be described. The description covers the core functionality, edge case of existing links, and cross-vault scope, plus points to discovery via vault_find_related. It is sufficient for an agent to select and invoke the tool correctly, though a bit more detail on parameter formats 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?

The schema has 0% description coverage, but the description explains the purpose of source_doc and target_doc as 'two documents' and gives example labels for the label parameter. However, it doesn't specify value formats or whether the label is restricted, leaving some ambiguity. The description only partially compensates for the sparse 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 opens with 'Create a link between two documents across any vault,' which explicitly states the action and scope. It distinguishes itself from sibling tools like vault_unlink_doc (opposite) and vault_find_related (discovery) by noting the specific operation and pointing to the alternative.

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

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

It provides explicit guidance to use vault_find_related for discovering links, which helps the agent choose the right tool. It clearly implies this tool is for creating links and handles existing links gracefully, but does not explicitly mention when not to use it or contrast with vault_unlink_doc for removal.

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 idempotent (true) and non-destructive (false destructiveness), so the bar is lower. The description adds valuable behavioral context: it explains the association is organizational metadata and emphasizes the multiplicity of projects per vault. It does not conflict with annotations and gives a clear semantic model.

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

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

The description is three sentences, front-loaded with the core action, and every sentence earns its place. The first sentence states the function, the second explains the metadata purpose, and the third clarifies multiplicity. No fluff or repetition.

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

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

The tool is simple and has an output schema, so return values don't need explanation. Annotations cover idempotency and safety. However, the description leaves parameter semantics under-specified, which could lead to incorrect invocation (e.g., what 'vault' value to use). The metadata context and multiplicity note provide some completeness, but the param gap prevents a higher score.

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

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

Schema description coverage is 0%, so the description must compensate. It only restates the parameter names ('vault', 'Project name') without explaining value format, examples, or constraints. There is no guidance on how to specify a vault (ID, name?) or what constitutes a valid project_name. The description adds virtually no semantic value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Associate a Claude Project name with a vault.' It also distinguishes itself from sibling tools by emphasizing this is organizational metadata linking a project to a vault, not a document or session link. The term 'metadata' and the multiplicity note ('a vault can be linked to multiple projects') further clarify its unique role.

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 the tool: it records which Claude Projects use knowledge from a vault. However, it does not explicitly mention alternatives or exclusions, such as pointing out that document links should use vault_link_doc. The guidance is implied but not fully 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?

With no annotations provided, the description carries full burden. It discloses that manual links are accessible on all tiers, that both products must be installed, and that doc must not be in an opt-out vault. However, it does not describe whether the operation is reversible, effects on existing links, or permission requirements. The return dict description is behavioral but incomplete.

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

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

Description is well-structured and efficient, using a short intro, a concise bullet-like 'Args' list, and a clear 'Returns' section. It avoids fluff. Only minor redundancy: 'Returns dict with ok -- bool' could be more concise, but it's still tight.

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

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

Given the tool's moderate complexity (3 params, no output schema, no annotations), the description covers most key aspects: prerequisites, tier availability, return shape. However, it lacks error behavior (e.g., what 'generic' failure implies), and doesn't clarify the 'manual' link lifecycle (e.g., how to unlink, if replaceable). It's 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 coverage is 0%, so description must compensate. It lists all three parameters (session_id, doc_id, vault_id) with brief explanatory phrases (e.g., 'LoreConvo session UUID', 'LoreDocs document ID', 'LoreDocs vault containing the document'). This adds essential meaning beyond bare parameter names, though it doesn't provide format validation or relationships between params.

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

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

Clearly states the action: 'Create a manual cross-product link from a LoreConvo session to a LoreDocs doc.' The verb is specific, the resources are named, and it distinguishes itself from sibling link tools like vault_link_doc (which likely links docs to docs) and vault_link_project. Also mentions manual vs automatic, which differentiates further.

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

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

Gives clear when-to-use context: manual link creation, available on all tiers, requires both products installed, and doc must not be in an opt-out vault. Does not explicitly name alternatives, but the context implies when this is appropriate vs other link operations. Lacks explicit exclusions for when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds value by disclosing that the tool lists all vaults and returns summary statistics, which is meaningful behavioral context beyond the annotations.

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

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

Two sentences, front-loaded with the action and purpose, zero filler. 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 simple read-only list tool with robust annotations and an output schema, the description is nearly complete. The only minor gap is that 'all knowledge vaults' could be misleading given the include_archived parameter defaults to false, but this is discoverable from the schema.

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

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

Schema description coverage is 0% and the description does not explain either parameter. The input schema only provides names, defaults, and an enum for response_format; agents must infer that include_archived controls whether archived vaults are included in 'all' and that response_format changes the output serialization.

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 knowledge vaults') and adds the key detail of summary stats (document count, total size, last modified). This clearly distinguishes it from sibling tools like vault_list_docs, which list documents rather than vaults.

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 see what vaults exist and find the one you need,' giving clear context for when to invoke it. It doesn't name alternatives or exclusions, but the intended use case is obvious.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds only functional details already present in the schema (sorting/filtering) and does not disclose additional behaviors like default sort order, pagination behavior, or limitations. It provides no extra transparency beyond the annotations.

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

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

The description is two sentences long, with no filler or repetition. It front-loads the core purpose and then lists the key options 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?

An output schema exists, so return values are covered. The description covers the main purpose and filtering/sorting options, but it omits details like default sort order, pagination behavior, and response format selection. For a tool with 8 parameters, this is adequate but not complete for advanced usage.

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 0%, so the description carries a heavier burden. It does mention sortable fields (name, date, size, category) and filterable properties (category, tag), which helps map to the sort_by, category, and tag parameters. However, it does not explain the allowed enum values, defaults, limit/offset pagination, or response_format semantics, leaving some parameters under-explained.

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

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

The description uses the specific verb 'list' and the resource 'documents in a vault', clearly distinguishing it from sibling search tools. Mentioning sorting and filtering options further clarifies its scope.

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

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

The description clearly implies the tool is for listing documents with sorting/filtering options, which is sufficient context for most use cases. However, it does not explicitly state when to prefer this over alternatives like vault_search or vault_get_doc, so it misses the highest tier of 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 only state readOnlyHint=false and destructiveHint=false. The description adds critical behavior—the document is removed from the source vault—which is not directly implied by the annotations. This clarifies the mutation effect, though it omits details about permissions or failure scenarios.

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

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

The description is exceptionally concise: two short sentences that front-load the action and resource, with a second sentence adding the critical removal detail. No fluff or redundancy.

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

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

For a simple tool with two parameters and an output schema, the description covers the core behavior adequately. However, it does not address edge cases like moving to the same vault, permission requirements, or how to handle non-existent documents, leaving minor gaps.

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

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

The schema has no descriptions for the two parameters, and the tool description does not elaborate on doc_id or target_vault beyond their names. The phrase 'different vault' hints at target_vault's role, but no format, identifier type, or usage details are provided, leaving the agent to infer.

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 ('a document'), and the destination ('a different vault'). It also explicitly notes that it removes the document from the source vault, which distinguishes it from vault_copy_doc and other sibling tools.

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

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

The removal clause implies a key difference from copying, but the description does not explicitly name alternatives or provide exclusion criteria. It lacks guidance such as 'use instead of copy when you want to remove the source' or 'do not use for archiving.'

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 include idempotentHint=true, and the description adds specific behavioral detail: if a vault is already linked to the directory path, it returns it; otherwise it creates a new vault and records workspace_path for future calls. This goes beyond the generic idempotency annotation. 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 well-structured with three short paragraphs, each serving a purpose: core action, behavior, and rationale. It is not overly verbose, though the third paragraph could be trimmed. Every sentence adds value, making it concise for the information conveyed.

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 core workflow, idempotent behavior, and use case, which is sufficient for the tool's complexity. An output schema exists, so the description need not explain return values. The description is complete enough for an agent to select and invoke the tool correctly, though it lacks edge-case handling details (e.g., invalid paths).

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 0%, so the description must compensate. It explains workspace_path's role implicitly ('vault scoped to a workspace directory', 'records the workspace_path'), but the optional 'description' parameter is not mentioned at all. The description adds meaning for the key parameter but does not fully cover the second parameter.

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

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

The description clearly states the tool's purpose: 'Open (or create) a vault scoped to a workspace directory.' This is specific, with a clear verb (open/create), resource (vault), and scope (workspace directory). It also distinguishes from siblings by contrasting with named vaults, noting that named vaults remain available for explicit management.

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: for workspace-scoped vaults with lower friction, vs. named vaults via vault_create. It explicitly states 'This mirrors how MemClaw scopes memory to workspaces -- lower friction than naming vaults manually' and mentions named vaults remain available. However, it does not explicitly say 'use this instead of vault_create', so it's clear but slightly indirect.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds crucial behavioral context: priority ordering (authoritative first, then recency), token budget calculation (max_tokens * safety_factor), cap_behavior semantics ('best_effort' vs 'strict'), per-session caching via session_token, and per-document truncation. This goes beyond annotations and gives the agent a realistic model of tool behavior.

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

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

The description is well-structured: a one-sentence summary, a comparison to vault_inject, a usage note, and a compact Args block. Every sentence provides necessary information, and the parameter list is essential given the lack of schema descriptions. It is appropriately sized and front-loaded.

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

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

For a tool with six parameters, no schema descriptions, and a complex token-budget behavior, the description covers all essential aspects: purpose, ordering, usage timing, parameter semantics, and edge-case behavior (cap_behavior). An output schema exists, so return-value details are not needed. The description is sufficient for correct invocation and selection.

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

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

Schema descriptions are completely absent (0% coverage), so the description carries the full burden. It compensates thoroughly by defining each parameter: vault_name, max_tokens, cap_behavior, session_token, max_single_doc_tokens, and safety_factor (including default). This adds meaning far beyond the bare schema types.

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

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

States a specific verb and resource: 'Pre-load all vault documents into the current session by priority order.' It clearly distinguishes from vault_inject by specifying it's equivalent to vault_inject with no query and by noting the ordering logic. This makes it easy to differentiate from siblings like vault_inject and vault_search.

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

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

Explicitly says 'Use at session start to orient yourself on all knowledge available in a vault.' It also frames the tool in relation to vault_inject, giving an alternative reference point. This provides clear when-to-use guidance and a comparison to a sibling 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 establish that this is a write operation and idempotent, but the description adds useful context: it explains the automatic sync behavior for new documents, the one-time rebuild requirement for existing ones, and the Pro-only restriction. It does not mention operational details like confirmation or runtime, but the annotation coverage lowers the bar.

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

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

The description is front-loaded with the main purpose and is concise, using only three short sentences. Each sentence earns its place by explaining the what, when, and background context without fluff.

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 thoroughly covers the purpose and timing of the rebuild, and with an output schema present return values are not needed. However, it omits any guidance on the 'confirm' parameter, which defaults to false and could cause an invocation to be a no-op or fail if not set. This is a crucial gap for an otherwise simple tool.

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

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

The only parameter 'confirm' is not mentioned in the description, and the schema has no description for it. With schema coverage at 0%, the description should compensate, but it leaves the agent without guidance on whether confirm must be true for the rebuild to proceed.

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 verb ('Rebuild') and resource ('LanceDB semantic search index from all stored documents'), which fully defines the tool's purpose. It is distinct from sibling search and document management tools, and the 'Pro only' note adds a unique 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?

The description gives explicit when-to-use scenarios: after installing Pro deps or after restoring from backup. It also provides a when-not-to-use cue by noting that new documents are auto-synced, so the rebuild is only needed for existing documents.

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 the operation is non-destructive (destructiveHint: false) and idempotent (idempotentHint: true). The description adds valuable context that the document is 'hidden but can be recovered', which goes beyond the annotations. No contradiction found.

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 extremely concise, consisting of two sentences with no redundant information. The key action is front-loaded, and the alternative tool is mentioned 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 single-parameter soft-delete tool with an output schema, the description covers the core behavior and key alternative. It could mention that the document remains recoverable via a restore tool, but the provided context 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?

The schema has zero description coverage for the only parameter, 'doc_id', and the description does not explain it. While the parameter name is self-explanatory, the description fails to compensate for the missing schema documentation, leaving the agent to infer the parameter's meaning.

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 ('soft-delete a document') and resource, and explicitly distinguishes from the sibling 'vault_delete' for permanent deletion. It resolves the ambiguity of the title 'Remove Document' by specifying the non-destructive nature.

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 names 'vault_delete' as the alternative for permanent deletion, providing a clear when-not-to-use case. However, it does not mention when to use 'vault_doc_restore' for recovery, which would be a helpful additional guideline.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses FTS5 syntax, the semantic search behavior, the fallback to FTS5 if the semantic index is missing, and the Pro/pip install requirement. This is rich, useful behavioral context that helps the agent anticipate outcomes.

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

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

The description is well-structured: a one-sentence intro, a bullet list of FTS5 syntax examples, and a compact paragraph on semantic mode. Every sentence adds value, 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?

The output schema exists, so return format is covered. The description thoroughly explains modes, syntax, prerequisites, and fallback behavior. Minor gaps: it does not explain the vault parameter's filtering role or response_format, but these are inferable from the schema and the tool's purpose.

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

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

With 0% schema description coverage, the description compensates for the most important parameters: query (supports FTS5 syntax) and semantic (Pro-only, hybrid search, fallback). However, it does not add meaning for limit, offset, vault, or response_format, relying on schema titles and defaults. Partial compensation warrants a 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 'Full-text or semantic search across document contents,' clearly stating a specific verb (search) on a specific resource (document contents). It distinguishes two search modes (FTS5 vs semantic) and differentiates from sibling tools like vault_search_by_tag and vault_get_doc.

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 each mode: default FTS5 for keyword search, semantic for meaning-based search (with Pro requirement and fallback note). It mentions a prerequisite (run vault_rebuild_index first) but does not explicitly reference alternatives like vault_search_by_tag or state when this tool 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds the vault scoping behavior ('one vault or all vaults'), which is useful. However, it does not disclose details like return format, sorting, or pagination, so the added value is moderate.

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 immediately conveys the action, resource, and scope with no filler. Front-loaded and concise.

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

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

For a simple search tool, the description covers the main purpose and scoping. An output schema exists, so return values needn't be explained. It lacks explicit guidance on when to prefer this over vault_search, but given the simple nature, it is nearly 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 0%, so the description must compensate. It explains 'tag' and 'vault' semantics ('with a specific tag' and 'one vault or all vaults'), but does not explain the 'response_format' parameter. Since tag and vault are the primary parameters, this is adequate but not complete.

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 finds all documents with a specific tag, using the verb 'find' and resource 'documents'. It further specifies scope ('across one vault or all vaults'), which distinguishes it from general search (vault_search) and tag-based injection 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 usage: use this when you need to find documents by tag. It mentions vault scoping but does not explicitly compare with alternatives (e.g., vault_search for full-text search) or state when not to use it. There is no explicit when/when-not guidance, but the core use case is 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 already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, covering the primary safety profile. The description adds semantic context for two enum values but does not describe behavior such as whether the existing priority is overwritten or any side effects. With annotations handling the key behavioral traits, a score of 3 is appropriate.

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

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

The description is concise: two short sentences that state the purpose and then clarify the two most ambiguous enum values. Every sentence earns its place, with no filler or redundancy.

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

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

For a simple setter with two parameters and an existing output schema, the description adequately conveys the tool's action and clarifies important terms. It could mention that setting priority replaces the existing value, but given the low complexity and that the output schema is available, the description is reasonably complete.

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

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

Schema description coverage is 0%, so the description must compensate. It defines 'authoritative' and 'outdated' but leaves 'normal', 'draft', and doc_id undocumented. This partial compensation is insufficient for fully understanding all parameters, though the undefined values are somewhat self-explanatory.

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 'Mark' and identifies the resource as 'a document's priority/status', which clearly distinguishes this tool from siblings like tagging or categorization. It lists the four possible values, making the scope explicit. The slight ambiguity of 'priority/status' is resolved by the enumerated values.

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 setting document priority/status and clarifies the meaning of 'authoritative' and 'outdated', which helps decide when this tool is appropriate. However, it does not explicitly state when to use it over alternatives, nor does it provide any exclusions or 'use instead' references.

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?

Goes beyond annotations by disclosing a key side effect: 'Reverting to tier='free' re-enables limits (but does not delete any existing data that exceeds the limits -- it only blocks new writes)'. This is important behavioral context. Annotations already cover idempotency and non-destructiveness, and the description adds the specific limit behavior and environment requirement.

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 paragraphs with active, front-loaded language. The first sentence clearly states the core purpose, and each subsequent sentence adds necessary context (purchase process, environment variable, side effects). It is slightly longer than strictly necessary but every sentence earns its place.

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

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

Given the tool's complexity (license activation, environment prerequisites, and side effects), the description covers the workflow, prerequisites, and behavioral consequences. An output schema exists, so return values do not need to be explained. The only minor gap is the absence of explicit error conditions, but this is not critical for a setting tool.

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

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

The only parameter 'tier' has 0% schema description coverage, but the description explicitly states the two valid values ('pro' and 'free') and what each does ('Pro tier removes all vault, document, storage, and version limits'; 'free re-enables limits'). This effectively compensates for the missing schema documentation, though it does not formally enumerate the values as an enum.

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

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

Description opens with 'Activate a tier (free or pro) for LoreDocs', which clearly states the verb (activate), resource (license tier), and scope. It distinguishes itself from sibling tools like vault_tier_status and get_license_tier, which are read-only status/retrieval tools, whereas this tool changes the tier.

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

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

Provides explicit prerequisites ('After purchasing a Pro license, set LOREDOCS_PRO=<your-license-key> in your environment and restart the server') and a step-by-step usage path ('then call this tool with tier='pro' to persist'). It explains when to use it for upgrading and downgrading, though it does not explicitly state when not to use it (e.g., before license purchase), but that is implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds behavioral context beyond those annotations by explaining what 'needs attention' means (no notes, no tags, no links) and that vault scoping is optional. This helps the agent understand the tool's selection logic without contradicting the annotations.

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

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

The description is front-loaded with a one-sentence summary, followed by two concise sentences that elaborate on criteria and usage. It contains no redundant or extraneous information, making it highly efficient and well-structured.

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

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

Given the tool's simplicity (two optional params, output schema present, annotations provided), the description is nearly complete. It covers purpose, usage, and vault scoping. The 'limit' behavior is not described, but the default in the schema and the output schema itself reduce the need for further detail. Overall, it is a well-rounded and useful description.

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 0%, so the description must compensate. It explains the 'vault' parameter ('Optionally scope to a single vault') but does not explain 'limit', which is only defined by its default value in the schema. While 'limit' is reasonably self-explanatory, the description does not fully cover parameter 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 description uses a specific verb ('Get suggestions') and resource ('documents'), and clearly defines the criteria (undocumented, unorganized, isolated) that distinguish it from sibling tools like vault_search. It immediately conveys what the tool does and what makes it unique.

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

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

The description states when to use the tool: 'to guide housekeeping work or to discover documents that haven't been connected to the broader graph.' This provides clear context for use, though it does not explicitly name alternative tools or exclusion criteria. It is specific enough to guide selection among 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 idempotentHint=true and destructiveHint=false, so the description adds value by disclosing case-sensitivity and automatic duplicate removal. These details go beyond the structured annotations and help predict tool behavior.

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

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

The description is three short sentences that immediately state the purpose, capability, and key behavioral constraints. No filler or redundant information; 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 simple 3-parameter mutation tool with an output schema, the description covers the essential actions and two important behavioral rules. It lacks edge cases like empty arrays, but these are not critical for such a straightforward 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 0%, but the parameter names (doc_id, add_tags, remove_tags) are self-explanatory. The description's mention of adding/removing tags partially maps to these params, but it doesn't explicitly explain array nature or nullability, relying on the schema to carry that weight.

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 'Add or remove tags on a document' with a specific verb and resource, distinguishing it from siblings like vault_bulk_tag (bulk operation) and vault_search_by_tag (search). It precisely captures the tool's core 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 provides clear context by noting that tags can be added and removed in a single operation, which tells the user about combined capability. However, it does not explicitly contrast with alternatives or mention when not to use this tool, keeping it one step below full guidance.

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

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

Annotations already indicate a safe read-only operation (readOnlyHint=true, destructiveHint=false, idempotentHint=true). The description adds concrete behavioral details about what is reported (vault count, storage usage, percentages against Free tier limits), which goes beyond the annotations without contradicting them.

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

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

The description is very concise: a two-sentence opening that states the core purpose, followed by a brief usage note. Every sentence adds value, and the most important information is front-loaded.

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

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

This is a simple read-only tool with one optional parameter, an output schema, and clear annotations. The description fully covers what the tool does, what it reports, and when it is useful. There are no significant gaps given the tool's simplicity and the presence of the output schema.

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

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

The schema has only one parameter, response_format, with an enum (markdown/json) and a default value, making it self-explanatory. The description does not explain this parameter, but the schema fully covers its semantics. Given low schema description coverage (0%), a baseline of 3 is appropriate because the parameter is inherently clear.

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 with a specific verb ('Show') and resource ('current tier and usage vs. limits'). It distinguishes itself from siblings like vault_set_tier (which sets a tier) and get_license_tier (which likely retrieves license details) by focusing on usage vs. limits.

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: 'Useful before hitting a limit to know how close you are, or to confirm Pro tier is active after upgrading.' It explains when to use the tool but does not explicitly mention when not to use it or name alternative tools.

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

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

Annotations already indicate destructive and idempotent behavior, but the description adds valuable context: the operation is bidirectional ('both directions') and gracefully handles non-existent links ('reports that cleanly'). This goes beyond the annotation flags and gives the agent a better mental model.

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, zero fluff. The main action and a key edge case are stated upfront. Every word earns its place.

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

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

For a tool with two simple string parameters and an output schema (not shown), the description covers the essential behavior: what is removed, the bidirectional scope, and the no-op case. The main gap is parameter format, but that is more of a parameter semantics issue. Overall, it is sufficiently complete for the tool's simplicity.

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

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

Schema descriptions cover 0% of parameters, so the description must compensate. It only refers to 'two documents' without explaining what format source_doc and target_doc should take (e.g., IDs, paths, names). The parameter names provide some clue, but the description adds little beyond that.

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 ('Remove') and resource ('link between two documents'), and clarifies 'both directions.' This clearly distinguishes it from sibling tools like vault_link_doc (which creates links) and vault_remove_doc (which removes documents entirely).

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