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

Annotations already provide idempotentHint=true and destructiveHint=false, covering safety aspects. The description adds useful context about what gets created (a handoff note with specific content sections) and mentions the return value (path to the note), but doesn't disclose other behavioral traits like file format, location constraints, or overwrite 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 with a clear purpose statement followed by parameter documentation and return information. It's appropriately sized for a 4-parameter tool, though the 'Args' section could be more integrated with the narrative flow rather than appearing as a separate documentation block.

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, 100% schema coverage, and helpful annotations, the description provides adequate context. It explains the tool's purpose, parameters, and return value, though without an output schema, it could benefit from more detail about the returned path format or note structure. The description covers the essential information needed to use the tool effectively.

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 100% schema description coverage, the input schema already documents all parameters thoroughly. The description's 'Args' section essentially repeats what's in the schema without adding significant semantic value beyond restating the parameter purposes. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the specific action ('Create a session handoff note') and purpose ('so the next session picks up where this one left off'), distinguishing it from sibling tools like save_note or save_decision by focusing on session continuity. It explicitly mentions what content to include (what was worked on, pending tasks, blockers).

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 ('so the next session picks up where this one left off'), but doesn't explicitly state when not to use it or name specific alternatives among the sibling tools. It implies usage at session boundaries for continuity purposes.

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

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

Annotations provide readOnlyHint=true, indicating this is a safe read operation. The description adds value by specifying the tool's purpose (finding similar notes) and use cases, but does not disclose additional behavioral traits like how similarity is calculated, potential performance considerations, or any rate limits. With annotations covering safety, the description provides some context but lacks deeper behavioral insights.

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 appropriately sized and front-loaded, starting with the core purpose and use cases, followed by parameter details and return information. Every sentence earns its place, but the Args section could be integrated more seamlessly to avoid redundancy with the schema. Overall, it is efficient with minimal 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?

Given the tool's moderate complexity (2 parameters, read-only operation), the description is complete enough for an agent to understand its purpose and usage. It covers what the tool does, when to use it, and basic parameter info, though it lacks output details (no output schema provided) and deeper behavioral context. With annotations indicating safety, it provides a solid foundation but could benefit from more on return values or limitations.

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

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

Schema description coverage is 100%, with both parameters (path and top_k) fully described in the schema. The description repeats this information in the Args section without adding extra meaning, such as format details for 'path' or implications of 'top_k' on results. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description does not compensate with additional semantic insights.

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 ('Find notes that cover similar topics to a given note') and resource ('notes'), distinguishing it from siblings like search_notes or search_across_vaults by focusing on similarity rather than keyword-based searching. It provides concrete use cases ('discover related context, find notes that might conflict, or build a broader picture of a topic'), making the purpose explicit and differentiated.

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 includes clear context for when to use this tool ('to discover related context, find notes that might conflict, or build a broader picture of a topic'), which implicitly distinguishes it from general search tools. However, it does not explicitly state when not to use it or name specific alternatives among the siblings, such as search_notes for keyword-based queries, leaving some room for improvement.

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

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

The annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds valuable context about path relativity ('Paths are relative to the vault root') and clarifies that it returns 'full markdown text content', which goes beyond the safety information provided by 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 efficiently structured with three focused sentences: purpose statement, usage guidance, and return value clarification. Each sentence serves a distinct purpose with zero wasted words, and key information is front-loaded.

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

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

For a simple read operation with one parameter, 100% schema coverage, and readOnlyHint annotation, the description provides complete context. It explains the tool's purpose, when to use it, path format, and return content, which is sufficient given the tool's low complexity and good annotation coverage.

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

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

