ainote

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

Annotations indicate non-read-only and non-destructive, and the description adds behavioral context: saves to cloud, persistent storage, auto-sync via local_path. No contradictions, and adds significant 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?

Well-structured with sections and a concise opening, but somewhat lengthy. Every sentence is informative, though slight trimming possible. Front-loaded effectively.

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?

Lacks information about return values or success indicators, which is important given no output schema. Also missing error conditions. Otherwise covers usage and behavioral context well.

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

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

Schema has 100% coverage, so baseline is 3. Description adds value by explaining local_path's role in sync, category subcategories, and memory_type semantics, going beyond 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 the tool saves documents to cloud for sync and storage. It lists specific use cases (memory files, configs, env notes, project notes) and categories, distinguishing it from sibling tools like get_dev_doc or delete_dev_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?

Provides explicit when-to-use scenarios (e.g., memory files, configs) and implies when not to use (e.g., not for actual secrets). Includes multi-device workflow and references sibling tool pull_dev_docs for sync, offering clear context.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's role is to add context. It correctly explains that the tool creates a new task and supports various fields, but does not disclose potential side effects (e.g., no duplicate checking, no permission requirements). However, for a creation tool, this level of transparency is adequate.

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

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

The description consists of two short sentences that front-load the purpose and then summarize capabilities. Every sentence adds value, and there is no fluff or repetition. It is 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 complexity (16 parameters, 1 required), the description adequately summarizes the types of fields supported. No output schema exists, but the description does not need to detail return values. It could mention that the created task's ID is returned, but this omission is minor. Overall, the description is complete enough for agent 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?

The schema covers all 16 parameters with descriptions (100% coverage). The description adds a high-level summary ('dates, times, location, notes, notifications') but does not provide additional meaning beyond what the schema already offers. Therefore, baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Create a new task') and the resource ('in AI Note'). It lists the supported features (dates, times, location, notes, notifications), distinguishing it from sibling tools like update_task and delete_task. The purpose is specific and unambiguous.

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

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

The description states what the tool does but does not provide explicit guidance on when to use it versus alternatives like update_task or delete_task. No prerequisites or scenarios are mentioned. While the purpose is clear, an agent would benefit from knowing, for example, that this tool is for newly created tasks only, not for modifying existing ones.

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?

Discloses the operation is a soft-delete and reversible, adding value beyond annotations which only indicate destructiveHint and idempotentHint. 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 concise sentences that front-load the main action and include necessary disambiguation detail without any redundant information.

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

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

Adequately covers core functionality and identifier options; no output schema exists, but return value is not critical for understanding the tool's purpose. Could mention that a document must exist.

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 covers all parameters with descriptions; the description adds context for the 'category' parameter by listing possible subcategories and explaining its purpose, improving usability.

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 performs a soft-delete on dev documents by title or UUID, and distinguishes it from sibling tools like create_dev_doc, get_dev_doc, update_dev_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?

Explicitly advises to pass 'category' when multiple docs share the same title across subcategories, providing clear usage context. Could explicitly mention when not to use, but overall helpful.

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 (destructiveHint=true), description adds soft-delete behavior, 30-day recovery window, daily cleanup timing, and ownership/404 details. Provides substantial extra 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?

Two concise sentences that front-load the action and follow with key behavioral details. 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?

Describes 404 case but not success behavior (e.g., what is returned on successful soft-delete). Lacks completeness for a simple tool with no 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?

With 100% schema coverage and only one parameter (id), the description adds no new meaning beyond the schema's 'Task ID to delete'. Baseline score is appropriate.

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

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

Description clearly states soft-delete a task by ID, which is specific and distinguishes from sibling delete tools for different resources (e.g., delete_dev_doc). Verb and resource are 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?

Mentions that deletion is soft (reversible) and returns 404 if task doesn't exist or not owned, but does not explicitly compare to alternatives or provide a when-to-use/not-to-use guide.

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 that the tool returns 'full content', which is useful beyond annotations. However, annotations already declare readOnlyHint=true and idempotentHint=true, so the behavioral profile is mostly covered. No contradictions. Some extra detail on what full content entails could improve 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 extremely concise with two sentences, covering the key action and result. No unnecessary 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?

