Arkon Vault

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, signaling a mutating, non-idempotent operation. The description adds the specific state transition (open to accepted) and the side effect of recording the accepting platform/agent. This covers basic behavior but does not disclose potential errors (e.g., if handoff is not open) or concurrency implications. It is consistent with annotations.

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

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

A single, direct sentence that front-loads the primary action. No filler, no repetition of the tool name, and the information is efficiently packed. Every word contributes to understanding the tool's purpose.

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 only two parameters and no output schema, the description adequately conveys the core operation. It implies the precondition that the handoff must be open and specifies what is recorded. It does not elaborate on error handling or edge cases, but given the simple nature and existing annotations, it is sufficiently complete for an agent to call 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%, with clear descriptions for 'id' and 'acceptedBy'. The description adds no new parameter meaning beyond what the schema already states; it simply echoes 'records the accepting platform or agent', which maps directly to acceptedBy. Baseline 3 is appropriate given full schema coverage.

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

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

The description states a specific action on a specific resource: changing an open handoff to accepted and recording the accepting party. It distinguishes from siblings like vault_complete_handoff (which likely marks completion) and vault_post_handoff (creation). The verb 'changes' and object 'handoff' are clear.

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 siblings. It does not mention alternatives like vault_complete_handoff or vault_checkpoint_handoff, nor any preconditions beyond 'open handoff' implied by the phrase. An agent must infer usage from the tool name 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?

Annotations mark this as a mutating, non-idempotent operation. The description usefully discloses the side effect ('renews the existing four-hour ownership lease') and clarifies it does not transfer ownership, which goes beyond the raw annotations.

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

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

Two succinct sentences, front-loaded with the core action ('Publishes progress on an accepted handoff') followed by the key constraints. 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?

Covers the main lifecycle behavior (accepted handoff, no completion, lease renewal, no transfer) and schema covers all parameters. It does not describe error/edge cases such as nonexistent or already-completed handoffs, but this is acceptable for a compact tool description.

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 covers all parameters (100% coverage) with descriptions, so the description need not repeat them. It adds only the general notion of 'progress,' which is not required given the schema coverage.

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

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

States a specific verb ('Publishes progress') and resource ('an accepted handoff'), and immediately distinguishes itself with 'without completing it' and 'without transferring ownership,' making it clearly distinct from sibling tools like 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?

The description clearly implies the scenario: checkpoint progress on an accepted handoff while explicitly excluding completion. It also explains the lease-renewal effect, but it never names sibling tools or states 'use this instead of X,' so it stops short of fully explicit 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds context about the source of related records (connector writes or Arkon Sync uploads), which is useful beyond annotations)Skip, but it doesn't describe potential behaviors such as record availability, ordering, or any retrieval limitations.

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

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

The description is concise, two sentences, with no filler. The main purpose is front-loaded, and the additional detail on data sources is kept brief. Every sentence adds value without redundancy.

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

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

Given the tool has only one parameter and no output schema, the description is adequate. It explains the tool's purpose and the nature of returned records. The main gap is the lack of guidance on when to use it compared to sibling tools like vault_get_context, but for a simple retrieval tool, the context is 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% and explains the projectId parameter format with examples (grok:..., claude-code:...), so the schema carries the necessary detail. The description does not add parameter-specific information, so it relies on the schema; a baseline score of 3 is appropriate since the schema is sufficient.

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 retrieves a project brief and related stored project records, with a specific verb ('Returns') and resource ('Arkon Vault project brief'). The scope is reasonably defined, but it could more explicitly differentiate from sibling tools like vault_get_context or vault_search_projects. The phrase 'Arkon Vault project brief and related stored session-derived project records' is specific enough to avoid confusion with generic tools.

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

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

The description implies the tool is for retrieving detailed project briefs, and mentions related records come from connector writes or separately approved Arkon Sync uploads, giving context on data sources. However, it does not explicitly state when to use this tool over alternatives like vault_get_context or vault_search_projects, or when not to use it. The context is present but not stated as direct guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and 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 readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a non-read, non-idempotent write operation. The description adds 'durable' to indicate persistence, which is useful. However, it doesn't disclose what 'durable' means in terms of storage, whether the decision is appended to a log, or any side effects beyond creation. 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?

