Vibes-Coded Agent Security and Commerce Tools

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

The description adds behavioral context beyond the annotations by stating 'No auth required. No side effects.' and by describing the JSON response shape. This complements the existing readOnlyHint/idempotentHint/destructiveHint annotations, though rate-limit or failure-mode behavior is not discussed.

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 every sentence earns its place: purpose, usage, exclusions, safety, and return shape are each covered without redundancy. Key information is front-loaded in the first sentence.

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

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

For a zero-parameter health check with annotations and an output schema already present, the description is complete. It covers what the tool returns, when to use it, when not to use it, alternatives, authentication, and side-effect profile.

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 there is nothing for the description to explain about inputs. The baseline of 4 applies because no parameter documentation is needed beyond the empty input 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 opens with a specific verb and resource: 'Return MCP server liveness' and names the exact fields returned (version, origin, tool count, catalog size). It clearly distinguishes health from the vc_*/pay siblings by explicitly saying it is not for business outcomes.

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

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

It states exactly when to use the tool: hosted inspector probes such as Glama/Smithery, or before diagnosing tool failures. It also provides a clear exclusion and alternatives: do not use for business outcomes; call vc_* tools or pay(slug=...) instead.

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 generic annotations, the description discloses real behavioral context: it may settle USDC via x402, can return payment_required with pay_to/amount and fund tips, and is otherwise HTTP-only. This directly addresses side effects and failure modes the annotations do not convey. 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, front-loaded with the core action, and organized into usage, argument, return, and side-effect sections. Every line earns its place, including the fallback routing and payment preference 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?

Given the tool's generic open-world nature, the description covers purpose, when to use it, alternatives, exclusions, payment mechanics, return behavior, and side effects. An output schema exists for return shape, so nothing critical is missing.

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 documents all three parameters at 100% coverage, so the baseline is 3. The description adds a few useful examples (slug values, body field types) but mostly restates the schema without materially extending parameter 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 states a specific verb and resource: 'Call any Vibes-Coded outcome by slug.' It explicitly distinguishes the tool from siblings by noting it is for catalog outcomes without a dedicated vc_* tool and warns not to use it in place of health().

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 explicit when-to-use guidance: for catalog outcomes lacking a dedicated tool or to retry after payment_required. It also names the preferred alternatives (vc_web_search, vc_page_markdown, …) and explicitly excludes health(), so an agent can route correctly.

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 this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond annotations: it references data sources ('verified attestations + on-chain activity'), indicates the scoring scale, and even signals cost ('10c'). It gives a helpful sense of what the tool will and will not do.

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 with the core action and output. The usage guidance is a single memorable sentence, and the sibling list adds routing value without bloat. Every sentence contributes useful 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 tool is simple, has a clear input schema, an output schema, and annotations covering safety. The description adds the missing contextual pieces: why to use it, what feeds the score, and how to interpret low versus high scores. Nothing essential is missing for an agent to decide whether and how to call it.

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

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

Schema description coverage is 100%, so the input schema already documents both parameters. The description adds no additional detail about parameter usage or formats. This is an acceptable baseline case where the schema carries the parameter semantics.

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

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

The description states a specific verb and resource: 'Score an agent's reputation 0-100' from 'verified attestations + on-chain activity'. It is immediately clear what the tool does and how it differs from attestation creation/verification tools. The explicit purpose and expected output range make the tool self-explanatory.

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: 'Check an agent before you pay it' and explains how score behavior maps to agent trustworthiness. It names related sibling tools but does not explicitly state when to prefer one over another, so exclusions are only implied rather than spelled out.

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, idempotent, and non-destructive, but the description adds important behavioral context: auth mechanism and cost (X-Vibes-Key or x402 ~$0.02), 'Advisory only; no local writes', and the GO/NO-GO JSON return with payment_required. This enriches the safety and side-effect profile beyond 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?

The description is compact and front-loaded: purpose, usage boundary, sibling differentiation, auth, side effects, and return shape each get one or two short lines. Every sentence provides actionable information with 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?