Given no output schema, the description adequately states it returns 'full content'. For a simple retrieval tool, this is sufficient. However, a brief note on the structure or size of the content could 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 coverage is 100%, so baseline is 3. The description only says 'by title or id', which repeats schema fields but does not add new semantics or usage context for parameters like category or include_versions.

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

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

The description clearly states the verb 'Get', the resource 'a single dev document', and the method 'by title or id'. It also specifies it returns full content, making the purpose unambiguous and distinguishable from sibling tools like list_dev_docs or update_dev_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 implies usage for retrieving one document's full content, but does not explicitly state when not to use or provide alternatives. Context from sibling tool names (e.g., list_dev_docs) gives some guidance, but it is not direct.

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. The description adds minimal behavioral context (e.g., specifies target clients and no auth required), but does not disclose anything beyond what the annotations imply.

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

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

The description is a single concise sentence that conveys all necessary information without superfluous words.

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

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

For a simple information retrieval tool with no parameters and no output schema, the description is complete: it states the purpose, target audience, and authentication requirement.

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

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

There are zero parameters and schema coverage is 100%, so the description does not need to explain parameters. The baseline of 4 is appropriate.

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

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

The description clearly states the tool provides setup instructions for AI Note MCP across multiple clients, with a specific verb and resource. No sibling tool offers similar functionality, so differentiation is not needed.

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 indicates no authentication is required, implying public use. While it does not explicitly state when to use or alternatives, the context is clear given the lack of competing 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?

Adds important behavioral context beyond annotations: the 7-day retention window, daily cleanup job, and read-only nature. No contradiction with annotations (readOnlyHint, destructiveHint).

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

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

Three sentences, each adding distinct value: purpose, date behavior, time behavior + cleanup. Front-loaded with main action, no 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?

Covers retrieval logic, cleanup, and parameter usage well. Lacks return format description, but given no output schema, it's acceptable. Could mention what happens if no matching handoff exists.

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

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

Schema coverage is 100%, but the description adds meaningful guidance beyond schema descriptions—e.g., 'Omit for latest' for date and detailed disambiguation instructions for time. Example value 'HHMM (KST)' is helpful.

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 'Retrieve a session handoff by project + topic', using a specific verb and resource. Distinguishes from siblings like handoff_save and handoff_list, and explains special behavior for omitted date and time parameter.

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 guidance for when to omit/include date and how to use the time parameter for disambiguation. Does not directly contrast with alternatives, but the context makes usage 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=true, destructiveHint=false. The description adds valuable transparency: entries older than 7 days are filtered out and permanently deleted by a daily cleanup job. It also explains that v2 frontmatter fields are exposed in each entry without fetching the body. No contradictions 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 three sentences: purpose, filter details, retention behavior. Every sentence adds value, no fluff. Information is front-loaded 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 7 parameters and no output schema, the description is fairly complete but lacks details on the return format (e.g., what fields are in each entry beyond frontmatter fields). With no output schema, the description should ideally list the response structure. However, it does mention that v2 frontmatter fields are exposed, which partially addresses this.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context that filters are server-side and that v1 handoffs are excluded when status filter is set, but this is largely redundant with schema descriptions. Minimal additional 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 verb 'List', the resource 'session handoff notes', and the location 'primary vault under handoffs/'. It distinguishes from siblings like handoff_get and handoff_save by focusing on listing. The 'most-recent first' ordering further clarifies 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 does not explicitly state when to use this tool vs alternatives. It implies listing handoffs, but lacks guidance such as 'use handoff_get for a single entry' or 'use handoff_save to create'. The retention note is behavioral, not usage guidance. Sibling tool names provide some context but not 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?

