Arkon Vault

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the description's job is only to add context. It does add the state guard ('open handoff') and the recorded acceptor, but says nothing about what happens on an already-accepted or completed handoff, or whether the change is reversible.

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?

One sentence, zero filler, with the state transition front-loaded and the recording side effect trailing. Nothing needs to be trimmed.

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 mutation tool with no output schema, the safety profile is carried by annotations and the parameters by the schema. Still missing are failure behavior on non-open handoffs and what a successful claim returns, leaving a modest gap.

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

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

Schema coverage is 100%, so both id and acceptedBy are already documented in the schema. The description restates acceptedBy's purpose ('records the accepting platform or agent') without adding format or constraint detail, so 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?

States a concrete verb ('Changes ... to accepted') and the resource (an open handoff), plus the side effect of recording the acceptor. An agent can distinguish this from vault_post_handoff or vault_complete_handoff, though the description never names those siblings to sharpen the boundary.

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

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

The phrase 'open handoff' implies a precondition (only unclaimed handoffs can be claimed), which hints at when the tool applies. But there is no explicit when-to-use, no mention of vault_complete_handoff or vault_checkpoint_handoff as alternatives, and no guidance for an already-accepted handoff.

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

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

The annotations already declare that this is a non-read-only, destructive, non-idempotent operation. The description adds useful behavioral context by stating that each checkpoint renews the existing four-hour ownership lease without transferring ownership, though it does not cover permissions or error 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 tightly written sentences with no wasted language. The core action and the lease-renewal detail are both front-loaded and easy to scan.

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 fully documented schema and rich annotations, the description provides enough context to select and invoke the tool correctly. The main remaining gap is that, with no output schema, it does not describe what a checkpoint call returns or how failures are reported.

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 six parameters are already documented in the input schema. The description reinforces the accepted-handoff and progress concepts but adds no format or constraint details beyond the schema, making the baseline 3 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 and resource: "Publishes progress on an accepted handoff." It also distinguishes the action from completion by saying "without completing it," which clearly separates it from vault_complete_handoff.

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 clearly establishes the use case: checkpointing progress on an already accepted handoff during active work. It implicitly excludes completion, but it does not explicitly name vault_complete_handoff or other sibling alternatives, so it falls 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 indicate destructiveHint=true and idempotentHint=false, so the description's burden is lower. It adds the compatibility note about the accepted status, but does not disclose any irreversible consequences or post-close behavior beyond what the annotations imply.

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

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

Two short sentences with no filler. The primary behavior is front-loaded, and the compatibility caveat is placed second without disrupting the core message.

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 low-complexity tool with full schema coverage and clear annotations, the description is mostly complete. It lacks guidance on when to prefer vault_accept_handoff, and gives no clue about return behavior, but the essential calling context is present.

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 id, status, and acceptedBy adequately. The description adds only the notion of identifying the handoff by identifier, which is marginal value over 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 (changes a handoff to done or cancelled), identifies the resource (a handoff), and the key parameter (identifier). It is clearly distinguishable from siblings like vault_accept_handoff, which targets a different state transition.

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

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

The description does not explain when to use this tool versus alternatives. It mentions that 'accepted' status remains supported for compatibility, but notably does not direct agents to vault_accept_handoff when the goal is to accept a handoff.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds that the result is shared context including projects and handoffs for the current workspace, which is modest behavioral context, but it does not describe response structure, filtering behavior, or any operational constraints. This is acceptable for a read-only, zero-parameter tool but not exceptional.

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 front-loads the action and resource, then adds the two key content categories and scope. Every phrase contributes useful information 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?

For a zero-parameter, read-only tool with annotations covering safety and idempotence, the description covers the essential return content ('projects and handoffs') and context ('connected workspace'). It is slightly vague about what 'context' includes beyond those two categories and does not detail the output shape, but the lack of parameters and output schema makes this 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?

The input schema has no parameters, so there are no parameter semantics for the description to clarify. The baseline for zero-parameter tools is 4, and the description does not introduce any confusion or conflicting parameter expectations.

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, 'Returns,' names the resource ('shared Arkon Vault context'), and specifies contents ('projects and handoffs') and scope ('connected workspace'). It is clear about what the tool does, though it does not explicitly differentiate itself from siblings like vault_get_project or vault_list_handoffs, so it stops short of a 5.

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 no guidance on when to use this tool versus the many sibling tools, such as vault_get_project, vault_list_handoffs, or vault_list_conflicts. An agent can infer that this returns an aggregate overview, but the description never states that or provides exclusions or alternative 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 declare readOnly, idempotent, closed-world and non-destructive, so the safety bar is largely covered. The description adds genuine value by disclosing the return payload (name, summary, status, related records), which matters given there is no output schema; only the not-found behavior is left unexplained.

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?