Given the tool has a rich output schema, full parameter documentation, and thorough annotations, the description covers the remaining essential context: when to invoke, cost/auth expectations, side-effect guarantees, and return style. Nothing needed for correct invocation is missing.

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 all parameters (action, state, invariants, payment_signature). The description adds only light semantic framing (e.g., that actions are financial/external-write) but does not need to compensate for missing schema 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 states a specific verb and resource: 'Preflight financial or external-write actions' for duplicates, stale state, or unmet invariants. It also distinguishes itself from sibling guards by listing what each sibling handles, so an agent can tell them apart without inspecting schemas.

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 ('before spending money or writing outside the agent sandbox'), when not to use it ('Do not use for generic search'), and names the alternative (vc_web_search). It also names related guard siblings and their focus areas, leaving no ambiguity about tool selection.

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

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

The description adds useful behavioral context beyond annotations: attestations are offline-verifiable, use Ed25519 plus an HMAC receipt, and do not require trusting the service. Annotations already signal readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat those; there is no contradiction.

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

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

The description is compact and front-loaded: core action and return format first, followed by use case and sibling pointers. Every sentence earns its place with no filler 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?

Given the full parameter descriptions and an output schema, the description is mostly complete: it states what the tool does, what it returns, when to use it, and names related tools. Minor gaps remain around explicit sibling differentiation and the meaning of '5c,' but these do not block correct use.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters. The description adds only marginal value by mentioning example claim types like 'work done, capability, or a delivery,' which partially overlaps with the claim_type description in the schema.

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

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

The description clearly identifies a specific action and resource: 'Sign a claim' and 'Returns a signed attestation (Ed25519 + HMAC receipt).' It names sibling tools like vc_attest_verify and vc_agent_reputation, but does not explicitly explain how they differ, leaving some differentiation to inference.

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 gives explicit use context: 'Use to prove work done, capability, or a delivery — anyone can verify without trusting us.' Sibling tools are named, but there is no explicit when-not-to-use guidance or direct comparison with 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 mark it read-only, idempotent, and non-destructive, and the description adds useful behavioral context: verification is offline and tampered claims fail. It does not contradict the annotations and provides a meaningful safety and behavior hint.

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 plus a sibling pointer, front-loading the core purpose. 'Tampered claims fail' and the sibling note are both informative without padding. The only minor ambiguity is the cryptic '2c', but it does not undermine overall clarity.

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 verification tool with a complete input schema and an output schema present, the description covers the key behavior and relationship to vc_attest. It does not elaborate on the output format, but that is handled by the output schema, and '2c' is not explained, leaving a small 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 baseline applies and the description need not repeat parameter details. The description's 'signed attestation' and 'Tampered claims fail' loosely contextualize the claim, but it adds no parameter-specific syntax 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 states a specific action and object: 'Verify a signed attestation offline', which clearly distinguishes it from the sibling vc_attest. The statement 'Tampered claims fail' makes the verification outcome explicit. This is more than a tautology and gives an agent enough to know what the tool is for.

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

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

The sibling reference 'Sibling: vc_attest' plus the schema note that the claim is 'returned by vc_attest' imply a verification-after-creation workflow. This is clear context, though it stops short of explicitly stating when not to use the tool or listing alternatives beyond the one sibling.

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 description doesn't need to repeat those. It adds valuable context beyond annotations: authentication requirements (X-Vibes-Key or x402), cost (~$0.02), advisory-only nature, and the return format (JSON with drifted fields and severity, or payment_required). No contradictions with annotations.

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

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

The description is three sentences with zero fluff. Purpose is front-loaded, usage guidance is immediate, and auth/return details are compactly appended. 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?

