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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's non-destructive claim is consistent. It adds valuable context beyond annotations: 'Packet bytes remain retained for audit and this tool never deletes them,' which reassures the agent about side effects.

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

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

The description is two concise sentences, front-loaded with the core action. Every clause earns its place, and it avoids redundancy with the schema or annotations.

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 acknowledgement tool with only two parameters (one required) and an output schema present, the description covers the purpose, the preconditions, and the key safety behavior. There are no critical gaps for an agent to invoke it correctly.

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

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

The schema description coverage is 100%: both actorName and deliveryId have clear descriptions. The tool description itself adds no parameter-specific meaning, but the schema fully documents the parameters, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Mark') with a clear resource ('delivery as acknowledged') and explicitly lists valid prior conditions ('reviewed, imported, or intentionally skipped'). This distinguishes it from siblings like list_inbox, get_inbox_delivery, and pull_inbox_packet.

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 (after a delivery has been reviewed, imported, or intentionally skipped). It does not explicitly name alternatives or exclusions, but the condition is unmistakable, giving the agent enough guidance to select it appropriately.

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 readOnlyHint/destructiveHint annotations, the description discloses that the tool is deterministic, never repairs records, and only covers private records when the server runs with --include-private. It also clarifies the error/warning levels and recovery text, adding significant behavioral context not captured by annotations.

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

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

The description packs a high amount of useful information into two sentences, front-loaded with the primary use case. Every phrase adds value, such as the error/warning distinction and the privacy caveat, with no wasted words.

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

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

Given the tool's simplicity (no params, no output schema), the description covers all relevant aspects: purpose, trigger conditions, behavior, and alternatives. It even mentions the --include-private flag and recovery text, making it a complete guide for 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 tool has zero parameters, so the schema is empty. The description cannot add parameter semantics beyond the schema; baseline 4 applies since no parameters need explanation.

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: it reports broken supersedes and replyTo references, self-references, supersedes cycles, and competing forks. It also distinguishes itself from run_doctor, which handles directory, secret, and audit-log checks, providing clear differentiation from siblings.

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

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

Explicitly advises use after imports or before trusting a supersedes or reply chain, and directs users to run_doctor for alternative checks. This gives both when and when-not guidance, fully satisfying the criterion.

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 (which indicate a non-read-only, non-destructive write), the description adds meaningful context: it stores only what is passed and never reads chat history, and it refuses scope files outside the project root or content flagged by the secret scanner. This is valuable safety/privacy transparency 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?

Two sentences, front-loaded with the purpose trigger and then providing key behavioral constraints. Every word earns its place; no fluff or repetition of schema content.

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 12 parameters, no output schema, and nested objects, the description gives enough orientation: what it creates, where, what it returns (record with path), and key acceptance/rejection rules. It does not need to enumerate parameters because the schema handles that, and the return type is summarized adequately.

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

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

Schema description coverage is 100%, so all 12 parameters are already well-documented in the input schema. The description adds no new parameter-specific semantics, merely restating the scope-file constraint already in the schema. Baseline 3 applies due to full 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 uses a specific verb (“writes”) and resource (“brief Markdown record”) with a location (.notch/briefs/), clearly stating what the tool does. It also frames it as “scoped task written down for another agent or session,” which distinguishes it from sibling tools like create_packet, though it does not explicitly name alternatives.

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

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

The description opens with “Use when the user wants a scoped task written down for another agent or session,” providing a clear trigger condition. It does not explicitly state when not to use it or name alternative tools, but the context is strong enough for basic routing among siblings.

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

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

Description adds significant behavioral context beyond the annotations: it reveals the write location (.notch/private/inbox/), states the packet is never sent anywhere, and notes it stays hidden from packet listings unless --include-private is passed. This is meaningful transparency for a write operation, going well beyond the annotations.

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

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

Two sentences deliver the use case, storage destination, and visibility behavior with zero filler. The purpose is front-loaded in the first sentence, making it immediately 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 (6 params, no output schema), the description covers the essential workflow: what it creates, where it is stored, and its private nature. It does not state the return value, but for a simple creation tool this is a minor gap.

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

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

Schema description coverage is 100%, so the schema fully documents all six parameters. The description adds no additional parameter-level detail beyond the schema, meeting the baseline but not exceeding it.

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

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

