ainote

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

Annotations only indicate non-read-only, non-destructive, non-idempotent. The description adds crucial behavioral details: `verdict` is rejected with an error, confirmation requires human judgment, and the tool can only shape the assumption (not confirm it). No contradiction with annotations.

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

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

The description is compact and front-loaded: first sentence gives the core action, second paragraph adds a critical safety warning. Every sentence adds value, and the use of a red emoji draws attention to the most important constraint.

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

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

Given the moderate complexity (create/update, no delete, verdict restriction), the description covers all main behaviors and constraints. It doesn't describe the return value, but no output schema exists; overall it's sufficiently complete for the agent to use correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does repeat id semantics already in the schema ('Omit to create, pass to update') and mentions a non-existent 'verdict' parameter, which is useful context but does not add meaning beyond what the schema provides for actual parameters.

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

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

The description uses a clear, specific verb ('Create or update') and resource ('assumption under a project (L2 intent layer)'), which distinguishes it from sibling tools. It explicitly mentions that verdict confirmation is handled elsewhere (judgment_submit), further differentiating its purpose.

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

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

Provides explicit instructions: omit `id` to create, pass it to update, and states there is no delete tool. It also warns against passing `verdict` and directs the agent to judgment_submit for that concern. This is clear when/when-not/alternative guidance.

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

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

Annotations are all false and unhelpful, so the description carries the burden. It reveals the action types and required inputs but does not disclose behavioral details such as whether the returned key expires, side effects on signup, error responses, or rate limits. The phrase 'Obtain an MCP key' is a high-level result without underlying behavior.

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

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

The description is compact and front-loaded, conveying the essential points in one sentence. The use of colons and pipes is efficient, though slightly cryptic. It earns a high score for minimizing words while communicating the consolidated surface and per-action requirements.

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 output schema, the description does not explain what the tool returns beyond 'an MCP key'—no details about the response structure, error handling, or post-conditions. Given it involves authentication with signup and login, more context about the returned key and potential side effects is necessary for correct 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?

Although schema coverage is 100%, the description adds value by explicitly listing which parameters are required for each action ('login: email, password | signup: email, password'). This addresses a gap in the schema, which only makes 'action' formally required, while the description clarifies that email and password are necessary depending on action.

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: 'Obtain an MCP key' with specific actions (login/signup). It uses a precise verb+resource structure and differentiates itself from siblings by being the authentication entry point, especially referencing 'consolidated surface' and 'legacy 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 provides usage guidance by noting it is a consolidated surface replacing legacy tools ('same handlers as the legacy tools') and clarifies per-action required parameters. It does not explicitly mention alternative sibling tools, but the context makes it clear when to use this tool.

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

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

Explicitly discloses soft-delete behavior and reversibility ('Reversible from trash'), which adds meaningful context beyond the destructiveHint and idempotentHint annotations. No contradiction with annotations.

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

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

Two concise sentences, front-loaded with the main action, then the specific disambiguation guidance. No fluff or redundancy.

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

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

Covers the core behavior, reversibility, and the edge case of title collisions. Lacks explicit mention that either `id` or `title` must be provided (since no required parameters), but this is implied. Good overall for a tool with annotations and full schema coverage.

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

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

Input schema already covers all parameters (100%), so baseline is 3. Description adds value by clarifying that `category` should be used when titles collide across subcategories and lists examples (memory/claude/cursor/env/docs). This goes 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 'Soft-delete a dev document by title or UUID' with a specific verb and resource. It distinguishes this from sibling tools like delete_task, graph_soft_delete, and sync_delete by focusing on dev documents.

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 clear context: mentions reversibility and explains when to pass `category` for disambiguation. Lacks explicit when-not-to-use or alternatives, but the resource-specific scope implies when it applies.

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 and idempotentHint), the description reveals the soft-delete nature, 30-day reversibility, daily purge job, and 404 responses for non-existent or unauthorized tasks.

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

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

Two sentences, front-loaded with the action, containing no filler content. Every word earns its place.

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

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

For a simple one-parameter delete tool with no output schema, the description covers purpose, behavior, constraints, and error cases comprehensively.

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 the single id parameter with a clear description, achieving 100% coverage. The tool description does not add additional parameter semantics, 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 'Soft-delete a task by ID' with a specific verb and resource, distinguishing it from sibling tools like delete_dev_doc or 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 implies usage (delete a task) but does not explicitly state when to use versus alternatives or exclusions. It adds context about reversibility but lacks explicit guidance on when not to use.

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

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

Annotations already disclose readOnly, idempotent, and non-destructive behavior. The description adds that this is a consolidated surface with the same handlers as legacy tools, which provides some behavioral context, but it does not disclose return format, pagination, or other operational 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?

The description is extremely concise, with two short clauses that front-load the core purpose. Every word earns its place, and there is 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?

Despite having 7 parameters and multiple action modes, the description does not explain what each action does—especially 'categories' and 'pull'—or what the tool returns. The schema documents parameter details, but the tool's overall behavior and action-specific semantics remain underspecified.

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 parameters are fully documented in the schema. The description's action list repeats the schema enum but does not add meaning beyond what is already provided, matching the baseline for high schema coverage.

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

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

