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?

Annotations indicate a write operation (readOnlyHint=false) and non-idempotent (idempotentHint=false). Description adds context about one-shot token and registration, but doesn't elaborate on side effects or auth requirements.

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

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

Single sentence, efficient and front-loaded, no wasted words.

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

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

With 4 parameters (including nested capabilities) and no output schema, the description fails to cover capabilities parameter or return value, making it incomplete for complex use.

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

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

Schema description coverage is 0%, description hints at enrollment_token and age_pubkey but omits capabilities and alias, leaving 2 of 4 parameters unexplained.

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

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

Description uses specific verb 'complete device enrollment' and explains the exchange process, clearly distinguishing it from sibling tools like env_sync.device_list.

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 explicit guidance on when to use this tool versus alternatives, such as when enrollment token is available 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=true, idempotentHint=true, and destructiveHint=false, covering safety. However, the description does not explain the behavior of the only parameter 'include_stale', which affects whether stale devices are included. This is a key behavioral trait missing, requiring the agent to infer from the parameter name.

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: first states action and scope, second specifies returned fields. No wasted words, well-structured for quick parsing.

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

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

Despite low complexity (one optional boolean, no output schema), the description fails to document the 'include_stale' parameter and does not elaborate on output format (e.g., list order, pagination). This leaves gaps for effective use.

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

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

Schema description coverage is 0%, so the description must compensate for the parameter. It does not mention 'include_stale' at all, leaving the agent to rely solely on the parameter name. The description only explains return fields, not input semantics.

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

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

The description clearly states the verb 'List' and the resource 'enrolled devices for the calling user', with additional context on fields returned. It distinguishes from sibling tools like env_sync.device_enroll (enrollment) and env_sync.heartbeat_ping (ping).

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 the tool lists devices for the calling user, providing clear context for when to use it. While it does not explicitly state when not to use it or name alternatives, the sibling tool names imply different purposes (e.g., enrollment, sync), making 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 indicate idempotency and non-destructiveness. The description adds a critical security behavior ('Plaintext never transits'), which goes beyond annotations. It does not repeat or contradict annotations. It could disclose more about failure modes or state changes, but the added value is significant.

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, focused sentence of 13 words. It is front-loaded with the action and key constraint, with no wasted words or redundancy. Perfectly concise for a tool with moderate complexity.

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

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

Given the tool's complexity (nested objects, 4 params, no output schema), the description lacks crucial context: what happens on success, error conditions, prerequisites (e.g., device_id must own access, which is in schema but not description), and the behavior if shares already exist. The description is too brief to fully guide an agent without additional structured data or sibling tool knowledge.

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

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

Schema description coverage is low (25%), with only device_id having a description. The tool description does not explain any parameter semantics; it only hints at secret_shares via 're-encrypted ciphertexts'. The description fails to compensate for the poorly documented schema, leaving the agent to guess about required fields like target_device_id and client_hlc.

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 ('share'), resource ('existing secrets'), and context ('with a newly enrolled device'), distinguishing it from siblings like secret_push or secret_pull. It specifies the method ('by uploading re-encrypted ciphertexts') and a key constraint ('Plaintext never transits').

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 after device enrollment ('newly enrolled device'), providing clear context. However, it does not explicitly state when to use this tool vs alternatives (e.g., secret_push for existing devices), nor does it mention any prerequisites 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=true, idempotentHint=true, destructiveHint=false, indicating a safe read. Description adds report detail (dwell time) but no 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 sentences, no wasted words, front-loaded. However, could include parameter context without breaking conciseness.

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

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

Adequate for a simple read-only report, but missing parameter context and output description. Given the large sibling set, more context would improve completeness.

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

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

The single parameter device_id is not described in the schema or description. With 0% schema description coverage, the description should explain the parameter's meaning, but it does not.

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 it's a cross-device drift report listing skills present on one device but missing on another. It identifies the specific resource (skills) and action (listing drift). While distinct from sibling tools like sync_diff, it doesn't explicitly differentiate itself.

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

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