The description clearly states the tool is for self-addressed captures (preference, decision, or note) with no recipient, and specifically says it writes a private seed packet to .notch/private/inbox/. This verb+resource+scope distinguishes it from siblings like create_packet, create_reply, and create_seed_packet, which involve sending or other packet types.

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

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

Opens with 'Use for a self-addressed capture,' providing clear context for when to invoke this tool. However, it does not explicitly name alternatives or exclusion criteria, though the private/no-recipient framing implicitly contrasts with other create 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 only indicate non-read-only, non-destructive, and non-open-world behavior; the description adds substantial transparency: writes to the outbox, copies files as artifacts, requires at least one recipient, secret-scans content before writing, and does not transmit. This goes well beyond the structured hints and provides the key side-effect and safety context an agent needs.

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

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

Two sentences, front-loaded with the primary use, and every clause earns its place: the outbox write, artifact copying, returned path, recipient requirement, secret-scan, and no-transmission behavior. No filler or repetition of schema details.

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

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

For an 18-parameter tool with no output schema and minimal annotations, the description gives a solid workflow overview and critical constraints, but it does not address the seed variant, private vs project outbox, or error/warning behavior such as NOTCH_SUMMARY_LARGE. The rich schema compensates for most parameter-level details, so the gap is modest.

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 covers all 18 parameters with individual descriptions, so the baseline is 3. The description adds meaningful high-level constraints not explicit in the schema's required list: at least one recipient field is mandatory, and 'copies any listed files in as artifacts' ties the files parameter to the described behavior. It doesn't elaborate on individual parameter syntax because the schema already handles that.

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

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

The description opens with a specific action ('capture the current working state as a portable packet'), then details exact mechanics: writes a Markdown record to the store outbox, copies listed files as artifacts, and returns the packet with its path. It distinguishes create_packet from send_packet by noting 'creating a packet transmits nothing — packing and sending are separate steps.'

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 when to use the tool: when you need to capture working state for another session, tool, or repo, and explicitly states that no transmission occurs, implying sending is a separate step. However, it does not name sibling tools like send_packet or create_seed_packet as alternatives, so exclusions are implied rather than explicit.

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

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

The description adds meaningful behavioral context beyond the annotations: the parent is never modified, the reply is a new linked packet, and the privacy behavior for private/seed parents or when private is set. With readOnlyHint false, these details help the agent understand the write semantics. 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, front-loaded with the action, and each sentence conveys important information. The second sentence is dense but not wasteful, earning a 4 rather than 5 due to slightly complex structure.

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 14 parameters and no output schema, the description covers the essential behavioral aspects: what the tool does, the parent link, non-modification of parent, and privacy rules. It could mention what the reply packet contains or the expected result, but the description is sufficiently complete for a write operation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the parentId matching requirement and the private default behavior, which complements the schema's description of the 'private' parameter. This extra context justifies a 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: answering a specific packet by writing a new linked reply packet rather than editing the parent. It enumerates the reply types and distinguishes from editing, giving a clear, specific purpose that differentiates it from sibling tools like create_packet.

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 usage context: use this to reply to a packet instead of editing it, with explicit requirements (parentId must match exactly one record) and privacy rules. However, it doesn't explicitly name alternative tools or state when not to use it, though the 'instead of editing' implies the contrast.

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

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

Annotations indicate readOnlyHint=false, so write behavior is known. The description adds the concrete write target (.notch/private/outbox/), the purpose/sensitivity values written, and the fact that the packet stays local and unimported until import_seed_packet runs. This goes beyond annotations by explaining the lifecycle and destination.

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 usage condition, then precise destination and lifecycle. No 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 10-parameter tool with no output schema, the description covers the key outcome (write to specific path), usage condition, and lifecycle. It doesn't mention return behavior or the ignored-parameter nuance, but the schema covers parameters. Adequate but not exhaustive.

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

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

Schema has 100% parameter description coverage, including notes that several fields are accepted but not recorded. The description itself adds no parameter detail beyond referencing title and summary. Baseline 3 applies because the schema fully documents 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 creates a private seed packet for durable private context, writes it to .notch/private/outbox/, and distinguishes it from handing context to someone else. Specific verb (writes), resource (seed packet), and scope (private, local) are all present.

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 an explicit usage condition: 'Use when the user wants durable private context... for a future session rather than handed to someone else.' This gives clear when and when-not, though it doesn't name a specific alternative tool. It also mentions import_seed_packet as the complementary import step.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scope 'default project brief' but does not disclose return format, error behavior, or other operational details. With annotations present, a score of 3 reflects the minimal additional 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 a single, concise sentence that immediately conveys the tool's purpose. No unnecessary words or repetition; it is appropriately front-loaded.

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

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