The description clearly identifies the tool's purpose as reading dev docs, with a specific verb and resource. The action list (get, list, categories, pull) adds functional scope and distinguishes this read tool from sibling write tools like dev_doc_write.

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 state when to use this tool versus alternatives, nor does it mention that dev_doc_write should be used for modifications. Usage context is only implied by the phrase 'Read dev docs', which provides no explicit when/when-not guidance.

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

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

The description adds behavioral context beyond annotations by explicitly labeling the operation as 'non-destructive' and noting it is a 'consolidated surface — same handlers as the legacy tools'. This informs the agent about the tool's nature and provenance, which is not present in the annotations.

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

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

The description is extremely concise (two sentences) and front-loaded with the core purpose. It packs essential details (actions, non-destructive nature, per-action requirements, deletion alternative) without any filler or redundancy.

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

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

Given the tool's complexity (9 params, 4 enums) and the rich schema descriptions, the description provides sufficient high-level context to select and invoke the tool. It covers the essential action/parameter logic. A minor gap is that it doesn't explicitly tie into the sibling 'dev_docs_read' tool, but this is not critical for correct invocation.

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

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

Although the schema has 100% parameter descriptions, the description adds a critical layer by summarizing the conditional requirements: 'create: title, content | update: content'. This is not evident from the schema's 'required' field (only 'action' is required), and it directly helps the agent construct a valid 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?

The description clearly states the tool's function: 'Create or update a dev doc'. It explicitly identifies the resource (dev doc) and the actions (create/update). It also differentiates from siblings by noting that deletion is handled by a separate tool (delete_dev_doc), making its scope unambiguous.

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

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

The description provides explicit usage guidance: it tells the agent which parameters are required per action ('create: title, content | update: content') and explicitly says deletion is a separate tool, preventing misuse. This gives clear when-to-use and when-not-to-use context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds only that it is a consolidated surface with the same handlers as legacy tools, which is minor implementation context. No contradiction with annotations; the description adds limited value beyond them.

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

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

The description is concise and front-loaded with the action list. The parenthetical about the consolidated surface is slightly ambiguous but still compact. It conveys essential information without unnecessary verbosity, though it could be 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?

This is a multi-action tool with 7 parameters and no output schema. The description only lists action names without explaining what each action returns, how pagination works (e.g., cursor/limit for txn_pull), or how parameters relate to actions. Given the complexity, the description is not complete enough for an agent to use correctly without significant inference from the schema.

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

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

All 7 parameters have schema-level descriptions (100% coverage), so the baseline is 3. The tool description does not add parameter semantics beyond the schema. The schema descriptions themselves are terse for several parameters (e.g., '[txn_pull]'), but coverage is complete, so the description need not compensate.

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

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

The description clearly states the tool reads env-sync state and enumerates the exact supported actions (devices, drift, status, txn_pull). It explicitly differentiates itself from the sibling env_sync.secret_pull tool, removing ambiguity about 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 gives clear context that this is the read surface for env-sync and explicitly redirects secret reads to a different tool (env_sync.secret_pull). It also notes the consolidated-surface relationship to legacy tools, aiding migration. However, it does not mention when to prefer it over other sibling read/write tools, so it falls short of a 5.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral context: 'Response is ciphertext_b64 only — server never sees and never returns plaintext.' This privacy/security trait is not captured in the annotations and is essential for the agent to understand the tool's 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 a single, front-loaded sentence followed by a brief clarification. Every word contributes to understanding the tool's core function and response behavior. No unnecessary details or repetition.

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

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

The description covers the essential purpose and response format, which is especially important given no output schema. However, it lacks guidance on parameter selection (node_id vs alias) and does not mention the device_id fallback. This leaves some ambiguity for a tool with a oneOf schema and partially documented parameters.

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 provides no information about the node_id, alias, or device_id parameters. With schema description coverage at only 33%, the description should compensate but does not, leaving the agent without clarity on which identifier to use or the role of device_id.

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: 'Pull an encrypted secret blob.' The verb 'Pull' is specific and the resource is described, distinguishing it from sibling tools like secret_push and secret_rotate. It also adds the response format, further clarifying its role.

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

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

The description implies use for retrieving encrypted secrets without exposing plaintext, but it does not explicitly state when to use this tool versus alternatives like secret_push or secret_rotate. No prerequisites or exclusions are mentioned, leaving usage mostly implied.

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

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