No guidance on when to use this tool versus alternatives (e.g., sync_diff, sync_status). With many sibling tools, explicit usage context is missing.

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

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

The description discloses key behaviors beyond annotations: it updates last_sync_at and capabilities, and triggers a fast-path drift recheck conditionally. This adds context about state changes and conditional triggers, although it could mention idempotency implications more explicitly given the idempotentHint=true annotation.

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

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

The description is a single, concise sentence that efficiently conveys the core action and effects. It is front-loaded with the tool's purpose and avoids unnecessary verbiage.

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

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

Despite adequate annotations, the description omits information about return values, all optional parameters' roles, and the specific output schema. Given 8 parameters and no output schema, the description leaves gaps that could hinder correct invocation, especially for optional fields like os and claude_code_version.

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

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

With 0% schema description coverage, the description fails to compensate adequately. It vaguely refers to 'installed-set hashes' but does not explain individual parameters like device_id, os, claude_code_version, or the arrays. Parameter meanings are left to inference from field names.

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

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

The description clearly states the tool's purpose as a device heartbeat ping, specifying it updates last_sync_at and capabilities and conditionally triggers a drift recheck. It effectively distinguishes itself from sibling tools like env_sync.drift_status and env_sync.sync_status by focusing on periodic check-ins and state updates.

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?

While the description implies usage for periodic device check-ins, it lacks explicit guidance on when to use this tool versus alternatives (e.g., env_sync.device_enroll for initial enrollment or env_sync.drift_status for drift checking). No exclusions or prerequisites are mentioned.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds critical behavioral context: 'server never sees and never returns plaintext,' which goes beyond annotations and informs the agent about privacy guarantees.

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 action, and every sentence adds value. 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?

The description correctly notes the response format (ciphertext_b64) and safety aspects, but fails to explain how to identify the secret (node_id or alias) and the oneOf requirement. Given the lack of output schema, this is a notable gap.

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

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

Schema coverage is 0%, so the description must explain parameters. It provides no information about the two parameters (alias, node_id) or the oneOf condition. The description is entirely silent on how to specify which secret to pull, leaving the agent without guidance.

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

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

The description clearly states the action ('Pull') and the resource ('encrypted secret blob'), and distinguishes from sibling tools like secret_push and secret_rotate. It also specifies that the response is ciphertext_b64 only, which is specific and unique.

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

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

The description implies the tool is for retrieving a secret blob but does not explicitly state when to use it versus alternatives (e.g., secret_push, secret_rotate) or provide exclusions. Usage context is only implied by the tool name and sibling names.

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 mentions the server never sees plaintext and a recipient constraint, but fails to disclose behavioral traits like idempotency, conflict handling, or error scenarios. With annotations all false, the description should provide more depth.

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-loading the core purpose and key constraint. Every sentence is meaningful 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?

Despite having no annotations and no output schema, the description is too brief. It omits important details like what client_hlc is, behavior on duplicate aliases, and the exact format of recipients, leaving the tool under-specified.

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

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