For a simple read-only tool with one optional parameter and strong annotations, the description is mostly adequate. However, it does not explicitly state the return value (e.g., parsed record) despite having no output schema. The parameter schema hints at the parsed record, so the gap is minor.

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 sole parameter includeMarkdown is fully documented in the schema (100% coverage), explaining its effect and default. The description itself does not discuss parameters, but the baseline is 3 due to 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 uses the specific verb 'Read' and the resource 'default project brief', clearly stating its action. The word 'default' distinguishes it from the sibling 'get_targeted_brief' and 'list_briefs'.

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 (read the default brief) but does not explicitly state when to use this tool versus alternatives like get_targeted_brief or list_briefs. No exclusions or alternative references are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description complements these by explaining the 'retained' nature of the delivery state and the optional address behavior. It adds context about what the state represents (pulled, acknowledged, rejected) without contradicting the annotations.

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

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

The description is a single, tightly-worded sentence that front-loads the core action ('Read retained delivery state by ID') and then adds the optional address nuance. Every word contributes meaning, with no repetition or filler.

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

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

Given the tool's simplicity (2 params, annotations, and an output schema), the description fully covers the key context: what it reads, how the optional address works, and the intended use case. The output schema handles return values, so no further explanation is needed.

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 provides 100% parameter coverage with detailed descriptions for both 'address' and 'deliveryId'. The description adds a brief purpose for the address parameter ('so the sender can see...'), but this largely mirrors schema text. Since the schema already explains parameter semantics thoroughly, the description adds marginal value, placing it at the baseline of 3.

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

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

The description clearly states the action ('Read retained delivery state by ID') and the specific resource ('delivery state'), immediately distinguishing it from sibling tools like list_inbox or get_status. It also explains the optional address parameter's role, making the tool's purpose unambiguous.

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

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

The description provides clear usage context: it is for reading a specific delivery's retained state, particularly so the sender can check pulled, acknowledged, or rejected status by passing the recipient's address. While it doesn't explicitly name alternative tools or exclusions, the use case is well implied and distinct from list_inbox (which lists deliveries) or get_status (which likely reports overall store status).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with these. The description adds the 'by ID or slug' lookup detail but does not disclose failure behavior (e.g., match exactly one packet) or other nuances beyond what the schema already provides. No contradiction, but little added 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 a single, front-loaded sentence that communicates the verb, resource, and lookup mechanism with zero redundant words. 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 read-only tool with a rich parameter schema and clear annotations, the description is mostly complete. It omits return-value details (as there is no output schema), but the verb 'Read' implies returning the packet record, and all parameter behaviors are covered in the schema. Some nuances, like server-flag dependency for includePrivate, are left to the schema, which is acceptable.

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 detailed parameter descriptions for id, direction, includePrivate, and includeMarkdown. The description's 'by ID or slug' merely paraphrases the id parameter and adds no new meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb ('read') and resource ('packet'), and specifies the lookup key ('by ID or slug'), which distinguishes it from sibling tools like list_packets (enumeration) and get_brief (different resource). It is a precise, minimal definition of the tool's purpose.

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

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

The description implies use when fetching a single packet by identifier, but it does not explicitly state when to use this tool over alternatives such as list_packets or get_brief. No exclusions or alternative references are provided, leaving the choice to the agent's reasoning.

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

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

Annotations already declare read-only and non-destructive nature, but the description adds critical behavioral details: private seed packets are counted but their contents are never returned, and the includeWarnings parameter is always ignored. This goes beyond the annotations, giving the agent a clear safety and privacy 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 well-structured sentences. The first is front-loaded with the purpose and lists all return contents efficiently; the second clarifies privacy behavior. Every clause delivers useful information with no redundancy.

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

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

Despite lacking an output schema, the description thoroughly enumerates what is returned (counts, newest packets, briefs, warnings) and notes exclusions (private packet contents). For an orientation tool, this is complete enough for an agent to know exactly what to expect.

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 already fully describes the only parameter (includeWarnings) with the same 'accepted but not applied' note, so the description adds no new meaning. Baseline of 3 is appropriate because schema coverage is 100% and the description doesn't extend the parameter understanding.

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

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