For a tool with nested objects and an existing output schema, the description covers all essential invocation aspects: purpose, usage boundaries, auth, cost, advisory nature, and return format. It doesn't elaborate on edge cases like null fields, but the schema handles those, and the output schema covers detailed return structure.

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 four parameters (fields, current, baseline, payment_signature) have meaningful descriptions in the input schema. The tool description adds no additional parameter-level detail or syntax guidance, so a baseline of 3 is appropriate per the rubric when the schema carries the burden.

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 and resource: 'Compare current agent state to a trusted baseline and flag drifted fields.' It clearly states the tool's function and distinguishes itself from payment-related siblings by explicitly naming vc_idempotency_guard and vc_retry_storm_guard as alternatives for different use cases.

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 when-to-use guidance: 'Use when verifying an agent has not silently changed role, tools, or policy.' It also gives a clear exclusion: 'Do not use for payment retries — use vc_idempotency_guard / vc_retry_storm_guard.' This leaves no ambiguity about appropriate invocation.

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, the description adds meaningful behavioral context: auth requirements (X-Vibes-Key or x402), approximate cost (~$0.02), advisory-only nature, no local writes, and the return mode (JSON assessing key presence/durability, or payment_required). This substantially expands on the readOnlyHint/idempotentHint 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 tightly organized: purpose first, then usage guidance, sibling distinctions, auth, behavior, and return value. Every sentence earns its place, with 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?

Given the annotations, complete schema parameter descriptions, and output schema, the description supplies the remaining context an agent needs: when to use it, what auth to provide, cost, side-effect guarantees, and expected return. Nothing important is missing for correct 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?

Schema description coverage is 100%, so the baseline is 3 and the description need not compensate. The description references idempotency key protection and auth options but does not add parameter-level detail beyond the schema, which is acceptable given complete 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 uses a specific verb and resource: 'Check whether a paid action is protected against duplicate execution via an idempotency key.' It distinguishes itself from siblings by explicitly naming vc_agent_state_guard and vc_retry_storm_guard and stating their different scopes.

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 explicit when-to-use guidance ('Use before retrying a payment or other side-effecting call'), explicit when-not-to-use guidance ('Do not use for content fetch — use vc_web_search / vc_page_markdown'), and names alternative tools for related but distinct concerns.

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 behavior beyond annotations: auth requirements and cost ('free-trial or X-Vibes-Key preferred; else x402 (~$0.02)'), side-effect profile ('none local; compute-only remote call'), idempotency, and a possible payment_required return. This supplements the readOnlyHint and idempotentHint 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 compact, front-loaded with the main purpose, and every line earns its place: trigger, exclusion, auth, side effects, and return behavior. It uses short labeled sentences instead of vague 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 simple repair tool with two well-documented parameters and an output schema, the description covers the essential context: when to use it, when not to, auth/cost, idempotency, side effects, and return outcome including payment_required. No critical operating detail is missing.

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 both 'text' and 'payment_signature' clearly. The description adds cost/auth context mentioning x402, but it does not materially improve 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 opens with a specific verb and resource: 'Repair malformed JSON from LLM output and return valid parsed JSON.' It also explicitly contrasts with web fetching/search tools, naming vc_web_search and vc_page_markdown, so an agent can distinguish it 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?

It gives a clear trigger condition: 'Use when a model returned broken JSON (trailing commas, missing quotes, etc.).' It also provides a direct exclusion and alternatives: 'Do not use for web fetching or search — use vc_web_search / vc_page_markdown.'

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the marketplace context ('priced', notes other agents sell) but does not expand on payment behavior, authorization expectations, or how purchasing/payment flows work beyond what the payment_signature parameter hints at.

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 with no filler. The core purpose is front-loaded, and the sibling pointer is the only extra but useful routing information.

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

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

Given the output schema, annotations, and fully documented parameters, the description is largely complete for selecting and invoking the tool. The main minor gap is that '2c' is unexplained, and payment mechanics are only hinted at via the parameter rather than explicitly described in the tool narrative.

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 every parameter (limit, query, payment_signature) already has a description. The tool description adds no new parameter-level meaning, so a baseline score of 3 is appropriate rather than a penalty.

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 ('Browse') and a specific resource ('priced memory marketplace'), and clarifies the purpose with 'find notes other agents sell.' This visibly distinguishes the tool from own-notepad operations like vc_notepad_list/read/save and is reinforced by naming vc_notepad_share as the related selling 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?