The description reveals storage location, file naming convention, and WAF-bypass tips, adding significant behavioral context beyond annotations. No contradictions with annotations (idempotentHint=true is consistent with overwriting 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 two sentences with no wasted words. It front-loads the core purpose and immediately adds actionable detail about the time parameter.

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 comprehensively but lacks information about what the tool returns (e.g., confirmation or file path). For a write tool with no output schema, 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?

All 6 parameters are fully described in the schema (100% coverage), and the description adds extra meaning by explaining the file path pattern and time suffix behavior, which goes 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 saves a session handoff note for cross-device/session continuation, using a specific verb and resource. It distinguishes from sibling tools like handoff_get and handoff_list by specifying the write operation.

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

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

The description gives guidance on using the optional time parameter to disambiguate multiple handoffs on the same day, but does not explicitly state when not to use this tool versus alternatives like handoff_get.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe, non-destructive operation. The description adds the return fields and reinforces read-only behavior but does not disclose additional behavioral traits like pagination or ordering.

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

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

The description is two sentences long, front-loaded with the main action, and contains no unnecessary words. Every sentence adds 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 simplicity (no parameters, no output schema) and the annotations covering safety, the description fully conveys what the tool does and what it returns. It is complete for the agent's needs.

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

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

The input schema has zero parameters and 100% schema description coverage. With no parameters to document, the description correctly omits parameter details; baseline score of 4 is appropriate.

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

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

The description clearly states the tool lists all task categories for the authenticated user and specifies the exact fields returned (id/name/color/icon/task_count). This distinguishes it from the sibling 'list_dev_categories' which deals with dev categories.

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 it is read-only and suggests using 'create_task' with a category_id to assign tasks. This provides clear context on when to use this tool vs alternatives, though it lacks explicit mention of 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 indicate readOnlyHint, idempotentHint, destructiveHint, so the tool is safe. Description adds that it returns document counts, which is behavioral information beyond annotations. 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, no waste. First sentence states purpose with examples, second gives usage guidance. Efficient and clear.

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 annotations covering safety, the description is complete: it explains what it does, why to use it, and how it relates to a sibling. No gaps.

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

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

No parameters exist, so schema coverage is 100% (empty). Baseline for 0 parameters is 4; description does not need to add 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?

Description clearly states the verb (list), resource (all subcategories under dev/), and provides examples (memory, claude, cursor, etc.). It distinguishes from sibling tool list_dev_docs by specifying it is for discovery before filtering.

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: 'Use to discover which categories exist before calling list_dev_docs with a category filter.' Provides clear context and alternative.

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, fully covering safety. The description adds context about filtering capabilities but does not disclose additional behavioral traits (e.g., performance, ordering, or restrictions). With annotations providing sufficient transparency, the description adds marginal value.

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

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

The description is a single sentence efficiently conveying purpose and key filters without redundancy. Every word earns its place, and the main action ('List dev documents under the dev/ category hierarchy') 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 description covers basic functionality but lacks information on pagination, ordering, or result limits, which are common for listing tools. Without an output schema, these omissions affect completeness. The description is adequate but not fully comprehensive.

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% (all three parameters have schema descriptions). The tool description paraphrases these descriptions and adds example values for subcategory, but does not provide significant new meaning beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists dev documents under a specific category hierarchy and lists available filters. This distinguishes it from sibling tools like list_categories (which lists categories) and list_papers (different content), making the purpose specific and unambiguous.

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

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

The description specifies when to use the tool (to list dev docs with optional filters) and implicitly excludes use cases for other tools by mentioning different filters and hierarchy. However, it does not explicitly state when not to use this tool or suggest alternatives, leaving some inference to the agent.

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

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

Annotations already declare readOnly and idempotent hints. Description adds value by listing returned fields (id, title, content_preview, etc.) and capabilities like keyword search and pagination, which are not in annotations. No contradiction.

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

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

Three concise sentences: purpose+capabilities, return fields, usage examples. No filler words, each sentence adds unique 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?

Covers core search, filter, pagination, and sort features. Mentions return fields despite no output schema. Could optionally note max limit (in schema) or preview truncation, but overall adequate for a list 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 coverage is 100% with each parameter well-described. Description mentions high-level features (keyword search, category filtering) that map to parameters but adds no new meaning beyond the schema definitions. Baseline 3 applies.

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

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

Description clearly states 'List notes/papers from AI Note' with explicit capabilities (keyword search, category filtering, pagination, sorting) and return fields. Distinct from sibling tools by specifying 'notes/papers' as the resource, differentiating from other list tools like list_categories.

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 concrete usage examples: 'Use this when the user asks find my note about X', 'what did I write on Y', or wants to search their knowledge base.' Lacks explicit when-not-to-use or alternatives, but examples strongly indicate appropriate contexts.

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. The description 'list' aligns with these, but adds no additional behavioral insights such as pagination behavior, rate limits, or data freshness. Since annotations cover the safety profile, the description is adequate but not enhanced.

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 concise and front-loaded, containing no superfluous words. It efficiently communicates the tool's core functionality.

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 18 parameters fully described in the schema, annotations indicating read-only and idempotent behavior, and no output schema required, the description sufficiently covers the tool's capabilities. It misses some nuance about filter combinations but is generally complete for a listing tool with rich 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 coverage is 100% with all parameters described in the input schema. The description only summarizes parameter categories (e.g., 'date ranges', 'location search') without adding new details. Baseline is 3 due to high schema coverage, and the description does not improve parameter understanding 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 verb 'list', resource 'tasks from AI Note', and specifies advanced filtering, date ranges, location search, and sorting. It effectively distinguishes this tool from sibling tools like create_task or delete_task.

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

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

The description implies usage for listing tasks with various filters but provides no explicit guidance on when to use this tool over alternatives or when not to use it. The context is clear but lacks exclusion criteria or sibling comparisons.

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-readonly and non-idempotent, but the description adds critical behavioral context: the side effect of creating an MCP key if absent, specifying the write target (user.mcp_keys). This exceeds the annotation detail and aligns with idempotentHint=false.

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 extraneous text. The main action is front-loaded, and the side-effect warning is placed second, 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 no output schema, the description clearly states the return value (MCP API key). It covers authentication requirements, side effects, and idempotency, making it complete for a tool with simple inputs and important behavioral caveats.

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 meaningful parameter descriptions for 'email' and 'password'. The tool description adds no additional semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'Log in to an existing AI Note account and return an MCP API key,' specifying the verb, resource, and outcome. It distinguishes from sibling 'signup_and_get_key' by noting 'existing' account, and the side effect note further differentiates it from a simple login.

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 'No prior authentication required,' and warns 'it is NOT idempotent and must be gated like other key-creation flows.' This provides clear when-to-use and when-not-to-use guidance, including important safety instructions.

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. The description adds beyond that: it reveals the return value { found: false } when item doesn't exist or belongs to another user, and clarifies that only authenticated user's items are accessible. This provides valuable behavioral context.

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

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

The description is two sentences, front-loaded with the main action, and every clause adds essential information. 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?

Given no output schema, the description covers the return value behavior and authentication scope. It includes prerequisites (use memory_search), parameter rules, and error cases. It is fully sufficient for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds conditional semantics: 'source=paper requires id; source=vault_file accepts id or path'. It clarifies that id comes from memory_search and path is a file path, enhancing understanding beyond schema 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 tool fetches full content of one memory item, specifying the verb 'Fetch' and the resource 'memory item'. It distinguishes between source types ('paper' requires id, 'vault_file' accepts id or path), and sets it apart from siblings like memory_search, making 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 implies that memory_search should be used first to get the item, and provides conditional rules for source and parameters. However, it does not explicitly state when not to use this tool or list alternatives, though 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 indicate safe read operations, and the description adds value beyond them by detailing return format (snippets, not full content), mode behaviors, and error handling. No contradictions 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 sections (COST PRINCIPLE, MODES), but the MODES section could be slightly more concise. However, every sentence adds value and the main purpose is front-loaded, so it is efficient overall.

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 (modes, fallback, error handling), the description covers all essential aspects: purpose, usage, behavioral traits, parameters, and output schema (implied via return description). No gaps for agent 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?

With 100% schema description coverage, the schema already documents each parameter. The description adds crucial context: explains mode behavior in depth, notes that query may be blank only in latest_state mode, and provides examples. This significantly enriches agent 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 clearly states the tool's action ('search') and resource ('memory'), specifying it searches across dev docs, papers, and vault markdown files to return ranked snippets with IDs. This distinguishes it from siblings like memory_get and provides a concrete sense of the tool's scope.

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

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

Explicit guidelines include the cost principle (use memory_get for full content), mode explanations (keyword vs latest_state with fallback behavior), and handling of empty results (treat as definitive empty signal). These guide the agent on when and how to invoke the 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?

The description adds behavioral context beyond annotations: it details the steps (fetch, create directories, write files, report success/failure) and lists typical files restored. Annotations indicate readOnlyHint=true and destructiveHint=false, and the description aligns by saying it 'restores' files. 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?

The description is well-structured with clear sections: main statement, WHEN TO USE, WHAT IT DOES, TYPICAL FILES RESTORED, and a closing note. Every sentence adds value, and there is no redundant or unnecessary text.

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 (1 optional parameter, no output schema, read-only, idempotent), the description covers the main behavior and use cases. It could mention overwriting behavior or error handling, but the typical files list and step-by-step are sufficient. Minor gap for a complete picture.

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

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

Schema coverage is 100% for the single optional parameter 'category'. The description does not add new semantic meaning about the parameter beyond what the schema provides ('Subcategory filter. Omit to pull all docs with local_path.'). The description mentions 'Fetches every dev doc that has a local_path set' but does not elaborate on how the category filter works. Baseline 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 states a specific verb and resource: 'Restore all synced files to this device. Fetches every dev doc that has a local_path set and writes the content to that path on disk.' This clearly distinguishes it from sibling tools like sync_pull (which likely syncs changes) and get_dev_doc (which returns a single 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 includes an explicit 'WHEN TO USE' section listing appropriate scenarios (first-time setup, after reinstalling macOS, to restore memory files). It also says 'Run this once after setting up ainote MCP on a new device', implying it is not for regular sync. However, it does not explicitly exclude cases where it should not be used or name sibling 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 indicate write, non-idempotent, open-world. Description adds 'No authentication required' and confirms account creation. No contradictions, but could mention error scenarios like duplicate email.

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 succinct sentences, front-loaded with purpose. No redundant information.

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

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

Adequate for a simple signup tool. Lacks explicit mention of return value and error handling, but the core action is well-covered.

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

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

Schema coverage is 100% with clear parameter descriptions. The description does not add additional meaning beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states the tool creates a new account and retrieves an API key. It distinguishes itself from the sibling 'login_and_get_key' which is for existing users.

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 'No authentication required. Use this if you don't have an account yet.' This tells agents exactly when to use it and implies the alternative (login) for existing users.

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?

Given annotations provide no safety hints (readOnlyHint=false, destructiveHint=false), the description fully bears the burden. It clearly states that summary text is not stored (only HMAC digest), that writes are skipped unless opt-in is configured, and that success is returned even when skipped. These are critical behavioral disclosures.

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, efficiently packed with purpose, behavioral caveats, opt-in mechanism, and usage context. No filler; each sentence adds distinct information. Front-loaded with the core function.

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

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

The tool has 5 parameters, opt-in logic, and complex behavior. The description covers input semantics well and mentions success return even on skip, but lacks details on the response format or error cases. Given no output schema, a brief note on the vault_events row structure would improve completeness but is not mandatory.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by listing the allowed verdict values ('pass, flag, block, error') and emphasizing that the summary is HMAC'd and never stored, which is not in the schema. This goes beyond a simple restatement.

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 it records client-side Layer 5 codex review results as vault_events rows, with specific reference to sync.py merge gate. This distinguishes it from sibling sync tools (e.g., sync_merge, sync_push) by being an audit-logging tool for codex review outcomes.

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 it is opt-in (requires ENV variable and HMAC secret) and used by specific hooks (SessionStart, merge command). It does not explicitly list alternatives or when not to use, but the context is clear enough for an agent to decide.

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 behavioral details beyond annotations: CAS mechanism, protected path requirements, idempotence behavior (deleting non-existent path returns success with deleted:false), and auditing of force flag. Annotations already provide destructiveHint and idempotentHint, but description enriches 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?

Three concise sentences with front-loaded purpose. No redundant information; every sentence adds 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?

No output schema, but description covers return behavior for non-existent path (deleted:false) and conflict error (-32009). Could mention success response structure, but overall adequate for a delete 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 coverage is 100%, yet description adds functional meaning: explains base_sha for conflict detection, force for bypassing CAS, device_id for audit logging, and path format constraints.

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 'Delete a file from the primary vault' – specific verb and resource. Distinguishes from sibling tools like delete_dev_doc that operate on different resource types.

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 context for when to use CAS (for concurrent writes), explains protected paths require base_sha or force:true. However, no explicit when-not-to-use or alternative tools mentioned.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds key behavioral context: 'Server has no history — base_text must be supplied by the caller if a 3-way view is needed; otherwise this returns remote_text only.' This goes beyond annotations, though could be more detailed about edge cases.

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 composed of two concise sentences. The first states the output and primary use case, the second clarifies behavioral constraints. Every sentence adds value with no 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?

Given the tool's complexity (optional parameters for 3-way diff) and lack of output schema, the description adequately covers inputs and behavioral exceptions. It could mention return format or size limits, but it's sufficient for an agent to understand 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 coverage is 100%, so baseline is 3. The description adds meaning: explains base_text as 'client's baseline (last-known remote)' and local_text, and describes the effect of supplying them (differences for 3-way view or unified diff). This adds value beyond the raw 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 explicitly states 'Return the unified diff (and raw remote text) of a vault file.' It clearly identifies the verb (return) and resource (diff of vault file), and distinguishes from sibling tools like sync_merge by specifying its role in surfacing conflicts.

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: 'Useful for surfacing what sync_merge would conflict on, or for the client to render a git diff view before pushing.' It also states when not to use (NO database mutation) and implies alternatives (sync_merge for actual merging).

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds minimal context beyond verifying the read-only nature and scope to primary vault.

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?

Single sentence, no redundancy. Could benefit from structuring to highlight the legacy alias aspect and vault scope.

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

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

For a simple optional-parameter tool with comprehensive annotations, the description is adequate but fails to explain 'primary vault' or alternative tools.

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

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

Schema coverage is 100%, and the description does not add meaning beyond the schema's parameter description. The mention of 'primary vault' is not linked to the path 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 it lists files in the primary vault, but the phrase 'legacy alias' introduces ambiguity about its role relative to other 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?

No guidance on when to use this tool versus sibling list tools (e.g., list_dev_docs, list_categories). No indication that it's a deprecated alias.

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 readOnlyHint, idempotentHint, destructiveHint. The description adds operational details: stateless, uses git merge-file, returns merged text and remote_sha, and reinforces no mutation. 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?

The description is concise, front-loaded with the core purpose, and every sentence adds value. No unnecessary information.

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

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

The description covers the operation, input, output (though no output schema), and follow-up action. It is complete enough given the complexity and annotations, but lacks detail on the exact response format.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context about how base_text and local_text are used and mentions remote_sha, but does not significantly enhance parameter meanings beyond the 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 it computes a stateless 3-way merge for a vault file, specifying the underlying command and the inputs. It distinguishes from siblings by explicitly mentioning the follow-up sync_push.

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 when to use this tool (for merging) and provides clear guidance on what not to do (NO database mutation) and what to do next (follow up with sync_push). It also mentions the key parameters.

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, destructiveHint. Description adds ordering by most recent first and the specific data source, which provides additional behavioral context 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?

Two concise sentences, front-loaded with the core action. No redundant information; every sentence adds 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 no output schema, description explains it returns rows ordered by most recent, but does not detail the specific fields of each conflict row. However, the tool name and context (vault conflicts) provide sufficient understanding. Almost complete.

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

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

Schema coverage is 100%, so the schema describes both parameters fully. Description does not add new semantic information about parameters beyond what the schema already provides (default and max for limit are in 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?

Clearly states it lists unresolved vault_conflicts rows for the authenticated user's primary vault, distinguishing it from siblings like sync_merge or sync_diff. The verb 'List' and resource 'vault_conflicts' are 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?

Explicitly mentions use case (SessionStart hook to surface conflicts) and that it returns up to limit rows. Does not explicitly state when not to use or list alternatives, but the context of sibling tools implies this is for initial conflict detection before merge.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which sufficiently cover the behavioral profile. The description aligns with these but adds no extra behavioral context beyond 'pulling files'.

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

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

The description is a single sentence that immediately conveys the tool's purpose and legacy status, with no unnecessary 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?

Given the tool is a legacy alias without an output schema, the description is minimally adequate. However, it could elaborate on what 'pulling files' entails (e.g., download vs sync) to be 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 100%, so the description adds no new meaning beyond what the input schema already provides for 'path' and 'since' 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 tool's function ('pulling files from the primary vault') and adds context as a 'Legacy alias', which helps distinguish it from potential newer alternatives among 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 description labels the tool as a 'Legacy alias' but provides no explicit guidance on when to use it versus the non-legacy alternative. No usage scenarios or exclusions are mentioned.

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

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

The description details the behavior beyond annotations: it explains the CAS mechanism, conflict responses, force option, and encoding handling. Annotations indicate destructiveHint=true, and the description expands on this accurately, with 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?

The description is three sentences front-loaded with the primary action. It conveys essential information without redundancy, efficiently covering main behavior and optional tips.

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 7 parameters and no output schema, the description explains the core functionality and optional features well, but lacks details on return values (success format) and fails to mention potential failure cases beyond CAS conflict.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the high-level purpose of parameters, such as the CAS plan and WAF bypass tip, providing meaning beyond the 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 'Push a markdown file into the primary vault', using a specific verb and resource. It also mentions optional CAS via base_sha, distinguishing it from sibling sync tools like sync_pull or sync_delete.

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 context for optional parameters (e.g., base_sha for conflict detection, content_b64 for WAF bypass) but does not explicitly state when to use this tool versus alternatives or define exclusion 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?

Annotations provide idempotentHint=true and destructiveHint=false; the description adds the update modes (replace, append, prepend) and optional local_path sync, which are behavioral details beyond annotations. No contradiction present.

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

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

Two concise sentences that cover the core functionality, modes, and optional parameter. No unnecessary words 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 description lacks clarity on how the document is identified (e.g., by id or title+category). It omits that 'id' is not required but presumably needed for update. For a tool with 7 parameters and no output schema, more detail would improve completeness.

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

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

Schema coverage is 100% with all parameters described. The tool description does not add significant additional meaning beyond the schema; it only briefly mentions modes and local_path, which are already clear from enum 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 explicitly states 'Update an existing dev document' (verb+resource) and distinguishes from create/delete by focusing on update with modes (replace/append/prepend). It clearly identifies the tool's scope.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives like create_dev_doc (for new docs) or delete_dev_doc (for removal). It implies usage for modifying existing docs but lacks exclusion 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?

Annotations already indicate non-read-only, non-destructive, idempotent behavior. Description adds the ability to clear fields with 'null', which is useful beyond 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?

Single sentence, front-loaded with key information, 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?

Adequate for a mutation tool with full schema coverage, but lacks details on return values, error conditions, or side effects beyond what annotations provide.

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

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

Schema coverage is 100%, so description adds no extra meaning beyond stating 'All fields are optional except id', which is already evident from the required field.

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 'Update an existing task', specifying the verb and resource. Distinguishes from sibling tools like create_task and delete_task.

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?

Implies usage when modifying a task but no explicit guidance on when to use this versus alternatives, no exclusions or conditions provided.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds authentication context not covered by annotations, though it doesn't detail return format or error cases.

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 purpose, no redundant words. 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?

For a simple read-only URL retrieval with robust annotations, description covers essential aspects. Lacks error handling or return format details but is adequate given tool simplicity and no 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?

Schema description coverage is 100%, so baseline is 3. Description does not add any extra meaning beyond the schema's parameter descriptions for 'name' and 'target_path'.

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 clearly states the action ('Return'), the specific resource ('GitHub HTTPS clone URL'), and the context ('for an existing vault'). It distinguishes from siblings like vault_create or vault_list by focusing on clone URL retrieval.

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 authentication method (GitHub PAT or gh CLI) but lacks explicit guidance on when to use this tool versus alternatives, prerequisites (e.g., vault must exist), 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it 'talks to GitHub API' and explains the two possible return structures (account_login + installation_id vs install_url), which go beyond annotations by detailing the interaction and data flow.

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 sentences, front-loaded with the purpose, and every sentence adds value. No superfluous 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 tool with no parameters and no output schema, the description fully covers all necessary context: what the tool checks, what it returns in each case, and that it's read-only. No gaps remain.

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, so baseline is 4. The description does not need to add parameter details, and it correctly avoids adding unnecessary information.

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 clear verb-phrase 'Check whether the user has installed the ainote GitHub App' and specifies the resource (connection status). It distinguishes from siblings by being the only tool that checks GitHub App installation status, as no sibling has similar functionality.

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

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

The description states the condition (if connected vs not) and the corresponding outputs, providing clear context for when to use this tool. However, it does not explicitly mention when not to use it or list alternatives, but the purpose is straightforward and self-contained.

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 mutation (readOnlyHint=false) and non-idempotence. The description adds context: the vault is a private GitHub repository and requires prior setup. It does not contradict annotations. It could be more explicit about side effects (e.g., repo creation under user's account), but the current level is adequate.

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

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

The description is highly concise with two sentences: first states the core action, second states a critical prerequisite. Every sentence adds value, and there is no redundancy or unnecessary detail.

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

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

Given the tool's low complexity (2 parameters, no output schema), the description covers the essential aspects: what it does, that it creates a GitHub repo, and the required precondition. It could optionally mention what the return value is or that the vault is private, but overall it provides sufficient context for an agent to decide to use it.

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 covers 100% of parameters, providing detailed descriptions (name derives slug for repo name, description is optional GitHub description). The tool description does not add any additional semantic meaning beyond the schema, so it meets the baseline of 3.

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

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

The description clearly states the tool creates a new private vault as a GitHub repository under the user's account. The verb and resource are specific, and it distinguishes from sibling tools like vault_list or vault_clone by focusing on creation. However, it doesn't explicitly differentiate from other 'create' tools like create_task, but the tool name already handles that.

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 clear prerequisite: the user must have completed the GitHub App install flow. It implies when to use (when creating a vault) and does not need explicit exclusions as the context is straightforward. No alternatives are mentioned, but the sibling tools are for different operations, so usage is well-understood.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds context about the data returned (fields like slug, github_repo_full_name, sync status, etc.) and confirms the read-only nature, enhancing 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 sentences long, front-loads the core purpose, and avoids any extraneous information. Every sentence adds 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 no parameters and sufficient annotations, the description fully covers what the tool does and how to extend its use with sibling tools. It lists the returned fields, which compensates for the lack of 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?

No parameters exist, so the description is not required to detail them. The schema coverage is 100% by default, meeting the baseline. The description does not introduce any parameter-related confusion.

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 (List) and resource (the authenticated user's GitHub-backed vaults). It specifies the fields included, distinguishing it from sibling tools like vault_clone and vault_sync.

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 it is read-only and provides guidance on when to use sibling tools: vault_clone for git clone URL and vault_sync for read/write operations.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds the WAF-bypass mechanism for push but does not disclose other behavioral traits like rate limits or side effects beyond what annotations 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?

The description is two sentences and includes all critical information: action semantics and WAF-bypass. Every sentence is necessary and there is no extraneous text.

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?

There is no output schema, and the description does not explain return values or results for each action (e.g., list returns file list, pull returns content). This leaves a significant gap for an agent.

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

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

Schema coverage is 100% with descriptions for each parameter. The description reiterates the actions and WAF-bypass for content but adds minimal new semantic meaning beyond the schema.

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

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

The description clearly states it is a wrapper for vault file sync with actions list, pull, and push. It mentions working on the primary vault, but does not explicitly differentiate from sibling sync tools like sync_list, sync_pull, and sync_push.

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 via the action parameter but does not specify when to use this wrapper over individual sync tools. The sibling tools suggest potential overlap, and no guidance is provided for selection.

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