The description clearly states the tool returns a status overview: project name, store path, counts, newest packets, briefs, and warnings. It positions itself as an orientation tool ('Read first'), distinguishing it from sibling tools that handle specific operations like creating or listing items.

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

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

Explicitly instructs to 'Read first for orientation', signaling this should be used before other tools. This provides a clear when-to-use directive, which satisfies the criterion for explicit usage guidance even without naming specific alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details: the call fails rather than guessing on no/multiple matches, and includeMarkdown optionally returns rendered Markdown. This goes beyond what annotations provide.

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

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

Two sentences with no wasted words. The first sentence states the core action and context, the second covers the optional parameter and failure behavior. Every clause earns its place.

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

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

For a simple read-only tool with 2 parameters, full schema coverage, and annotations, the description adequately covers purpose, usage, and failure mode. It does not detail the response structure, but 'in full' and 'parsed record' provide sufficient context. A 5 would require more explicit return format 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 description coverage is 100%, and the parameter descriptions already cover the meaning of id (record ID or stored filename stem) and includeMarkdown (true returns Markdown). The tool description simply restates this information, adding no new semantic value beyond the schema.

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

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

The description uses a specific verb ('Read') and resource ('targeted brief') with identifying criteria ('by record ID or stored filename stem'). It also distinguishes from list_briefs by noting it is used after list_briefs narrows candidates, giving clear workflow context.

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

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

Explicitly states the usual sequence ('after list_briefs narrows the candidates') and when to set includeMarkdown. However, it does not name alternatives (e.g., get_brief) or state when not to use this tool, 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?

The description discloses extensive behavioral traits beyond the annotations: requires absolute path, refuses symlinks, verifies artifact hashes and referenced records, secret-scans content, routes private/seed packets to a specific directory, and refuses duplicate packet IDs without overwriting. This is far more detail than the minimal annotations provide (readOnlyHint false, destructiveHint false, openWorldHint false).

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

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

The description is a single dense sentence but packs a lot of useful information without fluff. It is front-loaded with the primary use case, then lists key behavioral constraints. It is slightly run-on but highly efficient; nearly every phrase adds value.

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

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

The tool is a write/import operation with no output schema, and the description covers the main flow: input requirements, safety verifications, routing rules, and duplicate handling. It omits details about the optional parameters (actorName, asReviewed) but those are documented in the schema. Given the complexity, it is sufficiently complete.

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

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

The input schema already provides 100% coverage with detailed descriptions for all three parameters, including the absolute path requirement and symlink refusal for packetPath. The description adds no new parameter-specific meaning beyond what the schema already says, so the baseline score of 3 is appropriate.

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

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

The description opens with 'Use when the user hands over a packet file or unpacked packet folder from another repo, tool, or machine and wants it in this store,' which clearly states the tool's purpose: importing external packet files/folders. This verb+resource combination ('import packet file/folder') distinguishes it from siblings like create_packet and import_seed_packet.

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 scenario ('when the user hands over a packet file or unpacked packet folder from another repo, tool, or machine') that tells when to use this tool. It does not explicitly name alternatives or exclude cases, but the context is strong enough to differentiate from create_packet. Lacks explicit when-not guidance, so not 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?

The description discloses several key behaviors beyond the annotations: requires absolute path, refuses symlinks, accepts only packets with purpose: seed, always imports to a fixed inbox location, and refuses duplicate packet IDs instead of overwriting. These are important operational details that an agent needs to know. Annotations only state mutation/world-supports/destructive hints, which are consistent with the description.

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

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

The description is a single sentence that packs all essential information without fluff. Every clause adds value: usage trigger, reviewed status, private context, path requirements, purpose restriction, destination, duplicate policy. Excellent front-loading and no wasted words.

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

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

Given the tool's moderate complexity (import with safety constraints) and absence of output schema, the description fully covers invocation context, validation rules, destination, and conflict behavior. No important aspect seems missing; the agent has enough to correctly invoke and anticipate outcomes.

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

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

Schema description coverage is 100%: all three parameters are described in the schema. The description adds some context about absolute path and purpose: seed which is also in schema, but does not add new meaning beyond the schema for actorName or asReviewed. Baseline 3 applies because 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 opens with a specific use case: 'Use when the user points at a seed packet file they have already reviewed and wants that carried-forward private context in this store.' This clearly states the tool's function (import reviewed seed packet) and distinguishes it from generic import_packet or create_seed_packet by focusing on reviewed, private seed packets.

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 'Use when' context and lists constraints (absolute path, refuses symlinks, purpose: seed, imports to .notch/private/inbox/, refuses duplicates). This effectively tells when to use it and what it will/won't accept, but it does not explicitly name a sibling tool as an alternative. Still strong 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=false, and the description adds the concrete side effects: writing local configuration and registering the address. It explicitly states it does not create authenticated identity, which is valuable to prevent confusion with authentication tools. 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: first gives the precondition, second states the action and a clarifying non-action. Every word earns its place, with 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?