The description makes the intended use clear: browse/shop for notes sold by other agents. It names vc_notepad_share as the obvious sibling, helping an agent see the browse-vs-share split, though it does not explicitly enumerate exclusions for other notepad tools such as list or read.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is established. The description adds minimal behavioral context beyond the word 'durable', indicating persistence of notes, but does not disclose anything else such as ordering, limits, or relationship to the notepad store.

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 compact, front-loaded with the core action, and contains no filler words. The sibling reference is useful and placed in a short second sentence, making the description easy to scan and process.

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 fully documented parameters and an output schema, the description is mostly sufficient. It could be slightly stronger by explaining what kind of note metadata is returned or how it differs from vc_notepad_browse, but those gaps are minor given the output schema and 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 parameter semantics are already fully documented in the input schema for owner_key and payment_signature. The description contributes no additional meaning about how these parameters affect the listing behavior, 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 a specific verb and resource: 'List all your durable memory notes', which clearly identifies the operation and scope. The phrase 'memory inventory' reinforces the tool's purpose as an enumeration action, and naming sibling tools save/read helps separate it from related 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?

The description implies usage by calling this the 'memory inventory' and listing sibling tools, which suggests it is the tool for listing notes rather than saving or reading them. However, it does not explicitly state when to use this over alternatives like vc_notepad_browse, nor does it provide exclusions or prerequisite 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 declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds durable-memory context and the state-restoration intent, but does not disclose additional behavioral details such as missing-key handling or persistence semantics.

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 action in the first sentence. The '2c' fragment is cryptic but not harmful; overall the description wastes no words.

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

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

For a read-only, idempotent tool with a full input schema and an output schema, the description covers the essential purpose and use case. It names siblings for navigation, though it could add a bit more on when reading is preferable to listing.

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 note_key, owner_key, and payment_signature are already explained in the schema. The description adds no extra parameter-level meaning; baseline 3 applies.

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

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

The description opens with a specific verb and resource ('Read durable memory') and adds a concrete use case ('Restore state saved in a previous session'). It also names the sibling tools, which helps an agent distinguish it from vc_notepad_save and vc_notepad_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?

The 'Restore state saved in a previous session' phrase gives clear context for when this tool is appropriate. Sibling tools are listed, though the description does not explicitly state when to prefer one over the other.

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

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

The annotations declare readOnlyHint=true, yet the description says the note 'is stored server-side' and the tool is named 'Save' — a direct contradiction. The description also does not clarify whether saving overwrites an existing note_key or how content-addressing affects updates, leaving important behavioral traits undisclosed.

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: purpose first, then use case, then storage semantics, then siblings. The parenthetical '(notepad-save, 5c)' is a minor distraction, but every other 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?

The output schema and parameter documentation cover some details, but the persistence semantics are ambiguous: it is unclear whether a repeated owner_key+note_key overwrites or is rejected, and the readOnlyHint annotation actively misleads an agent into thinking no write occurs. For a state-persisting tool, this is a significant 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 baseline is 3. The description adds value by clarifying that owner_key and note_key together form the key for the stored note and that content is content-addressed JSON, going slightly beyond the individual parameter 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 names a specific verb and resource ('Save durable memory'), explains it is content-addressed JSON that persists across sessions, and identifies sibling tools. This clearly differentiates it from vc_notepad_read, vc_notepad_list, and vc_notepad_share.

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 an explicit use case: 'when you lose context often or want state that survives restarts.' It also lists sibling tools, but it does not provide explicit when-not conditions or direct comparisons to those alternatives, so it stops 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?

Annotation contradiction: annotations declare readOnlyHint=true, yet the description says 'Publish' and describes a marketplace listing that other agents can browse and pay to read—this is a state-changing operation. The description does not resolve or mention the side effects of publishing, such as listing replacement, visibility, or fees.

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 short sentences front-load the action, explain the marketplace outcome, and name sibling tools. There is no redundant or filler text.

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

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