Schema description coverage is 100%, with the schema already documenting the single 'path' parameter as 'Relative path from vault root'. The description repeats this same information without adding additional semantic context or format details beyond what the schema provides, meeting the baseline for high coverage.

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 ('Read the full content') and resource ('of a note'), distinguishing it from siblings like search_notes (which finds notes) or save_note (which creates/updates notes). It explicitly defines the scope as reading complete text content.

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 guidance on when to use this tool ('after search_notes returns a relevant result and you need the complete text'), naming the specific sibling tool (search_notes) as the precursor. It clearly indicates the workflow relationship between 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 indicate readOnlyHint=true, and the description aligns by describing a retrieval operation ('Get orientation context'). It adds valuable context beyond annotations by specifying what data is returned (pinned notes, handoff, decisions) and its purpose for session continuity, though it lacks details on rate limits or authentication needs.

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

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

The description is front-loaded with the core purpose in the first sentence and uses two concise sentences total. Every sentence earns its place by clarifying the tool's function and output without redundancy, 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 low complexity (0 parameters, read-only) and lack of output schema, the description is mostly complete. It explains what the tool does and returns, but could improve by detailing the output structure or error handling, though annotations cover safety aspects adequately.

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 parameters with 100% coverage, so no parameter documentation is needed. The description compensates by explaining the tool's output ('Returns structured session context') and content, adding meaning beyond the schema, though it could briefly mention the lack of inputs.

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 specific verbs ('Get orientation context') and resources ('pinned notes, the latest handoff, and recent decisions'). It distinguishes itself from siblings by focusing on session continuity rather than note creation, searching, or memory management, making it easy to understand 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 usage ('for a new session' and 'pick up where the last session left off'), implying it should be used at session start. However, it does not explicitly state when not to use it or name alternatives among siblings, such as 'recent_activity' or 'get_note', leaving some ambiguity in tool selection.

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

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

The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds valuable context beyond this by specifying what information is returned (note count, chunk count, etc.) and providing troubleshooting guidance, though it doesn't mention rate limits or performance characteristics. No contradiction with annotations exists.

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 and front-loaded with the core purpose, followed by details and troubleshooting. It could be slightly more concise by merging some sentences, but every sentence adds value (e.g., return details and alternative actions).

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 (0 parameters, read-only), no output schema, and rich annotations, the description is mostly complete. It explains the purpose, usage, returns, and troubleshooting, though it could briefly mention the response format or any limitations for full 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?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately notes there are no inputs by not discussing parameters, which is sufficient given the schema fully covers this.

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 specific verbs ('Check', 'verify', 'report') and resources ('health and size of the note index'), distinguishing it from siblings like reindex (which modifies) or mem_health (which checks memory). It explicitly identifies what it does rather than restating the name.

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

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

The description provides explicit guidance on when to use this tool ('to verify the index is up to date or to report stats to the user') and when to use alternatives ('If the user reports problems, suggest they run `same doctor` for diagnostics. For bugs, direct them to...'), clearly differentiating from other tools like reindex or mem_health.

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

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

The description adds valuable behavioral context beyond the readOnlyHint annotation. It explains what the tool generates ('a concise briefing generated from vault contents'), mentions it's 'experimental' (which implies potential instability), and describes the content structure ('recent activity, open decisions, and key context'). While it doesn't cover rate limits or authentication needs, it provides useful operational context that annotations don't capture.

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 and appropriately sized. It front-loads the core purpose, provides usage guidance, documents the parameter, and notes the experimental nature. While efficient, the parameter documentation duplicates schema information, slightly reducing conciseness 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?

Given the tool's moderate complexity (single parameter, read-only operation), the description provides good contextual completeness. It explains the tool's purpose, when to use it, what it returns, and its experimental status. The main gap is the lack of output schema, but the description adequately describes the return value ('a concise briefing generated from vault contents').

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 100% schema description coverage, the input schema already fully documents the single parameter 'max_items'. The description repeats the parameter information verbatim ('Maximum items per section (default 5)'), adding no additional semantic value beyond what's in the schema. This meets the baseline expectation when schema coverage is 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's purpose with specific verbs ('Get an orientation briefing') and resources ('what matters right now', 'recent activity, open decisions, and key context'). It distinguishes itself from siblings like 'recent_activity' by providing a comprehensive briefing rather than just activity data, and from 'get_session_context' by focusing on project state orientation rather than session-specific context.

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 when to use this tool: 'Use this at the start of a session to understand current project state.' This provides clear context for usage and distinguishes it from tools like 'search_notes' or 'get_note' that serve different purposes. The guidance is specific and actionable.

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

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