The description conveys the core function, precondition, and an important exclusion (no identity creation). With an output schema present and annotations covering read-only/destructive hints, this suffices; it doesn't explore error cases or re-init behavior but is adequate for a simple init 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 descriptions cover 100% of parameters, including that 'name' becomes the local: address and 'root' is an absolute path. The tool description adds no additional parameter-level semantics beyond mapping 'address' to the name parameter, 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 tool initializes a durable inbox by writing local configuration and registering the address for async cross-agent packet delivery. It uses a specific verb ('writes local configuration and registers') and identifies the resource, distinguishing it from packet creation and inbox read tools in the sibling 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?

Explicit precondition 'Use only after the user chooses an explicit local mailbox root and address' tells when it is appropriate to invoke. It does not name alternatives, but the context implies this is a setup step before other inbox operations; also clarifies it does not create identity to prevent misuse.

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 readOnlyHint/destructiveHint annotations, the description discloses key behaviors: 'Returns brief metadata only, never the rendered Markdown', exact matching for targetAgent/status, AND semantics for tag filters, and that all matches are returned unless limit is set. These details are not present in the annotations and help the agent understand output and filter behavior.

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

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

The description is two sentences that front-load the core purpose and then efficiently list behavioral details. There is no redundancy with the schema; every sentence contributes essential guidance.

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 clarifies the return type ('brief metadata only, never the rendered Markdown'), ordering, filter semantics, and limit behavior. Combined with the detailed parameter schema and safety annotations, the agent has enough context to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with each parameter already documented in the input schema (e.g., limit 'unset returns every match', since 'accepted but not applied by the MCP server'). The description's filter statements ('match exactly', 'requires every listed tag') mostly reinforce existing schema text without adding new semantics, so the baseline of 3 is appropriate.

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

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

The description starts with 'List targeted briefs in this store, newest first'—a specific verb, resource, and scope. It further clarifies the purpose by stating 'to find a brief ID before reading one with get_targeted_brief', distinguishing it from sibling tools like get_targeted_brief or get_brief.

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 names the intended use case ('to find a brief ID before reading one with get_targeted_brief') and references the alternative tool. This provides clear when-to-use guidance, and the description also explains when a limit would be set to bound results.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds value by clarifying the default behavior (pending only) and indicating that includeAll should be used sparingly, implying a possible performance or semantic difference.

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

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

Two concise sentences: the first states the primary purpose, the second gives a conditional usage caveat. No redundancy, and the most important information is front-loaded.

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

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

For a simple list operation with a single optional parameter, an output schema, and read-only annotations, the description fully covers the necessary context. It clarifies the default state filtering and the exceptional case without over-explaining.

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 practical usage guidance for includeAll ('only when reviewing history'), going beyond the schema's straightforward boolean explanation and giving an agent a decision rule for when to set it.

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

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

The description clearly states the tool lists pending async packet deliveries for the store, which is a specific verb, resource, and scope. It distinguishes itself from sibling list tools like list_briefs and list_packets by focusing on inbox deliveries.

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 guidance on when to use the includeAll parameter ('only when reviewing pulled, acknowledged, or rejected history'), but it does not explicitly compare against alternative tools like get_inbox_delivery. Still, the context is sufficient for most 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 indicate read-only and non-destructive, but the description goes further by disclosing that packet bodies are never returned, defaults to both directions and at most 50 results, and that private records require a server flag and produce a NOTCH_PRIVATE_HIDDEN warning rather than failing. This adds substantial behavioral context beyond the annotations.

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

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

The description is a compact two-sentence block that front-loads the core purpose and immediately follows with critical behavioral notes. Every clause earns its place, delivering high density without verbosity.

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 and no output schema, the description provides sufficient context: ordering, default limit, direction default, privacy handling, and return content (metadata and paths, not bodies). It also notes the warning behavior for private records. This is complete enough for an agent to use correctly.

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

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