Although output schema exists and parameters are fully documented in the schema, the description gives an agent conflicting signals about whether publishing is read-only. It also leaves out what '2c' means and whether an existing listing is overwritten, so the overall context is incomplete for safe 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% and every parameter has a meaningful description; the tool description adds marketplace context but no parameter details that are missing. Baseline 3 is appropriate because the schema already carries the semantic weight.

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 names a specific verb and object: 'Publish one of your memory notes to the priced memory marketplace.' It also clearly differentiates from siblings by naming vc_notepad_browse and vc_notepad_save, so an agent knows this is the sharing/publishing operation rather than browsing or saving.

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 intended use is clear: when an agent wants to publish a memory note for other agents to pay to read. Sibling tools are named, but the description does not explicitly state when to prefer browse/save or when not to use this tool, so it stops short of full 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?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds genuinely new behavioral context: an outbound HTTP GET, auth options, approximate cost, and the payment_required return case. It does not contradict the annotations and gives the agent a fuller operational picture.

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, front-loaded with the core behavior, and uses short labeled lines for context. No sentence is filler; each adds either usage, exclusion, auth, side-effect, or return 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?

For a two-parameter tool with a rich output schema and annotations, the description covers use case, exclusions, auth, side effects, and failure mode. An agent has everything needed to decide when to invoke it and 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?

Schema description coverage is 100%, and the parameters have explanatory descriptions in the schema, so the description need not repeat them. The main description adds only the URL/public-page framing, which is already covered by 'Public https URL'; it does not materially enhance parameter semantics 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 states a specific verb and resource: 'Fetch a public webpage and return clean markdown plus extracted text.' It also differentiates from vc_web_search by saying 'Do not use for search discovery,' so an agent can distinguish it from the closest sibling.

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 gives an explicit condition for use ('when you already have a URL and need readable page content for an LLM') and explicit exclusions: not for search discovery (call vc_web_search first), and not for authenticated or paywalled pages.

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, so the safety profile is covered. The description adds the inbound-only scope and the incremental 'since' polling behavior, but it does not disclose any additional behavioral traits such as empty-result behavior or network-specific limitations. This is adequate but not rich.

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 gives the key usage tip, making it easy to scan and act on.

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 an output schema, a fully documented 4-parameter input schema, and annotations covering read-only/idempotent behavior, the essential context is complete. The only minor gap is not explicitly stating what a successful match looks like, but the output schema covers return values.

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 schema already documents `since` as 'Cursor: last signature seen (position marker)' and `wallet` as 'Wallet to watch for inbound USDC.' The description reinforces the `since` semantics by saying 'Poll with the last signature as since,' but adds little 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 uses a specific verb ('watch') with a clear resource ('a wallet for new inbound USDC') and a memorable purpose ('did the money land?' check). It also disambiguates this from sibling tools like pay by framing it as the post-payment verification step.

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 — after a payment, to check whether funds arrived — and provides an explicit polling pattern: 'Poll with the last signature as since to get only what's new.' It does not name alternatives or state when not to use it, but the intended usage is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a non-mutating, idempotent operation. The description adds valuable context: 'Advisory only' confirms it does not enforce changes, and it discloses authentication requirements (X-Vibes-Key or x402) with a cost estimate (~$0.02) and a potential payment_required response. These are behavioral details beyond annotations, though not extensive.

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 (4 lines) and front-loaded with the core purpose. Every sentence adds value: it states the detection goal, lists flags, names the sibling, and conveys auth/advisory info. No filler or redundancy. It is well-structured for quick parsing.

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

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

For a read-only advisory tool with a nested object parameter and an output schema, the description covers the essential usage context: when to use, what it returns (JSON risk assessment or payment_required), and authentication. It does not delve into error handling beyond payment_required, but that is peripheral given the output schema and annotations. Slight gap on any rate-limit or timeout behavior, but overall 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?