The description does not explain individual parameters beyond ciphertext and recipients. Alias, kind, device_id, and client_hlc are left unexplained. With 0% schema coverage, the description should compensate but fails to do so.

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 pushes a new client-encrypted secret, emphasizes that only ciphertext is sent and the server never sees plaintext, and distinguishes it from siblings like secret_pull and secret_rotate.

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 constraint (recipients must include the pushing device's own pubkey) but does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations declare destructiveHint=true, and the description adds valuable context: the process involves soft-deletion followed by a 7-day grace period before hard delete. This goes beyond the annotation and provides critical behavioral details.

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

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

Two sentences with clear front-loading of the action. Every sentence adds essential 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?

Missing information about return values (no output schema) and prerequisites (e.g., permissions, node existence). The description covers the core process but lacks context for a complete understanding of the tool's interaction.

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

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

The description mentions 'old node' and 'new ciphertext+recipients' but does not explain the meaning of device_id or client_hlc parameters. With 0% schema description coverage, the description fails to compensate and leaves parameter semantics unclear.

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

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

The description uses a specific verb 'rotate' and clearly outlines the process: soft-delete old node, create new live node with same alias and new ciphertext+recipients. It distinguishes from sibling tools like secret_push or secret_pull by focusing on rotation.

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 explicit guidance on when to use this tool vs alternatives like secret_push or secret_pull. The description implies rotation but does not compare or exclude other tools, making it harder for an agent to choose correctly among many 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?

Annotations already declare readOnly, idempotent, non-destructive. The description adds that it returns a snapshot with specific fields, providing useful 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?

Single focused sentence with no unnecessary words. Front-loaded with key 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?

Covers the main purpose and return contents. Lacks description of output format or interpretation, but adequate for a zero-parameter health snapshot 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?

Zero parameters, so baseline is 4. The description adds no parameter info, which is acceptable since no parameters exist.

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 a user-level vault health snapshot with specific data points (node counts, pending conflicts, last transaction, device liveness). It distinguishes from sibling tools like env_sync.drift_status or env_sync.device_list.

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 explicit when-to-use or when-not-to-use guidance. The description implies usage for checking vault health, but does not mention alternatives or when other tools (e.g., drift_status) might be preferred.

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 pagination, HLC ordering, and filterability beyond annotations which only declare readOnly and idempotent hints. No behavioral 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 a single, well-structured sentence that front-loads purpose ('Paginated read') and efficiently adds ordering and filter details without 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?

For a 4-parameter tool with no output schema, the description explains core function and filtering but omits details on cursor usage, limit behavior, and return format, leaving gaps for full agent understanding.

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

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

Schema description coverage is 0%, but the description mentions filtering by since_hlc and op, adding partial semantics. However, it does not explain cursor, limit, or enum values, leaving gaps in parameter understanding.

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

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

The description clearly states the tool does a paginated read of the env_sync transaction log with HLC ordering. It distinguishes from sibling tools like env_sync_txn_push (write) and env_sync_txn_rollback (rollback).

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 'Read-only' which guides usage away from writing. However, it does not explicitly mention alternatives or when not to use this tool, though sibling names imply the appropriate tools for other 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 declare destructiveHint=true and idempotentHint=false. The description adds behavioral traits: 'HLC-skew gated' (ordering constraint) and 'partial-success on conflict' (conflict resolution behavior), which go 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 sentences with key information front-loaded; every word earns its place. 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?

No output schema, and the description omits details on return values, error handling, or how to interpret partial-success results. Adequate but lacks completeness for a mutation tool.

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

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

Schema description coverage is 0%, so the description carries full burden. It mentions 'batched envelope' but does not explain the structure or required fields of the 'operations' array (tool, args, hlc). No additional semantic value over schema field names.

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

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

The description uses a specific verb ('ingest') and resource ('batched envelope of client-recorded env_sync mutations'), clearly distinguishing it from siblings like env_sync_txn_pull and env_sync_txn_rollback.

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

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

The description states it is for ingesting mutations and mentions 'HLC-skew gated, partial-success on conflict,' providing context on usage but no explicit when-not-to-use or alternative tools.

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

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

Annotations indicate destructive and non-idempotent behavior; the description adds context about safety gates and force opt-out for descendant conflicts. However, it does not explain what 'inverse-apply' entails (e.g., reverting changes, deleting the transaction) or side effects.

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

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

Two sentences efficiently convey the core purpose and key safety features. No extraneous information; every phrase earns its place.

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

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

Given the complexity of env_sync transactions, the description lacks details on return values, prerequisites (e.g., ownership), and the full impact of parameters. The safety gates are mentioned but not elaborated, leaving significant 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?

With 0% schema description coverage, the description only hints at the 'force' parameter via 'force opt-out', but fails to explain 'txn_id' or 'include_descendants', leaving agents to infer from parameter names.

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

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

The description clearly states the tool's action: inverse-applying a prior env_sync transaction. It distinguishes from sibling push/pull transactions, but does not explicitly name alternative tools for rollback scenarios.

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 mentions safety gates (ownership, idempotency, descendant-conflict) which imply conditions for use, but lacks explicit when-to-use vs alternatives, such as when to prefer sync_delete or other rollback methods.

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?

Annotations indicate readOnlyHint false and destructiveHint false, and the description adds that collisions do not silently overwrite, which is useful. However, it lacks details about return values, error handling, or authorization requirements.

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

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

The description is two sentences, front-loading the purpose with no redundant information. Every word serves a clear 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?

With 5 parameters (4 required) and no output schema, the description is insufficient. It does not explain the structure of the payload, the role of device_id, or the optional client_hlc, leaving the agent underinformed.

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

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

Schema description coverage is 0%, and the description only lists the node_type values without explaining alias, payload, device_id, or client_hlc. The description does not compensate for the schema's lack of parameter documentation.

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

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

The description clearly states the action ('Create a new env_sync graph node') and specifies the types of nodes (skill/hook/mcp_server/secret/setting_fragment), distinguishing it from sibling tools like graph_update_entity and graph_soft_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 some behavioral context ('Same-alias collisions open a conflict bucket — no silent overwrite') but does not explicitly state when to use this tool versus alternatives like graph_update_entity, nor does it offer guidance on prerequisites or exclusions.

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

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

Annotations already declare safe read-only and idempotent behavior. The description adds context about 'live' data and per-field LWW (last-writer-wins) state, providing transparency beyond annotations.

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

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

The description is a single, front-loaded sentence with no unnecessary words. Every word 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, the description lacks details on response structure. It mentions per-field LWW state but not the format. With 3 parameters and lookup constraints, it is minimally complete but could add return value details.

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

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

Schema coverage is 0%, so description must compensate. It clarifies the oneOf lookup logic but does not explain the meaning of individual parameters (e.g., what alias represents). Node_type enum is in schema, but no additional semantics provided.

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

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

The description clearly states the tool reads a live env_sync graph node with per-field LWW state. It distinguishes from sibling tools like graph_list_nodes by specifying single-node lookup.

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 two lookup methods (node_id OR alias+node_type) and implicitly differentiates from list tools, but does not explicitly state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond scope ('live', 'for calling user') and does not disclose pagination details, rate limits, or ordering. It relies heavily on annotations.

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

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

The description is a single concise sentence that front-loads the core purpose and key filters. Every part adds value, and there is no redundancy or 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 is adequate for a simple listing tool with annotations, but it lacks details about return format, pagination behavior, default limit, and nuances of filtering. Given no output schema and multiple filters, more context 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 only 25% (only cursor has a description). The description mentions 'optional node_type and HLC-since filters' but does not explain the meaning of node_type enum values or the format/behavior of updated_since_hlc. It partially compensates for the low schema coverage but still leaves key semantics vague.

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 'live env_sync graph nodes', the scope 'for the calling user', and the optional filters 'node_type and HLC-since'. This distinguishes it from sibling tools like graph_get_node (gets a single node) and graph_add_entity (adds a node).

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 a read-only operation for listing nodes but provides no explicit guidance on when to use this tool versus alternatives like graph_get_node or other listing tools. There is no mention of when not to use it or prerequisites.

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

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

Description adds detail beyond annotations: explains the mechanism (sets deleted_at) and scope impact (.live hides from reads). Consistently expands on 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 efficient sentences with no wasted words. Key actions and idempotency stated upfront.

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 behavior and idempotency, but omits return value/confirmation and does not explain the client_hlc parameter. Adequate but not fully complete given 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 has 0% description coverage and the description does not explain any of the three parameters (node_id, device_id, client_hlc). Parameter names alone are insufficient for correct invocation.

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 soft-deletes an env_sync graph node by setting deleted_at and hiding from .live scope. Distinguishes from hard delete implicitly.

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 idempotency and no-op on re-delete, which guides usage, but does not explicitly contrast with alternatives like hard delete or other cleanup tools.

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

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

Annotations are non-committal (all false), so the description adds value by disclosing that identity-immutable field mismatches open a conflict bucket and that no partial writes occur. This provides behavioral context beyond the schema.

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

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

The description is two concise sentences, front-loaded with purpose and followed by a behavioral caveat. No extraneous 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 complexity (4 parameters with nested objects, no output schema), the description covers the LWW and conflict bucket mechanics but omits explanation of parameters, return behavior, or error cases. It is minimally adequate for an agent but could be richer.

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

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

Schema description coverage is 0%. The description does not explain any of the 4 parameters (node_id, device_id, client_hlc, field_updates) beyond what the schema structurally reveals. The phrase 'Per-field LWW' hints at field_updates but does not clarify required fields or 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?

The description clearly states 'Per-field LWW update for an env_sync graph node,' specifying the verb (update), resource (env_sync graph node), and nature (LWW). It also mentions conflict handling, distinguishing it from sibling tools like graph_add_entity, graph_get_node, etc.

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 updating existing graph nodes ('update'), but does not explicitly provide when-to-use/when-not-to-use guidance or contrast with alternatives like graph_add_entity. No exclusion criteria or prerequisites are stated.

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

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

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?

Discloses key behaviors: destructive write, optional CAS conflict detection, auditability of force flag, WAF bypass mechanisms, and superseded state handling. Annotations already indicate idempotent and destructive; description adds valuable context without contradiction.

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

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

Front-loaded with core purpose, then details CAS and WAF bypass. Two clear sentences, each adding essential context; efficient but could be slightly more 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?

Covers all major aspects: push action, CAS conflict handling, WAF bypass, force overwrite, device tracking, superseded conflict resolution. Lacks output schema but compensates with thorough parameter and behavior descriptions.

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

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

Schema covers 100% of parameters with descriptions, but the tool description adds significant context: explains CAS mechanism, WAF bypass strategies, conflict resolution flow, and device_id logging beyond bare schema definitions.

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 states specific verb 'push', resource 'markdown file', destination 'primary vault', and mentions CAS and WAF bypass, clearly distinguishing 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?

Provides guidance on when to use optional CAS (concurrent multi-PC writes) and WAF bypass tips, but does not explicitly compare to alternatives like sync_merge or when not to use.

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

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

The description discloses important behavioral traits beyond annotations: partial success with HTTP 200, conflict result structure, request-level failure conditions (duplicate paths, idempotency key reuse, size limits), and the role of content_sha in retry safety. This adds significant value and aligns with the idempotentHint.

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: first paragraph introduces purpose and comparison, second details semantics and failure modes. It is front-loaded with the key insight. While slightly lengthy, every sentence adds value and no information is redundant.

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 (batch, partial success, idempotency, conflicts, size limits), the description covers most aspects: when to use, cost, per-item semantics, partial success handling, conflict resolution link, request-level failures, and content_sha benefits. Absence of output schema is noted but description still provides adequate context.

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

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

Input schema coverage is 100%, so baseline is 3. The description adds meaningful context for several parameters: explains content_sha's role in integrity and retry, idempotency_key usage (do not derive from paths), and batch-level constraints (200 items, 4MB). This enriches 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 tool's purpose: pushing many files in one call to the primary vault. It uses a specific verb ('push') and resource ('files in batch'), and distinguishes it from the sibling sync_push by explicitly recommending it for batches larger than a couple of paths.

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

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

The description explicitly says 'Use this instead of looping sync_push whenever you have more than a couple of changed paths', providing clear usage context. It also explains the cost rationale (round trips vs bytes). It could be more explicit about when not to use it (e.g., single file), but the guidance is strong.

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.