Although the schema covers all parameters, the description adds crucial semantic caveats for 'to', 'since', and 'fromProject' by explicitly stating they are 'accepted but not applied' by the server, requiring client-side filtering. It also clarifies the meaning of 'includePrivate' and its warning behavior. This goes beyond the schema descriptions.

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

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

The description clearly states that the tool lists packets in the store, ordered newest first, and explicitly distinguishes it from get_packet by saying the purpose is 'to find an ID before reading one with get_packet'. It also specifies that it returns metadata and on-disk paths, never packet bodies, giving a precise 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 a clear usage context: use it to find an ID before reading a packet with get_packet. It also explains default behavior and a privacy prerequisite (server flag --include-private). However, it does not explicitly contrast this with the sibling list_inbox tool, so there is no when-not-to-use 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 indicate non-read-only behavior, and the description adds key behavioral details: it runs validation checks and, when importing, does not acknowledge or delete the retained delivery. This goes beyond the raw annotation values by explaining side effects and limitations.

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

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

The description is two sentences long, front-loading the core purpose and then providing a critical clarification. Every sentence earns its place, with no redundant or filler content.

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 presence of a complete input schema, annotations, and an output schema, the description adequately covers the tool's functionality and key behavioral caveats. It could mention the no-write default when import is false, but the schema already covers that, making the description sufficient.

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

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

The input schema already provides 100% coverage with detailed descriptions for all four parameters. The tool description does not add significant new parameter semantics beyond what the schema states, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's primary action: verifying an async delivery by SHA-256 and packet/security checks, with an optional import via the 'import' flag. It distinguishes itself from sibling tools like ack_inbox_delivery by explicitly noting that import does not acknowledge or delete the delivery.

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

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

The description provides clear context for when to use this tool: to verify an inbox delivery and optionally import it. It implicitly excludes acknowledgment/deletion as separate actions, giving a when-not hint. However, it does not explicitly name alternative tools or provide a full decision tree.

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 flag the tool as read-only and non-destructive. The description adds important nuance: it is read-only except for fixDerivedState, which is refused when the server is read-only. This supplements the annotation with actionable safety context without contradicting it.

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 trigger condition, and enumerates checks efficiently. The second sentence clarifies the only mutating option. No wasted words; every phrase carries information.

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

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

The description thoroughly covers triggers and the scope of diagnostics, but there is no output schema and the description does not mention return values, exit codes, or how to interpret results. For a diagnostic tool, this leaves a significant gap in what the agent should expect after 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?

Both parameters (strict and fixDerivedState) are fully described in the schema with details on behavior and defaults. The description adds no additional parameter-level meaning beyond what's already in the schema, so it doesn't compensate beyond the baseline.

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 runs store diagnostics and enumerates exact checks: directories, .gitignore coverage, symlinks, records, secrets, audit logs, and hook drift. It also gives a specific trigger ('when 3Notch behaves oddly or before trusting a store'), making its purpose explicit and effectively distinguishing it from likely sibling 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 explicitly says when to use the tool and provides context for the mutating fixDerivedState option, noting it's refused in read-only mode. It doesn't mention alternative tools like check_store or exclusions, but the trigger condition is clear enough for correct selection.

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

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

The description adds context beyond annotations by explicitly stating this is an 'externally visible write to the configured mailbox' (aligning with readOnlyHint=false and openWorldHint=true) and noting it 'refuses private or seed packets'. This gives the agent important behavioral boundaries not present in the schema or annotations alone.

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

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

The description is two sentences, front-loaded with action guidance ('Use after notch packet pack') and conveys all necessary context without redundancy. Every word earns its place.

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

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

With a complete input schema, output schema, and annotations, the description adds the key contextual detail of when to use this tool in the packet workflow. It is complete enough for correct invocation, though it leaves the meaning of 'private or seed packets' implicit, which is minor given sibling tool names.

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 already documents each parameter thoroughly. The description does not add significant new meaning beyond the schema; it mostly reinforces the schema's explanation of packetPath and to. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'async handoff to a registered local: address in another repo or model client' after 'notch packet pack'. This distinguishes it from sibling tools like get_packet, list_packets, and create_packet, which serve different functions within the packet lifecycle.

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 sequencing ('Use after notch packet pack') and a clear use case ('when the user wants an async handoff'). While it doesn't name alternative tools, the placement within the packet workflow is sufficiently clear, and the constraint against private/seed packets hints at boundary conditions.

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