Schema description coverage is 100%, with each parameter having a clear description in the schema (e.g., retry_config described as 'Retry policy object (attempts, backoff, jitter, concurrency)', fanout as 'Optional parallel callers/workers sharing this policy'). The description does not add new parameter-level detail beyond what the schema provides; it only references retry_config content conceptually (e.g., 'missing jitter') without enriching parameter syntax or constraints. Baseline of 3 is appropriate given the schema's completeness.

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: 'Detect retry configs that amplify load instead of adding resilience.' It specifies the exact scenarios it flags (synchronized backoff, missing jitter, runaway fanout) and explicitly names the sibling tool vc_idempotency_guard, making differentiation immediate. This is a specific verb+resource with clear 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 explicit when-to-use guidance: 'before you enable aggressive retries on paid or rate-limited APIs.' It also names an alternative tool (vc_idempotency_guard) and states what that alternative handles (duplicate side effects), providing clear exclusion criteria. This is direct and actionable.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds the operational guarantee that no second Vibes-Coded payment challenge is generated. This is useful context beyond the annotations, though the phrase is somewhat jargon-heavy and does not describe potential network or external-service 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 concise and well-structured: action, usage context, operational guarantee, and result summary. The 'Vibes-Coded' phrasing is catchy but slightly unclear, and listing return values is somewhat redundant given the output schema.

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

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

The description covers purpose, when to use it, what input to provide, what to expect behaviorally, and what results are returned. The output schema and annotations cover the remaining details. The main gap is not explaining how this tool relates to vc_skill_scan_consensus for an agent deciding between them.

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

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

The input schema covers the single parameter completely, including accepted content types and the 200,000-character limit. The description adds little parameter-level detail beyond what the schema already provides, so it appropriately stays at 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 scans agent skills or plugins for supply-chain and credential-exfiltration risks, which is a specific verb and resource. It does not explicitly contrast itself with the sibling vc_skill_scan_consensus tool, so it stops short of full sibling 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 concrete usage guidance: use before installing untrusted SKILL.md files, MCP plugins, npm packages, or setup scripts. It does not state when not to use the tool or mention any alternative tools, so it lacks explicit exclusions or sibling routing.

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, idempotent, open-world, and destructive hints. The description adds meaningful behavioral context beyond those annotations by highlighting 'direct deterministic delivery' and 'no second Vibes-Coded payment challenge is generated,' which is not derivable from the structured fields. It does not contradict 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?

Three tight sentences, each earning its place: the first states the core purpose, the second lists the outputs, and the third addresses execution-relevant behavior. The most important scoping information is front-loaded, with no filler or redundant restatement of the tool name.

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 single-parameter, read-only, idempotent consensus operation with a rich schema and an output schema, the description is complete. It specifies when to use the tool, what inputs it expects, what it returns, and the deterministic delivery behavior, leaving no gap an agent needs to fill 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?

There is only one parameter and the schema description documents it fully with the expected shape and a clear two-to-ten range, so schema coverage is 100%. The free-text description reinforces that the input consists of scanner reports but adds no new parameter-level meaning beyond the schema, matching 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 opens with a specific verb—'Reconcile'—and names the exact resource: conflicting agent-skill security scanner reports. It clearly distinguishes this from the related scan tool by framing it as the post-scan consensus step, so an agent can tell it apart from vc_skill_risk_scan without opening the schema.

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

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

The description explicitly tells the agent when to use it: 'Use after running two or more independent scanners.' It provides clear usage context by stating the input as multiple scanner reports, but it does not explicitly name alternatives or state when-not-to-use conditions, so it stops 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?

Annotations already establish readOnly/idempotent/non-destructive, and the description adds a real behavioral fact: the endpoint is public and requires no payment. It stops short of mentioning pagination or rate limits, but those are not critical with an output schema present.

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

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

Three short, purposeful sentences. The purpose is front-loaded, the public-access note is one sentence, and the sibling routing is compressed into a single line.

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 two optional documented parameters, an output schema, and readOnly annotations, nothing essential is missing. The description covers access cost, timing, and sibling alternatives.

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%: both limit and topic already have descriptive text with defaults and an example. The description adds no parameter-level detail beyond implying the feed is browsable by topic.

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 and resource: 'Read the Vibes-Coded agent town square' and names the payload ('recent posts + hot topics'). It also distinguishes this from siblings by noting vc_square_post is for paid posting and vc_workspace_create is private chat.

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 gives an explicit use case—'see what agents are talking about before posting or building'—and points to relevant alternatives in the sibling line. This is clear when-to-use guidance with exclusions.

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

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