One front-loaded sentence with the verb, scope, and returned fields in that order; nothing is redundant. It is dense but not bloated.

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 tool with full annotation coverage, the description supplies the two things structured data lacks: workspace scoping and the shape of the returned brief. Only error/empty-result behavior is unaddressed, which 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 coverage is 100% and the projectId property already carries a format example (grok:..., claude-code:...). The description only restates that it takes a single project id, adding no new syntax or constraint information, so 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?

States a specific verb ('Returns') and resource ('stored project brief') scoped to a single project id in the connected workspace, and enumerates the fields returned. It implicitly separates itself from vault_search_projects by requiring one id, though it never names the 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?

Usage is only implied: 'for one project id' suggests a direct lookup, and 'in the connected workspace' hints at scope, but there is no explicit when-to-use or when-to-prefer-vault_search_projects guidance and no mention of what to do when the id is unknown.

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, covering the safety profile. The description adds context about the specific types of output (collisions, busy handoff targets, multi-platform activity) and the configurable lookback window, which goes beyond the annotations. However, it does not describe return format or pagination behavior, and given the read-only nature, the additional value is moderate.

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 with zero filler. It front-loads the main purpose (returns collisions) and includes the key scoping element (lookback window) without extraneous words. Every phrase contributes meaning.

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 no output schema and all parameters documented, the description is reasonably complete. It states what kinds of information are returned and the configurable window. However, it does not mention the optional format parameter or how the output is structured (e.g., JSON vs markdown), though the schema covers that. It also omits any indication of typical usage scenarios, which is partly covered by usage guidelines but contributes to completeness. Overall, adequate but not rich.

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

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

The input schema has 100% description coverage for all 5 parameters, so the schema already documents each parameter's purpose. The description mentions a 'configurable lookback window,' which aligns with windowHours, but does not add syntax or format details beyond the schema. With full schema coverage, the description does not need to compensate, but it also adds minimal value here.

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 what the tool does: it returns directory and topic collisions, busy handoff targets, and multi-platform activity within a configurable lookback window. The verb 'Returns' and the resource types are specific, distinguishing it from sibling tools like vault_list_handoffs, which focus on handoff listings rather than conflicts. However, it does not explicitly name an alternative, so it falls just short of a 5.

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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, typical use cases, or exclusions. An agent would have to infer that this is a read-only check for conflicts, but there is no explicit direction on when to prefer it over sibling tools such as vault_preflight or vault_list_handoffs.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations by revealing that omitting the status filter returns only open and accepted handoffs by default, which is non-obvious and important for correct invocation.

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

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

Two short sentences, no filler, and the core behavior is front-loaded in the first sentence. Every sentence earns its place by stating either the primary action or an important default behavior.

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 list tool with one optional parameter, the description plus schema and annotations are complete. The default filter is disclosed, the parameter values are in the schema, and the safety profile is carried by annotations, so nothing essential is missing 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?

Schema description coverage is 100% and the status parameter is fully documented with its allowed values ('open, accepted, done, cancelled, or all'). The description adds no additional parameter-level meaning beyond what the schema already provides, 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 states a specific verb ('Returns'), a clear resource ('handoffs'), and a filtering dimension ('status'), making the tool's purpose immediately distinguishable from siblings like vault_list_conflicts or vault_search_projects. The title aligns with the description, leaving no ambiguity about what is listed.

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 a caller wants a list of handoffs, and it gives useful default behavior (open and accepted), but it never explicitly contrasts this tool with alternatives like vault_get_context or vault_search_projects. There is no exclusion or when-not-to-use guidance, so the agent must infer appropriate usage.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is carried by structured data. The description adds only the word 'durable', which implies persistence but doesn't spell out irreversibility, whether duplicate decisions are created on retry (relevant given non-idempotent), or required permissions.

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

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

One sentence, front-loaded with the verb and resource, with no filler. It could have used its remaining space for usage guidance instead of re-listing parameters.

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 five-parameter write tool with full schema coverage and no output schema, the description covers what the tool does and what it accepts. It leaves a gap around return value/ID and persistence semantics but nothing that would cause a mis-call.

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 every parameter is already documented in the schema with meanings matching the description's field list. The description adds no syntax, format, or defaulting detail beyond what the schema already states (e.g. actor default 'MCP').

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 ('Creates') and a specific resource ('durable project or workflow decision'), and enumerates the optional fields that can accompany it. The resource is unique among the siblings (handoff/project/sync tools), so an agent can identify it, though the description never explicitly contrasts it with those 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?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no hint about when a decision should be recorded versus a handoff or checkpoint. The agent must infer the trigger condition entirely.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, which is surprising for a create operation and demands explanation the description never gives: does a second post overwrite an existing handoff for the same project, or accumulate duplicates? No mention of overwrite semantics, persistence, or notification side effects to the target platform.

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?