Annotations provide no safety hints (all false), so the description carries the burden. It discloses two key behaviors: the server never sees plaintext and recipients must include the pushing device's own pubkey. However, it does not describe side effects like what happens if the alias already exists, whether it overwrites, or error scenarios. This is moderate 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, front-loaded with the primary action, and every sentence adds value. There is no wasted wording 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 covers the essential purpose and security requirements, but given the tool's complexity (6 params, no output schema, no annotations), it lacks details on return values, error handling, and preconditions. It is adequate for understanding the core operation but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It adds meaning for ciphertext_b64 ('Ciphertext only') and recipients ('must include the pushing device's own pubkey'), but leaves alias, kind, device_id, and client_hlc without any explanation. Given six parameters, this is insufficient to guide an agent on parameter construction.

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 'Push' with a clear resource 'client-encrypted secret,' and the constraints (ciphertext only, server never sees plaintext) clarify the exact action. It distinguishes from sibling tools like env_sync.secret_pull and env_sync.secret_rotate by focusing on pushing a new secret.

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

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

The description clearly indicates when to use this tool: to push a new client-encrypted secret. It provides context that this is for new secrets and emphasizes the encryption model, but does not explicitly state 'use this instead of pull/rotate' or give when-not-to-use conditions. The intended usage is strongly implied, but explicit exclusions are absent.

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

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

Beyond the destructiveHint annotation, the description discloses the soft-delete behavior, the creation of a new live node, and the 7-day grace period before hard delete, offering 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?

Two concise sentences front-load the primary action and include key lifecycle details without wasted words.

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

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

The description captures the core workflow and lifecycle, but it omits details about response values and does not clarify implications for the alias during the grace period, though it is adequate for an internal tool.

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

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

The description maps 'new ciphertext+recipients' to the corresponding parameters and indicates the alias relationship via node_id, but it leaves device_id and client_hlc unexplained, which is a gap given the schema has no 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's function: rotating a secret by soft-deleting the old node and creating a new live node with the same alias. This specific verb+resource distinguishes it from sibling tools like secret_pull and secret_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?

It provides clear context for when to use rotation (when you need to replace a secret's ciphertext and recipients) but does not explicitly contrast with alternatives or state exclusionary conditions.

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

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

Annotations already mark the tool as destructive/non-read-only. The description adds useful behavioral context beyond annotations via 'HLC-skew gated, partial-success on conflict,' but does not explain what partial-success implies, side effects, or prerequisites.

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 short, front-loaded sentences; every phrase contributes ('Ingest...', 'HLC-skew gated, partial-success on conflict'). No filler or redundant restatement.

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 and moderate complexity, the description is usable but thin: it hints at batch and conflict behavior, yet lacks expected return, error representation, and what partial-success means. Schema and annotations mitigate some gaps.

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

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

The tool description never references device_id or operations and adds no detail beyond schema. Schema covers device_id thoroughly, but operations has no top-level description; with 50% coverage, description should compensate and doesn't.

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 'Ingest' and resource 'batched envelope of client-recorded env_sync mutations', clearly distinguishing from single-write siblings like env_sync_write and sync_push. The HLC-skew and partial-success details further pin the tool's role.

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

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

No explicit when-to-use guidance or alternatives are named. 'Client-recorded batched' implies batch contexts, but the description does not contrast with env_sync_write, sync_push_batch, or env_sync_txn_rollback, leaving selection to inference.

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

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

Annotations already indicate destructiveHint=true, and the description adds valuable behavioral context by listing safety gates: ownership, idempotency, and descendant-conflict with force opt-out. This goes beyond the annotation by explaining under what conditions the destructive action is allowed or blocked.

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 and front-loaded, consisting of one clear sentence plus a brief list of safety gates. Every word adds value without redundancy.

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

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

For a destructive rollback tool with no output schema and 4 parameters (3 undocumented), the description is minimally adequate but leaves gaps: it doesn't describe the effect of force/include_descendants on behavior, nor what the response or error cases look like. The safety gates add context but not complete operational clarity.

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 device_id has a description). The description does not explain txn_id, force, or include_descendants explicitly. It hints at 'descendant-conflict (force opt-out)' linking force to descendant handling, but major parameter meaning is left to inference from the tool name.

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 as 'Inverse-apply a prior env_sync transaction,' using a specific verb and resource. It distinguishes itself from sibling tools like env_sync_txn_push by explicitly indicating a rollback/undo 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 phrase 'Inverse-apply a prior env_sync transaction' implies usage for undoing a prior transaction, but it does not explicitly state when to use this tool versus alternatives. It mentions safety gates but no comparison or exclusion relative to other sync 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 convey safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description's 'non-destructive' is consistent with destructiveHint=false. However, it adds little beyond that; it does not disclose return behavior, auth expectations, or side effects of each action. The note about 'same handlers as the legacy tools' is the only extra 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 dense but compact, packing action enum, exclusions, legacy context, and per-action requirements into three sentences. It is front-loaded with the core purpose and avoids fluff, though the run-on structure could be improved with bullets or clearer segmentation.

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 complex 16-parameter, 3-action consolidated tool, the description provides essential selection and invocation guidance: action modes, required fields per mode, and tool exclusions. Since no output schema exists, a brief note about return values or common errors would improve completeness, but the current information is largely sufficient for correct invocation.

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

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

Schema coverage is 100% with detailed per-action parameter descriptions, so the baseline is 3. The description adds meaningful value by listing exactly which parameters are required per action, reducing ambiguity. It does not repeat schema details, making this a useful supplement rather than redundancy.

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: non-destructive env-sync writes, enumerating the exact actions (enroll, request_share, heartbeat). It also distinguishes itself from sibling tools by explicitly noting that secret push/rotate are separate tools, which prevents agent confusion.

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 per-action required parameters, which guides when and how to invoke each mode. It names alternatives ('Secret push/rotate are separate tools') and mentions it is a consolidated surface with legacy handlers. It could be stronger by explicitly contrasting with env_sync_read or txn_push, but the guidance is clear for the main use cases.

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

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

Annotations already mark it as read-only and idempotent; the description adds that no authentication is required, which is valuable operational context. It also indicates the output is instructions, conveying the tool's non-destructive nature. 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 two sentences, front-loading purpose and adding a single relevant detail about authentication. Every word earns its place.

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

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

For a parameterless, read-only tool with no output schema, the description fully covers what the agent needs: what it does and the authentication requirement. Additional return format details are unnecessary for such a simple tool.

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

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

The tool takes no parameters, so the schema has 100% coverage by default. The description correctly omits parameter details, and the baseline for zero-parameter tools is 4.

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: retrieving setup instructions for AI Note MCP across specific clients (Claude Desktop, Cursor, other MCP clients). The verb 'Get' and resource 'setup guide' are specific and distinguish it from sibling tools, none of which mention setup guidance.

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

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

It implies when to use the tool: whenever the user needs setup instructions for AI Note MCP. The description provides clear context but does not explicitly state exclusions or alternatives, though no sibling tool addresses setup guides. Given the simplicity, this is sufficient.

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

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

Beyond the readOnly/idempotent/destructive annotations, the description only mentions 'consolidated surface' and 'same handlers as legacy tools', which gives no operational behavior details (e.g., pagination, audit attribution, error semantics). It adds minimal value over the annotations.

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

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

The description is a single, focused sentence. It front-loads the purpose and includes the key discriminator (action). No fluff.

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

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

With 8 parameters and no output schema, the description omits critical context: what a get returns vs list, pagination behavior, and the meaning of the consolidated surface. The schema covers parameters but not the overall tool semantics.

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

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

The input schema fully describes each parameter, so baseline is 3. The description repeats 'action: get | list' which is already in the schema, and does not add any new meaning beyond what the schema provides.

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

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

The description clearly states the verb 'Read' and resource 'knowledge-graph nodes', and explicitly enumerates the supported actions (get/list) as a consolidated surface. This distinguishes it from sibling tools like graph_write 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?

No when-to-use guidance is provided. The description does not explain when to use get vs list, nor does it reference alternatives (e.g., graph_write for mutations). The only usage hint is the action enum in the schema, not the description.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses the specific effect (sets deleted_at, hidden from .live scope) and confirms re-deleting is a no-op success. This adds meaningful behavioral context, though it does not mention potential side effects or permissions.

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 with a clarifying second sentence. It front-loads the action and uses no filler. Every clause adds value, making it highly efficient.

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

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

For a simple mutation tool with annotations, the description adequately explains the operation and idempotent behavior. However, with three unexplained parameters and no output schema, the agent may not know how to invoke it correctly or interpret the response. It is functional but not 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?

The schema has 3 parameters with 0% description coverage, and the description does not explain node_id, device_id, or client_hlc. It only implies node_id identifies the target through the operation context. The description fails to 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 'Soft-delete an env_sync graph node' using a specific verb and resource, and elaborates the mechanism (sets deleted_at, .live scope hides it from reads). This distinguishes it from sibling tools like graph_write or sync_delete.

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

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

The description implies usage for soft-deleting graph nodes by explaining soft-delete semantics and idempotency, but it does not explicitly state when to use this over alternatives or when a hard delete might be appropriate. The context is present but no exclusions are given.

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 context beyond annotations: it declares the operation non-destructive, aligns with destructiveHint=false, and explains the consolidated handler surface. It clearly defines that action determines the required parameters, providing operational transparency. 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 compact, with the main purpose front-loaded. It uses parenthetical notes and a clear action-to-required-fields mapping. Every sentence adds value without redundancy.

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

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

For a tool with 8 parameters, two actions, and nested field_updates, the description provides essential context for correct invocation: action-specific requirements, non-destructive behavior, and separation from deletion. It doesn't detail return values (no output schema) or client_hlc mechanics, but covers the most important operational aspects.

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

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

Although schema coverage is 100%, the descriptions in the schema are only tags like '[add]' and '[update]'. The tool description enriches parameters by specifying which fields are required per action (e.g., add requires node_type, alias, payload, device_id). This adds critical 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 'Add or update a graph entity (non-destructive)' with specific verbs and resource. It distinguishes from the sibling graph_soft_delete by explicitly mentioning deletion is a separate tool. The action parameter add|update further clarifies the dual purpose.

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

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

It explicitly says deletion is handled by graph_soft_delete, providing an alternative. It also gives required fields per action (add vs update), which guides when to use each mode. However, it does not mention when to use graph_read for reading, though this is implied by context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the 'consolidated surface' note indicating compatibility with legacy tool handlers, but does not disclose output shape, pagination behavior, or other runtime characteristics.

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

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

The description is two short sentences that front-load the purpose. The second sentence packs action modes, legacy compatibility, and parameter requirements into a single run-on, but still avoids 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 large parameter count and no output schema, the description remains minimal. It does not explain what a successful response contains, differences between get/list return shapes, or default behaviors (like limit=50, which lives in the schema). The schema picks up much of the slack, but the description could better orient the 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?

The schema documents all 11 parameters (100% coverage), but the description adds critical conditional logic: that 'project' and 'topic' are required when action=get. This is not encoded in the JSON schema's required array, so it meaningfully augments 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 opens with a specific verb ('Read') and resource ('session handoffs'), clearly distinguishing it from the write-tool sibling 'handoff_save'. Mentioning the get/list actions adds operational 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 implies the tool is for reading handoffs but provides no explicit comparison to alternatives or when-not-to-use conditions. It states required parameters per action but not situational guidance (e.g., prefer this over memory_read for handoff data).

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

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

Beyond the annotations (write, idempotent, non-destructive), the description discloses the exact file path pattern, default date behavior, time suffix disambiguation, and a WAF-bypass technique. This adds substantial behavioral context that is not present in 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 dense and includes an example and a WAF tip, but the content is directly relevant and well-structured. It is not overly verbose given the amount of critical information conveyed.

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

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

The description is highly detailed regarding storage, naming, and parameter behavior, but it does not mention the return value or post-save confirmation. Given no output schema, a brief note on what the tool returns would be beneficial for 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%, but the description goes further by explaining the `time` parameter's effect on the filename with a concrete example, the default behavior for `date`, and the `content_b64` alternative to `content`. This enriches the schema's basic type 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 opens with a specific verb+resource: 'Save a session handoff note for cross-device / cross-session continuation.' It clearly identifies what the tool does and distinguishes it from sibling tools like handoff_read.

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

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

The description provides clear context for when to use the tool (saving handoffs for continuity) but does not explicitly mention alternatives or exclusions. The sibling list includes handoff_read, implying the read counterpart, but explicit cross-referencing would make the guidance stronger.

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

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

Annotations already cover read-only and non-destructive behavior. The description adds useful context beyond annotations, such as the default ordering (risk_tier ascending, then arrival order) and the semantic interpretation of risk_tier 1 pending. No contradiction with annotations.

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

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

The description is two sentences, tightly worded, and front-loads the primary purpose. Every clause adds value, including the L3 layer qualifier and the ordering note.

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 and 7 optional parameters, the description sufficiently covers the tool's scope, use case, and ordering. It does not explain the return shape, but the schema covers filters, and the safety profile is fully handled by annotations.

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

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

Schema description coverage is 100%, so each parameter is already described structurally. The tool description adds no additional parameter-specific detail, though it mentions the overall default order which is related to behavior rather than parameters.

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

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

The description states a specific verb ('List') and resource ('judgments') with a clear scope ('the authenticated user's own judgments, L3 layer'). It distinguishes itself from the sibling judgment_submit by being the read-only listing counterpart.

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 guidance: 'use this to check your own blocking status' and explains the significance of 'risk_tier 1 pending = execution blocked'. However, it lacks explicit when-not-to-use or alternative 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?

Beyond annotations (which only say readOnly=false, destructive=false), the description reveals critical behaviors: decisions are always created as 'pending', only humans decide them, risk_tier controls urgency with specific consequences (blocks execution, auto-proceed after wait, auto-expire after 24h), and passing `decision` is rejected. This is rich behavioral context not present in 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 in three paragraphs, each serving a distinct purpose: (1) core function and uniqueness, (2) critical constraint and follow-up, (3) risk_tier semantics. It is front-loaded with the most essential information and contains no redundant or filler content; every sentence earns its place.

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

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

Given 7 parameters, no output schema, and minimal annotations, the description provides comprehensive context: purpose, workflow, constraints (decision rejection), risk_tier behavior, and how to verify completion (judgment_list). It equips the agent to invoke the tool correctly and understand downstream effects, despite lacking explicit 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 covers all 7 parameters (100% coverage), so baseline is 3. However, the description adds meaning beyond the schema by explaining the behavioral impact of `risk_tier` (1 blocks, 2 reversible, 3 auto-expires) and explicitly warning against a non-schema parameter `decision`. This supplementary guidance raises the score.

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

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

The description clearly states the tool's function: 'Request a human judgment (L3 layer) by attaching evidence — approval, evidence, or verdict.' It specifies the exact resource (human judgment queue) and action (request/submit), and distinguishes it as 'the ONLY door an agent has into the judgment queue' from siblings like judgment_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?

It explicitly indicates when to use this tool (when human judgment is needed) and warns against passing `decision`, stating it is rejected with an error. It also directs to 'Use judgment_list afterwards' to check decision status, providing a clear alternative and follow-up workflow. This satisfies explicit when/when-not/alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds return field details (id/title/content_preview/category_id/created_at) and mentions supported features, which is useful and consistent 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 two sentences, front-loaded with the purpose, then enriched with concrete use-case examples. Every word earns its place; no filler or redundancy.

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

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

With no output schema, the description compensates by listing return fields. It covers the tool's functionality, use cases, and is sufficiently complete for a read-only list operation with well-documented parameters. Slight gap: doesn't mention default pagination or sort order, but those are in schema defaults.

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 of the 8 parameters fully described, so baseline 3 applies. The description mentions capabilities like search and sorting but adds no new parametric semantics beyond what the schema already provides.

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

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

The description clearly states the tool lists notes/papers from AI Note, with specific capabilities like keyword search, category filtering, pagination, and sorting. This distinguishes it from other read-oriented sibling tools by naming the exact resource (AI Note notes).

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 use-case examples ('find my note about X', 'what did I write on Y') and indicates when to search the knowledge base. It does not explicitly mention when not to use it or name alternatives, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'consolidated surface — same handlers as legacy tools' context, which is minor implementation detail, but it does not disclose behaviors like return format or pagination. No contradictions exist.

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 compact sentences with no filler. It front-loads the core purpose and immediately provides the key operational constraints, earning high marks for 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?

The tool has 9 parameters and rich schema descriptions, and annotations cover safety. The description fills in per-action requirements and notes legacy handler equivalence. However, without an output schema, it does not describe return values, which is a minor gap for a read/search 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%, providing detailed parameter descriptions. The description adds value by clarifying per-action requirements (get requires source, search requires query) and noting consolidated handlers, which is not fully evident from the schema's generic 'action' description.

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 agent memory and lists the two actions (get/search), giving a specific verb and resource. However, it does not explicitly differentiate from sibling read tools like handoff_read or graph_read, though 'memory' is distinct enough to avoid confusion.

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

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

It states required parameters per action ('get: source | search: query'), which is useful operational guidance. But it does not provide explicit guidance on when to use this tool versus alternatives or mention exclusions, so usage context is only implied.

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

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

The description adds meaningful context beyond the annotations: it notes the 'L2 intent layer' and explains the 'riskiest_assumption' field's semantics (highest-priority unverified assumption). This helps the agent understand what data to expect, complementing the readOnlyHint and idempotentHint annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, and every part adds value. The clarification about 'riskiest_assumption' is useful without being verbose.

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

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

For a read-only list/fetch tool with no output schema, the description adequately explains what the tool does and what the response includes. It could mention pagination or ordering, but given the simplicity and the annotations, it's reasonably complete.

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

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

Schema documentation covers both parameters (id and status) 100%, so the description doesn't need to add much. It does implicitly mention 'by id' but not the status filter; however, since the schema is complete, the baseline of 3 applies.

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

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

The description clearly states the tool's function: listing the authenticated user's projects or fetching one by ID. It specifies the resource (projects) and the operations (list/fetch), and the 'L2 intent layer' qualifier helps distinguish it from other project-related 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 gives clear context for use: it targets the authenticated user's projects and supports either listing all or fetching by ID. It does not explicitly name alternatives or exclusions, but the read-only nature and resource focus make the intended usage apparent.

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 (write operation), destructiveHint=false, and idempotentHint=false. The description adds valuable context by explaining the create vs. update behavior and the lack of a delete tool, which reveals the intended retirement path. It does not cover partial update semantics or return values, but the annotations provide the safety profile.

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

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

Two sentences, front-loaded with the core purpose, then the essential create/update distinction, followed by the deletion note. Every sentence earns its place with zero filler.

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

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

For a write tool with no output schema, the description covers the core function, the conditional parameter behavior, and the deletion alternative. It omits mention of return values or error handling, but these are not essential for a simple CRUD operation and the annotations provide the behavioral safety 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by clarifying the conditional role of `id` and highlighting the `status: archived` usage for retirement, which supplements the schema's per-property 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 'Create or update a project (L2 intent layer)' with a specific verb and resource. The distinction between create and update via the `id` parameter is explicit, and the note about there being no delete tool differentiates it from potential deletion operations.

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

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

It provides explicit conditional guidance: 'Omit `id` to create, pass it to update.' It also offers an alternative for retirement: 'There is no delete tool — use status: archived to retire a project.' This directly addresses when to use the tool and how to handle deletion without a dedicated 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?

Discloses critical behaviors beyond annotations: the summary body is not stored, only an HMAC digest; the server may skip writes while still returning success depending on environment configuration. Annotations only show boolean flags, so this adds significant 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 sentences, front-loaded with the main action, and every sentence provides useful context (purpose, data handling, operational condition). No filler or redundancy.

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

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

Despite no output schema, the description explains the write condition, data preservation limitations, intended callers, and typical use case ('why was this blocked?'). Sufficient for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats the HMAC behavior already in the schema's summary parameter description and adds no additional parameter-specific meaning.

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

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

The description clearly states the action: 'Record the result of a client-side Layer 5 codex review (sync.py merge gate) as a vault_events row.' It uses a specific verb and resource, and references sync.py hooks, distinguishing it from generic sync/vault tools.

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

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

It provides explicit usage context ('Used by the sync.py SessionStart hook + merge command') and a condition for when writes occur (env var + HMAC secret), but does not name alternative tools or provide an explicit 'do not use when' list.

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

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

Annotations already declare destructive=true and idempotent=true, but the description goes further: it specifies the 'primary vault', explains the CAS mechanism for concurrent multi-PC writes, lists protected paths that require base_sha or force, and notes that deleting a non-existent path returns deleted:false. This exceeds annotation coverage.

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, with the main purpose first, followed by parameter-related details and idempotency. Every sentence conveys essential information without redundancy; it is appropriately compact for the 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 (CAS, protected paths, audit, idempotency), the description covers the essential behavior and constraints. Parameter details are already in the schema, and the description adds the high-level semantics needed to understand when and how to use the tool.

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

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

All four parameters (path, force, base_sha, device_id) are fully described in the schema, so baseline is 3. The description adds meaning by linking base_sha to CAS write conflict detection and force to protected-path bypass, which clarifies how the parameters relate to each other.

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

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

The description opens with 'Delete a file from the primary vault', a specific verb and resource that clearly states the operation. It also distinguishes from sibling delete tools by mentioning CAS, protected paths, and idempotency, making the scope unambiguous.

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

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

The description provides context for using base_sha and force parameters—protected paths require them—and notes idempotent behavior. However, it does not explicitly name alternatives or state when to choose this tool over sibling delete tools like delete_dev_doc or delete_task, so guidance on tool selection is implied rather than 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?

The description goes well beyond the annotations (which already indicate destructive and idempotent behavior). It discloses the conflict detection mechanism (-32009 on base_sha mismatch), the advisory nature of dedup_candidates with explicit decision options, and the WAF-bypass behavior with content_b64. This provides the agent with crucial response behavior and decision framework.

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 structured with purpose first, followed by CAS, WAF bypass, and dedup guidance. It is dense but each sentence conveys necessary information. It could be slightly more concise by trimming redundant mentions of content_b64, but it remains efficient for a tool with this 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 (8 params, CAS, dedup, WAF) and lack of output schema, the description covers most behavioral aspects: response elements like dedup_candidates and -32009 are mentioned, and the push decisions are explained. However, it does not describe normal success response fields or edge cases like supports_superseded, which are left to the schema. Still, it is largely complete for agent selection and invocation.

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

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

The input schema has 100% coverage with detailed descriptions for all 8 parameters, including content_b64, base_sha, force, and resolves_conflict_id. The description reinforces some points (e.g., content_b64 for WAF bypass) but does not add substantial meaning beyond the schema. The baseline of 3 is appropriate since schema does the heavy lifting.

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

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

The description clearly states the tool's core function: 'Push a markdown file into the primary vault.' This is a specific verb (push) and resource (markdown file into vault), distinguishing it from siblings like sync_read or sync_delete. It also introduces CAS and dedup features, which further clarifies its role in the sync ecosystem.

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

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

The description provides clear context on when to use CAS (concurrent multi-PC writes), when to use WAF-bypass (large bodies ~10KB+), and how to handle dedup_candidates. It implies usage for single-file pushes, distinct from sync_push_batch. While it doesn't explicitly name alternatives or exclusions, the guidance is actionable and context-rich.

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 define idempotentHint=true and destructiveHint=true, and the description enriches these with crucial behavioral details: partial success returns HTTP 200, results must be matched by path not position, conflict results carry remote_sha and conflict_reason, request-level failures apply nothing, and content_sha powers integrity checks and retry-safe skipped_identical. This goes well beyond the annotations without contradicting them.

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

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

The description is dense but every sentence carries essential operational information. It is front-loaded with purpose and usage, then systematically covers partial success, conflict handling, failure scenarios, and dedup logic. No filler or repetition — size is justified by the tool's complexity.

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

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

For a batch mutation tool with no output schema, this description is exceptionally complete. It explains success/partial-failure semantics, request-level failure behavior, item constraints, retry safety, conflict resolution path, and dedup caveats. It leaves no major operational question unanswered.

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

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

The schema already describes all parameters, but the description adds significant meaning. It explains that content_sha is 'SHA1 hex of the decoded body' and drives both integrity and 'skipped_identical' behavior. It details idempotency_key semantics (reuse for retries, new key for changed items, collision on mismatch), and batch-level constraints like duplicate paths and size limits. This transforms the schema from a data dictionary into operational 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 begins with 'Push MANY files into the primary vault in ONE call,' using a specific verb (Push), resource (files), and scope (MANY, primary vault). It explicitly contrasts with sync_push by advising to use it 'instead of looping sync_push,' which immediately distinguishes it from its sibling tool.

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?

Clear usage guidance is provided: 'Use this instead of looping sync_push whenever you have more than a couple of changed paths — the cost of sync_push is round trips, not bytes.' This explicitly states when to use the tool and references the alternative. It also cautions about partial success and request-level failure conditions, giving operational context for choosing this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a note about being a 'consolidated surface' but no meaningful behavioral details like return format, merge semantics, or pagination behavior.

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

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

The description is relatively compact but somewhat run-on and includes an extraneous parenthetical about legacy tools that adds noise. It could be better structured by separating the action list, the write-tool note, and the requirements into clearer sections.

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 8 parameters, no output schema, and five distinct actions, the description lists the actions but does not explain what each action returns or its side effects (e.g., what 'merge' does with the provided texts, what 'conflicts' returns). The schema parameter descriptions help but are not sufficient to fully understand the tool's behavior.

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

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

The schema already provides per-parameter action qualifiers, but the description adds explicit required-per-action mappings (diff: path | merge: path, base_text, local_text), which is valuable clarification beyond the schema. This helps the agent know which parameters are mandatory for each action.

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 'Read-only vault sync operations' and enumerates the five actions (list, pull, diff, merge, conflicts). It explicitly distinguishes from sibling write tools (push/delete), making it unambiguous what this tool does and how it differs from others.

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 notes that writes are separate tools with CAS semantics, which helps guide selection away from sibling write tools. However, it does not provide nuanced guidance on when to choose one action over another (e.g., when to use diff vs pull), leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description does not need to repeat those. It adds minimal extra context like 'consolidated surface — same handlers as the legacy tools,' but does not disclose response shape, pagination behavior, or filtering nuances beyond what the schema already covers.

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 short and front-loaded with the core purpose. The parenthetical about consolidated surface and legacy tools adds context but is slightly jargon-heavy; still, it remains efficient with no redundant 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 plus the fully covered input schema and safety annotations provide enough context to invoke the tool correctly. A gap is the lack of an output schema or mention of return format, but the read-only nature and rich parameter descriptions keep this adequate for a complex 19-parameter 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 every parameter described in the input schema. The description only restates the action enum ('tasks | categories'), which is already documented in the schema, adding no new semantic value for the remaining 18 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 reads tasks and task categories, with a specific action parameter distinguishing the two operations. This distinguishes it from mutation siblings like task_write 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?

The description implies usage for read-only operations via the verb 'Read', but it does not explicitly specify when to use this tool versus alternatives like task_write or delete_task. The 'consolidated surface' note hints at replacing legacy read tools but provides no concrete when/when-not guidance.

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

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

The annotations already convey that the tool is non-destructive (destructiveHint false) and not read-only. The description adds useful context: it explicitly states 'non-destructive,' notes that the tool is a 'consolidated surface — same handlers as the legacy tools,' and clarifies that deletion requires a different tool. It also discloses action-dependent requirement structure. This goes beyond what annotations alone provide, though it does not delve into side-effect details like notifications or field-clearing behavior.

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

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

The description is compact (around 40 words) and front-loads the primary purpose. Every element contributes value: the main verb phrase, the action enum, the deletion alternative, the legacy-tool context, and the required-fields summary. The structure is somewhat choppy with parenthetical fragments, but it remains efficient and scannable.

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 (19 parameters, action-dependent behavior), the description provides a solid high-level overview: main operation, non-destructive nature, separation of deletion, and per-action requirements. It does not enumerate all parameters (relies on schema for that), but it covers the critical decision points. Slightly more explicit guidance about integration with tasks_read or update semantics (like 'null' to clear) would improve completeness, but the schema already handles those 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 100%, so the baseline is 3. The description adds a concise summary of required fields per action ('create: content | update: id'), which is a helpful extraction and reduces cognitive load for a 19-parameter tool. While each parameter is already described in the schema with [create]/[update] tags, the description's rule-of-thumb makes it easier to quickly understand the action-dependent requirements.

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 core function: 'Create or update a task (non-destructive).' It specifies the action parameter values (create | update) and distinguishes from sibling tool delete_task by explicitly noting it is a separate tool for deletion. This provides a specific verb+resource with clear differentiation.

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

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

The description gives usage guidance by specifying required fields per action ('create: content | update: id') and names an alternative tool for deletion ('Deletion is a separate tool (delete_task)'). However, it does not explicitly mention when to use this tool versus tasks_read for reading, but the tool name and write-focused description make this implicit. It could be strengthened with a direct 'for reading, use tasks_read' exclusion, but current guidance is adequate.

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 readOnly=false and openWorldHint=true. The description adds concrete behavioral context: the creation happens as a GitHub repository under the user's account, and it requires the GitHub App install flow. This goes beyond the annotations by specifying the external side effect and auth prerequisite.

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

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

The description is two sentences, front-loaded with the core action, and contains no filler. Every phrase (private, GitHub repository, under user's account, install flow) adds necessary context.

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

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

Given no output schema, the description does not describe return values, but for a create tool this is a minor gap. It covers what is created, where, and the key prerequisite. Sibling context and annotations fill remaining gaps, making it fairly complete.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters (name, slug, description). The description adds no additional parameter information, so the baseline of 3 applies.

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

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

The description clearly states the verb 'Create' plus the resource 'new private vault as a GitHub repository under the user's account.' It distinguishes from sibling tools like vault_read and vault_sync by specifying creation of a private GitHub repo.

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 ('Requires the user to have completed the GitHub App install flow first'), which is important usage context. It does not explicitly list alternatives or when-not-to-use, but the create semantics versus siblings (read/sync) are evident.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate safety. The description adds the 'consolidated surface' compatibility note but does not disclose additional behavioral consequences, such as what happens if an action fails or whether any state changes occur (which aligns with the read-only 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 compact and information-dense, with two sentences covering the purpose, action list, consolidated nature, and a key conditional requirement. No redundant phrasing or filler.

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

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

For a 4-parameter tool with no output schema, the description plus schema provides sufficient operational detail: actions, conditional requirements, and parameter meanings. It lacks explicit return-value descriptions, but the read-only annotation and action semantics make the tool's behavior predictable.

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%, providing baseline parameter descriptions. The description adds value by specifying a conditional requirement—'Required per action — clone: name'—which is not captured in the schema's simple required list. This helps agents understand action-specific parameter usage.

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 vault metadata and enumerates the three available actions (list, clone, status). It distinguishes itself from sibling tools like vault_create and vault_sync by focusing on read operations, and the phrase 'consolidated surface' indicates it is the unified read interface.

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 contexts by listing actions and noting that clone requires a name, but it does not explicitly state when to use this tool versus alternatives. It mentions 'same handlers as the legacy tools' which hints at replacing them, but no direct when/when-not guidance is 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 indicate destructiveHint=true and openWorldHint=true, so the mutability and side-effect potential are known. The description adds the primary-vault scope and WAF-bypass mechanism for push, but does not describe other behavioral traits such as whether pull overwrites local files or exactly what push modifies.

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, front-loaded with the tool's purpose. Each sentence contributes essential information—wrapper identity, action enum, and push-specific WAF-bypass—with no filler or redundancy.

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

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

The tool has multiple actions and no output schema, yet the description does not explain return formats or per-action behaviors (e.g., what list returns or what push responds with). It also omits prerequisites like authentication or vault-access requirements, leaving the agent under-informed for complex usage.

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

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

Schema description coverage is 100%, with each parameter already explained in detail. The description's mention of content_b64 and the content prefix duplicates schema information, adding no new parameter semantics beyond what the schema provides.

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

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

The description clearly states it is a wrapper around vault file sync with explicit actions (list, pull, push) against the primary vault. This distinguishes it from sibling tools like sync_push or vault_read, and the WAF-bypass note for push adds specificity.

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

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

The description implies usage as a general wrapper for vault sync operations and mentions 'mirrors sync_push' for push, but it does not explicitly state when to prefer this tool over dedicated siblings like sync_read or sync_push, nor does it provide exclusion criteria.

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