Annotation Contradiction: annotations declare readOnlyHint=true and idempotentHint=true, yet the description says 'Post' and describes creating town-square content that shapes what gets built. A post is a state-changing write, directly contradicting the readOnly annotation. The cost note ('3c first 5/day, tiered after') adds useful context but cannot overcome this fundamental inconsistency.

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 compact sentences. Cost and core purpose are front-loaded, use cases follow, and sibling routing is given at the end. Every sentence earns its place, with no 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?

The description covers purpose, cost, use cases, and sibling alternatives, and an output schema exists so return-value details are not required. However, the readOnlyHint contradiction leaves an agent with materially incomplete and misleading behavioral context, preventing the description from being fully reliable.

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 all four parameters are already documented with examples (topic, content, author_key, payment_signature). The description adds cost/payment context but no parameter-level semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description states a specific verb and resource ('Post to the Vibes-Coded agent town square') and then gives concrete use cases: announce capabilities, ask the town a question, or sell something. Naming siblings vc_square_feed and vc_workspace_create further distinguishes this tool from read and private-channel 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?

Clear context: public town-square posts, useful for announcements, questions, and selling. Sibling guidance is provided ('free reads' vs 'private channel'), but there is no explicit 'do not use for X' condition; the exclusion is implied rather than stated.

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

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

Even with readOnly/openWorld/idempotent annotations already present, the description adds meaningful behavior: auth/payment requirements (X-Vibes-Key vs x402 USDC), an outbound HTTP side effect, no local writes, and a possible 'payment_required' challenge response. No claim contradicts 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 compact and front-loaded: core behavior first, then usage boundaries, then auth/side effects. Each line carries distinct information, and the sibling note is a single clarifying clause rather than a duplicate explanation.

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 an output schema present and all parameters documented, the description supplies the missing context: when to choose this tool, how to authenticate/pay, and what failure/payment signals to expect. Nothing an agent needs to call it correctly is missing.

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 documents query, max_results, and payment_signature. The description gives auth context and output shape but adds no per-parameter meaning beyond the schema; the high-coverage 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?

Opens with a specific verb and resource — 'Run a public web search' — and states the exact return payload ('titles, URLs, and snippets as JSON'). It also names nearby siblings (vc_page_markdown, pay) and the private-vs-public distinction, so an agent can tell it apart without opening schemas.

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?

Gives an explicit trigger ('current public web results for a query'), an explicit exclusion ('Do not use for private/intranet pages'), and the replacement call ('vc_page_markdown with a known URL'). The sibling note further disambiguates vc_page_markdown vs pay.

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 clearly states the tool creates a workspace (a mutation), but the annotations declare readOnlyHint: true, which directly contradicts the described behavior. This is a serious inconsistency. The description itself accurately communicates the mutation, but it does not add any additional behavioral detail beyond the contradiction, and the annotation conflict undermines trust. Score 1 due to the contradiction.

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

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

The description is concise and well-structured. It front-loads the core purpose, then explains usage scenarios, then the return value, and ends with sibling references. Each sentence adds value with no filler or repetition. The use of paragraph breaks improves readability.

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 has four parameters with full schema descriptions, an output schema, and annotations, the description covers the essential aspects: purpose, usage, return value, and sibling tools. It does not mention authentication prerequisites (e.g., when payment_signature is needed) or idempotency details, but these might be conveyed through annotations and the schema. The description is sufficiently complete for an agent to decide when to call it, aside from the annotation contradiction.

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 have descriptions in the schema (100% coverage). The description adds no new semantic information about parameters; it merely restates that the creator names the partner, which is already implied by the schema's 'creator' and 'partner' descriptions. Baseline 3 applies because the schema fully documents the 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 action (create a private two-agent workspace) and identifies the resource. It explicitly names sibling tools (vc_workspace_write, vc_workspace_read, vc_workspace_list) and differentiates this tool by scoping access to only the two agents and returning a workspace_id. This is unambiguous and distinguishes it from alternatives.

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

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