The description adds valuable behavioral context beyond the destructiveHint annotation. While the annotation indicates destructive operations, the description clarifies that it 'creates new knowledge files without modifying originals' and mentions the experimental nature of the tool. It also describes what the tool does (merges duplicates, resolves contradictions, extracts key facts) which isn't covered by 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 with purpose statement, usage guidance, parameter details, and return information. It's appropriately sized for a tool with this complexity. The Args section could be more concise since it duplicates schema information, but overall the description is front-loaded with essential information.

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

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

Given the tool's complexity (consolidation operations), the presence of a destructiveHint annotation, and no output schema, the description provides good context. It explains what the tool does, when to use it, parameter details, and what it returns. The experimental flag is helpful context. It could benefit from more detail about the consolidation algorithm or error cases.

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 100% schema description coverage, the input schema already fully documents both parameters. The description repeats the parameter information in the Args section but doesn't add significant semantic value beyond what's in the schema. The baseline score of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('consolidate', 'merges', 'resolves', 'extracts', 'creates') and resources ('related notes in the vault'). It distinguishes from siblings like 'find_similar_notes' by focusing on consolidation rather than just finding similar notes, and from 'save_note' by creating new files without modifying originals.

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 the vault has many similar or overlapping notes'), but does not explicitly state when not to use it or name specific alternatives among the sibling tools. It implies usage based on vault state rather than providing explicit exclusions.

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

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

Annotations indicate idempotent and non-destructive behavior, which the description aligns with by noting suppression rather than deletion. The description adds valuable context beyond annotations: it clarifies that suppressed notes won't appear in normal search, require explicit requests to view, and the action is not easily reversible—none of which are covered by 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 with a clear purpose statement, usage guidelines, parameter summary, and return note. It's front-loaded with key information, though the 'Args' section slightly duplicates schema content, and the experimental tag could be integrated more seamlessly.

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 annotations and no output schema, the description is largely complete: it explains the action, behavioral implications, and irreversibility. However, it lacks details on error conditions or confirmation format, which would enhance completeness given the tool's experimental nature.

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 100% schema description coverage, the schema already documents both parameters fully. The description adds minimal value by restating parameter purposes in the 'Args' section, but it doesn't provide additional semantic context like format examples or constraints beyond what's in the schema.

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

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

The description clearly states the specific action ('suppress a memory') and resource ('note'), distinguishing it from siblings like 'delete' operations. It explicitly contrasts suppression with deletion and explains the effect on search visibility, 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?

It provides explicit guidance on when to use this tool ('for outdated, incorrect, or irrelevant memories') and when not to use it ('not easily reversible: there is no mem_restore tool'). This clearly differentiates it from potential alternatives like deletion 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 indicate readOnlyHint=true, and the description aligns with this by describing a check/return operation without implying mutation. The description adds valuable context beyond annotations: it discloses that the tool returns actionable recommendations and is experimental, which helps the agent understand potential reliability or behavior nuances not covered by 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 front-loaded with the core purpose and output, followed by usage guidance and an experimental note. It is efficient with two sentences, but the second sentence slightly repeats information about returns, making it not perfectly concise. Overall, it is well-structured with minimal 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?

Given the tool's complexity (health assessment with recommendations), annotations cover safety (read-only), and there is no output schema, the description does a good job explaining what the tool returns (score, metrics, recommendations) and its experimental nature. However, it could provide more detail on what 'key metrics' entail or error conditions, leaving minor gaps for full 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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, focusing instead on the tool's purpose and output. A baseline of 4 is applied since no parameters exist, and the description adds value by explaining what the tool does without redundant parameter info.

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 ('Check') and resource ('memory vault'), and distinguishes it from siblings by focusing on health assessment rather than creation, retrieval, or modification operations. It specifies the output (health score, recommendations) which differentiates it from tools like 'index_stats' or 'recent_activity'.

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

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