A single efficient sentence with the core action and payload front-loaded; nothing is wasted. It is arguably too terse rather than verbose, but structurally sound.

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 eight parameters, a non-idempotent create, and a destructive hint plus no output schema, the description should say what is returned (handoff ID? URL?) and whether existing handoffs are replaced. None of that is covered, leaving the agent unable to predict the result of calling 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 coverage is 100%, so the schema already documents all eight fields. The description echoes context, doneCriteria, toPlatform, and project association, adding no syntax, defaults, or format detail beyond what the schema provides, so 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 names a specific verb ("Creates") and resource ("structured handoff") and enumerates the payload contents, so an agent knows exactly what is produced. However it never distinguishes this from sibling tools like vault_accept_handoff or vault_complete_handoff, which represent different lifecycle stages of the same object.

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?

There is no guidance on when to create a handoff versus accepting, checking, or completing one, and no prerequisites or constraints stated. The agent must infer the workflow position from the sibling names alone.

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 detail beyond the annotations: the tool deterministically produces a single nextAction and provides collision warnings. The read-only side is already covered by annotations, so the description adds value 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 a single, front-loaded sentence that immediately states the primary output (deterministic nextAction) and then enumerates the supporting data. No filler or redundancy.

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

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

The description covers the main return contents, and the schema documents all five parameters, but there is no guidance on when this preflight should be invoked relative to sibling tools, nor any note on how the output should drive subsequent actions.

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 parameters are already documented in the schema (100% coverage), and the description does not add extra semantic context about how 'query', 'platform', or 'projectId' affect the result. It neither repeats nor significantly extends the schema, 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?

The description names a specific action ('Returns a deterministic nextAction') and lists concrete returned data (related projects, handoffs, shared vision, collision warnings), making the tool's purpose clear. It does not explicitly differentiate it from sibling tools like vault_get_context, so it stops short of a 5.

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 title 'Preflight before work' and the phrase 'for a topic or task' imply the intended use case, but there is no explicit guidance on when to choose this over siblings such as vault_get_context or vault_search_projects.

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

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

Annotations already declare destructiveHint true and readOnlyHint false, so the description's 'creates or updates' aligns with that. However, it adds no extra behavioral context such as upsert semantics, duplicate handling, or side effects beyond the annotation signal.

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 encapsulates the action and key attributes, with no fluff. It is front-loaded with the primary purpose and reads clearly.

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 straightforward purpose and full schema coverage, the description is reasonably complete. It would benefit from mentioning the unique behavior of using externalId/fromProjectId for updates, but that is already in the schema. No critical missing information prevents an agent from invoking 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 coverage is 100% with each parameter individually described. The description only reiterates a subset of fields (name, summary, platform, status, directory, link, external identifier) without adding any meaning beyond the schema. The baseline of 3 applies because the schema carries the full 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 states a clear verb ('Creates or updates') and resource ('Arkon Vault project'), and lists the key fields involved. This immediately differentiates it from sibling tools like vault_get_project or vault_search_projects, which focus on reads.

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 implicitly conveys that this tool is for persisting project state, but it does not explicitly compare it to alternatives or state when not to use it. Since it is a write operation among many vault_* tools, an agent might infer usage, but no explicit guidance is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the matching scope but does not disclose result ordering, limits, matching semantics (fuzzy vs exact), or whether full project objects are returned. 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?

A single, front-loaded sentence with zero wasted words. It names the resource, the action, and the search criteria in one compact 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 one-parameter, read-only search tool with comprehensive schema documentation, this description is sufficient for correct invocation. It does not describe the return shape or result limits, but the absence of an output schema and the simplicity of the operation make this 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?

The input schema already documents the query parameter with examples, and coverage is 100%. The description adds meaning by mapping the query to specific project attributes (topic, name, platform, working directory), which helps the agent construct an effective search term.

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: 'Returns Arkon Vault projects' and enumerates the matching dimensions (topic, name, platform, working directory). This clearly distinguishes it from sibling get/list operations, so an agent knows exactly what the tool does.

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: call this when you need to find projects by a searchable attribute. It does not explicitly name alternatives or exclusion criteria, such as using vault_get_project for a single known project, but the context is sufficiently unambiguous.

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

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

Annotations already disclose that the operation is non-read-only, destructive, non-idempotent, and open-world, so the description does not need to restate those safety traits. It adds useful scope by naming the server-side continuity index and the conditional Notion mirror, but it does not explain what data may be overwritten or what prerequisites are required for the mirror sync.

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

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

The description is a single front-loaded sentence with no wasted wording. It puts the primary action and target first, then adds the conditional mirror scope.

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

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

With zero parameters, no output schema, and annotations covering the safety profile, the description provides enough context to understand the operation's target and external side effect. It could be stronger if it clarified what "continuity index" refresh means operationally or noted prerequisites for the Notion mirror.

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

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

The tool takes zero parameters, so parameter semantics are not a meaningful gap. The description appropriately avoids inventing parameter details, matching 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 states a specific verb and resource: it refreshes the connected workspace continuity index on the server, including an optional Notion mirror. It is clear what the tool does, but it does not differentiate this operation from sibling tools such as vault_get_context or vault_preflight.

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 what the tool refreshes but gives no explicit guidance on when to use it, when not to use it, or which sibling tool to choose instead. The Notion mirror clause is conditional scope, not usage guidance.

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