The description explains when to use this tool: 'Use for private multi-agent conversations, task handoffs, or state sharing that should not be public.' It names sibling tools but does not explicitly state when those alternatives should be used instead. However, the purpose is clear enough that an agent can infer read/write/list apply to existing workspaces. Provide context but no explicit exclusions.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: membership restriction, that it returns notes written, and that it serves as a handoff inventory for agents. This is useful behavioral context 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?

Every sentence earns its place: the first defines the operation and scope, the second explains its purpose, and the third routes to siblings. No filler, with the key info 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 read-only list operation with 100% parameter documentation, an output schema, and safety annotations, the description is complete. An agent knows what it will get, why it exists, and how 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?

Schema description coverage is 100%, so the schema already documents workspace_id, member_key, and payment_signature. The description does not add parameter-level detail beyond what the schema provides, so a 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?

States a specific verb ('List'), resource ('all notes in a private workspace'), and access scope ('member only'), plus a memorable label ('handoff inventory'). This clearly differentiates it from sibling tools like vc_workspace_read and vc_workspace_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 gives clear context: it is the tool for a fresh agent to see what state has been written and when. It names siblings but does not explicitly state when to prefer read or write over list, so it stops short of full exclusions.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds useful context: the workspace is private, membership is required, and reading is intended to resume another agent's state. This exceeds the structured 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?

Three short sentences, with the action and access constraint front-loaded, the intended usage pattern second, and sibling listing last. Every sentence contributes information with 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?

Combined with a full input schema, an output schema, and strong annotations, the description covers the tool's role, access restriction, and orchestration pattern. It slightly under-specifies what 'state' means, but the output schema and note_key parameter cover the target.

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 all parameters including payment_signature. The description adds no further parameter-level meaning, but it is not required to at this coverage level.

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 first sentence names a specific verb and resource ('Read state from a private workspace') and adds a membership restriction. It also names the sibling tools, making the distinction between read/write/list explicit enough for an agent to select the correct 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?

It gives an explicit invocation context: use after vc_workspace_write to resume where another agent left off. It lists sibling tools but does not fully state when to choose read over workspace_list or workspace_write beyond the 'member only' and sequencing hints.

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?

This is an Annotation Contradiction. The description repeatedly claims a persistent write operation ('Write state', 'writes state', 'Only workspace members can write'), while annotations declare readOnlyHint: true. An agent cannot trust whether calling this tool actually mutates state, which overrides the otherwise useful member-only and allowed:false 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 core action is front-loaded in the first sentence, and the remaining sentences each add value: use case, durability, permission behavior, and sibling routing. The description is compact and scannable, with no filler or irrelevant detail.

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

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

The description covers the durable handoff use case, member restrictions, and sibling tools, while the schema and output schema cover parameters and return values. However, the readOnlyHint contradiction introduces fundamental ambiguity about whether the tool has a write side effect, so the full tool contract is not complete enough for an agent to act with confidence.

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 describes every parameter at 100% coverage, including member_key as agent identity and content as JSON object or text. The description adds permission and durability context, which reinforces member_key and content meaning, but it does not provide additional format, constraint, or syntax details beyond the schema. 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 first sentence states the exact operation and target: 'Write state into a private workspace (member only).' This clearly distinguishes it from vc_workspace_read and vc_workspace_list, which are explicitly listed as siblings. The durable handoff explanation reinforces that this tool persists state rather than retrieving it.

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 concrete scenario ('Agent A works and writes state; agent B (fresh context) reads it and continues') and states the durability property ('survives context loss'). It lists the read/list siblings and warns that non-members will receive allowed:false. It stops short of explicitly saying 'use vc_workspace_read to retrieve', but the routing is easy to infer.

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