One sentence, front-loaded with the core action and resource, then lists optional attributes. No wasted words. It could be slightly more explicit about the durable nature, but it's efficient and clear.

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

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

For a simple create-with-optional-fields tool, the description plus schema covers the essentials. There is no output schema, so the agent doesn't know what the return value is, but for a logging tool that may be acceptable. It doesn't mention whether the decision is immediately visible or requires a sync, but given the sibling vault_sync exists, that could be relevant. Still, the description is adequate for basic 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 schema already documents all five parameters. The description adds a bit of context by calling the decision 'durable' and listing optional attributes, but it doesn't add meaning beyond the schema's own descriptions. 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 uses a specific verb ('Creates') and resource ('durable project or workflow decision') and lists optional attributes (rationale, actor, project association, tags). It clearly distinguishes this from sibling tools like vault_get_context or vault_list_handoffs, though it doesn't explicitly name a sibling alternative.

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: use this when you need to record a durable decision. It does not explicitly state when not to use it or name alternatives, but the context of 'durable decision' versus handoff/checkpoint tools gives reasonable guidance. No exclusions or alternatives are mentioned.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, meaning this is a write operation but not destructive. The description does not disclose any behavioral details beyond stating it 'creates' a handoff, such as what side effects occur (e.g., notification to the target platform, conflict handling, or state changes). It does not mention whether it overwrites existing handoffs or requires specific permissions. Since annotations only state non-readOnly, the description carries the burden of clarifying mutating behavior, but it does not.

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, efficient sentence that front-loads the core purpose and key attributes. It includes all essential elements without fluff, but the sentence is slightly dense and could benefit from a slight structure break to highlight optional vs. required fields. Still, it earns its place 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 tool with 8 parameters, 1 required, and no output schema, the description provides a reasonable overview but lacks critical details about the creation process, such as what happens after creation, how the 'type' field affects behavior, or whether any validation occurs. Given the complexity of handoff workflows and the presence of siblings like 'vault_preflight' and 'vault_checkpoint_handoff', the description is not fully sufficient to guide an agent through the full context.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters. The description adds context that the handoff includes 'context, completion criteria, target platform, and optional project association', which maps to the parameters 'context', 'doneCriteria', 'toPlatform', and 'fromProjectId'. This adds moderate value by framing the purpose of these fields, but it does not detail syntax or relationships 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?

The description clearly states the verb ('Creates'), the resource ('structured handoff'), and the key attributes (context, completion criteria, target platform, optional project association). It distinguishes this from sibling tools like 'vault_accept_handoff' and 'vault_complete_handoff' by indicating it is the creation action, not acceptance or completion.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives such as 'vault_checkpoint_handoff' or 'vault_accept_handoff'. While it implies this is for starting a handoff, it lacks clear exclusions or references to sibling tools. No context is given for when not to use it, or when a checkpoint would be more appropriate.

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?

It discloses meaningful behavioral boundaries: no local file access, no ability to start Arkon Sync, and no uploading of conversations. The annotation set already covers read-only/idempotence/destructive traits, so the description adds context without contradiction.

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

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

The description is two crisp sentences. The first names the action and targets; the second clarifies limits and the alternative for uploads. Every phrase adds value.

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

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

For a parameterless tool with no output schema, the description gives enough operational context: what it refreshes, that it is server-side, and what it cannot do. It does not state success/error behavior, but that is not necessary at this level.

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 the 100% schema coverage is trivially complete. The description does not need to explain parameters and does not clutter the definition with them.

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 ('Refreshes') and identifies the exact server-side objects affected: the Arkon Vault continuity index and any configured Notion mirror. It also distinguishes this action from local sync and upload behavior by explicitly stating those are out of 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 clearly states what the tool cannot do and points to Arkon Sync as the separate tool for uploads, which gives useful when-not guidance. It does not explicitly compare this tool to sibling vault_* tools, but the 'refresh server-side index' purpose is enough to separate it from handoff/project tools.

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