The description provides clear context for when to use this tool ('to determine if the vault needs consolidation, reindexing, or cleanup'), which implicitly suggests alternatives like 'mem_consolidate' or 'reindex' for remediation. However, it does not explicitly state when NOT to use it or name specific alternative tools, keeping it at a 4.

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

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

The annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds useful context about the tool's purpose (recent modifications and session orientation) and mentions the return format ('list of recently modified notes with titles and paths'), which provides behavioral insight beyond the annotations. However, it lacks details on ordering, pagination, or error handling.

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 and front-loaded with the core purpose, followed by brief, relevant details. Each sentence earns its place by clarifying usage, parameters, and returns without redundancy or unnecessary elaboration, making it efficient and easy to parse.

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

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

Given the tool's simplicity (one parameter, read-only, no output schema), the description is largely complete, covering purpose, usage, parameters, and return format. However, it could enhance completeness by specifying the order of results (e.g., most recent first) or handling of ties, which are minor gaps for a 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?

The input schema has 100% description coverage, fully documenting the 'limit' parameter with its type, default, and max. The description repeats this information in the Args section but does not add significant semantic value beyond what the schema provides, such as explaining why the limit matters or how it affects performance.

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 ('Get recently modified notes') and resource ('notes'), distinguishing it from siblings like search_notes or get_note by focusing on recency rather than content or single retrieval. It provides explicit context ('to see what's changed recently or to orient yourself at the start of a session') that reinforces its unique purpose.

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

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

The description offers clear guidance on when to use this tool ('to see what's changed recently or to orient yourself at the start of a session'), which helps differentiate it from alternatives. However, it does not explicitly state when not to use it or name specific sibling tools as alternatives, such as search_notes for content-based queries.

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

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

The description adds valuable behavioral context beyond the destructiveHint annotation: it explains the default incremental behavior (only re-embeds changed files) and the effect of the force parameter. While annotations cover the destructive nature, the description clarifies what gets re-indexed and the performance implications, though it could mention potential downtime or resource usage.

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?

Well-structured with a clear purpose statement, usage guidelines, and parameter details in separate sections. It's front-loaded with key information, though the Args and Returns sections could be integrated more seamlessly. Every sentence adds value, but minor redundancy exists between the description and parameter details.

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 (destructive operation with one parameter) and lack of output schema, the description is mostly complete: it explains purpose, usage, behavior, and return value (indexing statistics). However, it doesn't detail the format of the statistics or error conditions, leaving some gaps for an agent to interpret results.

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

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

With 100% schema description coverage, the schema already documents the 'force' parameter fully. The description repeats the parameter's purpose in the Args section but adds minimal extra context beyond the schema, such as the default value (false). This meets the baseline for high schema coverage.

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 ('Re-scan and re-index all markdown notes') and distinguishes it from siblings by focusing on refreshing search indices rather than creating, retrieving, or searching notes. It specifies the resource type (markdown notes) and the verb (re-index).

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 states when to use this tool ('if the user has added or changed notes and search results seem stale') and provides an alternative behavior via the 'force' parameter. It differentiates from sibling tools like search_notes or index_stats by focusing on maintenance rather than querying or reporting.

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

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

Annotations provide idempotentHint=true and destructiveHint=false, indicating safe, repeatable operations. The description adds valuable context beyond annotations: it specifies that the action 'Appends to the decision log' (clarifying the append behavior) and mentions storage details ('stored in frontmatter'), which are not covered by annotations. No contradiction with annotations exists.

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 appropriately sized and front-loaded, with the core purpose in the first sentence. The Args and Returns sections are structured but slightly verbose in repeating schema info. Most sentences earn their place by adding context or examples, though some redundancy exists.

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, rich annotations (idempotent, non-destructive), and full schema coverage, the description is largely complete. It explains the tool's purpose, behavior, and parameters adequately. The lack of an output schema is mitigated by the 'Returns confirmation' note, though more detail on the confirmation format would enhance completeness.

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

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

Schema description coverage is 100%, with all parameters well-documented in the schema. The description repeats some parameter details (e.g., 'Short decision title') but adds minimal extra semantics, such as example values for 'title' and clarifying 'agent' usage. This meets the baseline for high schema coverage without significant enhancement.

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 ('Log') and resource ('project decision'), and distinguishes it from siblings by specifying it 'Appends to the decision log' for future sessions. This differentiates it from other save/note tools like save_note or save_kaizen by focusing on decision logging.

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 ('so future sessions can find it') but does not explicitly state when to use this tool versus alternatives like save_note or save_kaizen. It provides a general purpose but lacks explicit guidance on exclusions or comparisons with sibling tools.

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

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

The description adds valuable behavioral context beyond annotations: it explains SAME's provenance tracking ('if the source files change later, the item is automatically flagged as potentially addressed') and mentions the return value ('confirmation with the file path'). Annotations cover idempotency and non-destructiveness, but the description provides operational details that enhance understanding 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 well-structured and appropriately sized: a clear purpose statement followed by a bullet-point list of parameters. It's front-loaded with the core functionality, though the parameter section could be slightly more concise as it largely mirrors the schema.

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

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

For a tool with good annotations (idempotent, non-destructive) and full schema coverage, the description provides adequate context: purpose, usage scenario, behavioral details about provenance tracking, and return information. The lack of an output schema is compensated by mentioning the return value, though more detail on the confirmation format would be helpful.

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

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

Schema description coverage is 100%, so the input schema already documents all parameters thoroughly. The description's 'Args' section repeats this information without adding significant semantic value beyond what's in the schema, meeting the baseline for high coverage.

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: 'Log a friction point, bug, or improvement idea discovered during work.' It specifies the verb ('Log') and resource ('friction point, bug, or improvement idea'), and distinguishes it from siblings by mentioning SAME's provenance tracking feature, which no other tool in the list appears to offer.

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: 'discovered during work' for logging observations. It doesn't explicitly state when not to use it or name alternatives among siblings, but the context is sufficient to guide usage in typical scenarios without being misleading.

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

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

The annotations provide destructiveHint=true, but the description adds valuable behavioral context beyond this: it explains that notes are 'written to disk and indexed automatically,' mentions the 'SAME' system for stale detection when sources change, and describes how agent attribution is stored in frontmatter. This provides implementation details not captured in the single annotation.

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 efficiently structured: a clear purpose statement upfront, followed by key behavioral details, then a parameter summary. Every sentence adds value - none are redundant or verbose. The information is well-organized and appropriately sized for a tool with 5 parameters.

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

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

For a destructive write operation with no output schema, the description provides good context: it explains the write behavior, indexing, provenance tracking, and confirms what's returned. However, it doesn't detail error conditions or specific response format, leaving some gaps in completeness despite the strong annotations and schema coverage.

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 100% schema description coverage, the input schema already documents all parameters thoroughly. The description's 'Args' section largely repeats schema information, though it adds minor context about 'SAME' tracking for sources. This meets the baseline for high schema coverage without adding significant extra 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 specific action ('Create or update a markdown note in the vault'), identifies the resource ('note'), and distinguishes it from siblings like 'save_decision' or 'save_kaizen' by specifying it's for general markdown notes. It goes beyond restating the name by explaining the write-to-disk and indexing behavior.

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

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

The description provides clear context about when to use this tool (for creating/updating markdown notes with optional provenance tracking) and implicitly distinguishes it from read-only siblings like 'get_note' or search tools. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings like 'save_decision' for different note types.

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 declare readOnlyHint=true, which the description doesn't contradict. The description adds valuable behavioral context beyond annotations: it explains that unknown vault aliases are 'silently skipped' and mentions the CLI registration requirement. However, it doesn't describe rate limits, authentication needs, or other operational constraints.

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 efficiently structured with a clear purpose statement upfront, followed by usage guidance, prerequisites, and parameter details. Every sentence adds value with zero waste, and the information is well-organized for quick comprehension.

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

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

For a search tool with read-only annotations and no output schema, the description provides good context about cross-vault searching, prerequisites, and parameter behavior. It explains what the tool returns ('ranked results with titles, paths, snippets, and source vault name'), which compensates for the missing output schema. The main gap is lack of information about result format details or pagination.

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 100% schema description coverage, the schema already documents all parameters thoroughly. The description repeats some parameter information (query as 'Natural language search query', top_k defaults and limits, vaults behavior when omitted) but doesn't add significant meaning beyond what the schema provides. This meets the baseline for high schema coverage.

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 ('Search across multiple registered vaults at once') and resource ('vaults'), and explicitly distinguishes it from the sibling tool 'search_notes' by explaining when to use this tool instead. This provides excellent differentiation from alternatives.

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

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

The description provides explicit guidance on when to use this tool ('when you need context from other projects or want a cross-project view') versus the alternative ('search_notes'), and includes important prerequisites ('Vaults must be registered first via the CLI'). This gives clear context and 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 annotations already declare readOnlyHint=true, indicating this is a safe read operation. The description adds valuable behavioral context beyond annotations by specifying what content is searched (notes, decisions, context), the ranking of results, and the structure of returned data (titles, paths, text snippets), though it doesn't mention rate limits or authentication needs.

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

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

The description is efficiently structured with a clear purpose statement, usage guidelines, and parameter details in separate sections. Every sentence adds value, with no redundant information, and it's appropriately sized 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 moderate complexity, 100% schema coverage, and readOnlyHint annotation, the description is mostly complete. It explains what the tool searches for, when to use it, and what it returns, though without an output schema, it could benefit from more detail on the return format structure beyond 'ranked list of matching notes with titles, paths, and text snippets'.

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 100% schema description coverage, the input schema already fully documents both parameters. The description adds minimal value beyond the schema by providing example queries ('authentication approach', 'database schema decisions'), but doesn't significantly enhance parameter understanding beyond what's already in the structured data.

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 specific verbs ('search the user's knowledge base') and resources ('notes, decisions, and context'), distinguishing it from siblings like 'get_note' (single retrieval) and 'search_notes_filtered' (filtered search). It explicitly lists what types of content it searches for.

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

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

The description provides explicit guidance on when to use this tool ('when you need background on a topic, want to find prior decisions, or need to understand project architecture') and distinguishes it from alternatives by naming specific sibling tools in the context. It clearly defines the use case 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?

The annotations provide readOnlyHint=true, indicating it's a safe read operation. The description adds useful context about what the tool does (filtered search) and mentions it returns a 'filtered ranked list,' which gives some behavioral insight beyond annotations. However, it doesn't disclose additional traits like rate limits, authentication needs, or pagination 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 and appropriately sized. It front-loads the purpose and usage guidelines, then lists parameters with helpful examples, and ends with return information. While efficient, the parameter listing is somewhat redundant given the schema's completeness, slightly reducing conciseness.

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

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

Given the tool's complexity (8 parameters, search functionality) and lack of output schema, the description is reasonably complete. It explains the purpose, usage, parameters with examples, and return format. However, it could benefit from more detail on behavioral aspects like error handling or result structure to fully compensate for the missing 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 input schema has 100% description coverage, providing clear documentation for all 8 parameters. The description adds minimal value beyond the schema, listing parameter names with brief examples (e.g., 'engineering' for domain) but no additional syntax or format details. This meets the baseline for high schema coverage.

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: 'Search the user's knowledge base with metadata filters.' It specifies the verb ('search'), resource ('knowledge base'), and distinguishing feature ('with metadata filters'), which differentiates it from the sibling 'search_notes' tool that lacks this explicit filtering capability.

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 when to use this tool: 'Use this when you want to narrow results by domain...' It provides clear context for usage (narrowing results with metadata filters) and implicitly distinguishes it from alternatives like 'search_notes' (which presumably lacks filtering) and 'search_across_vaults' (which involves multiple vaults).

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