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

Annotations already declare readOnlyHint and openWorldHint, so the description correctly avoids belaboring safety. It adds real behavioral context beyond those annotations: entries accumulate over time in orderaine, each is a vault version, and the ledger reflects agent_update history. This tells the agent what kinds of activity will appear 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?

Three tightly packed sentences with no filler: the core action is front-loaded, the second sentence explains what entries are, and the third gives use cases. Every sentence earns its place and the whole is shorter than many vague one-liners.

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 covering return values)Skip annotations covering safety, this definition supplies the remaining information an agent needs to call it correctly: what the resource is, what its entries contain, how they were produced, and why one would invoke it. Nothing material is missing for a simple read-only filtered-list tool.

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

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

Schema coverage is 100%, so both parameters (name and limit) are already fully documented in the input schema. The description doesn't add format, constraints, or cross-tool semantics for parameters beyond what the schema states, so the 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?

Begins with a specific verb and resource: 'View the full activity ledger for a persistent agent.' It then details the content (updates, status changes, findings, ordered) and ties entries to 'vault version created by agent_update,' which clearly differentiates this read tool from sibling writer tools like agent_spawn and agent_update.

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 final sentence provides explicit use cases: 'audit what an agent has done, trace its reasoning, or review progress since spawn.' It names the creating sibling (agent_update) to establish provenance, though it never explicitly tells the agent when not to use it or points to agent_recall as the alternative for current-state retrieval.

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

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

The description discloses that the tool aggregates data from multiple sources (agent history, memory/vault) and that learnings compound over time, which is beyond what the readOnlyHint and openWorldHint annotations provide. This is useful for the agent to set expectations about the breadth of data. However, it does not detail specific edge cases like absent agent or partial data, so a 4 is appropriate.

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

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

The description is well-structured and to the point. It starts with the core action ('Recall a persistent agent by name'), explains what is loaded, then clarifies the additional context pulling, and ends with practical use cases. No redundant sentences, and every sentence 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?

Given that the tool has only one parameter, a clear description, and no output schema (which is not required to explain return values), the description is complete. It covers what the tool returns (goal, progress, findings, history, learnings) and the related context, and clarifies the difference from agent_update. An agent has enough information 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?

The only parameter 'name' is described in the schema as 'Agent name as used in agent_spawn', so the schema coverage is 100%. The description does not add additional parameter semantics beyond that, but the baseline is 3 given full schema coverage. There is no need for further elaboration since the interplay with agent_spawn is clear.

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: to recall a persistent agent by name, loading its goal, progress, findings, history, and learnings. It distinguishes itself from siblings implicitly by focusing on the aggregated agent state and related context, going beyond what agent_update or vault_read alone would provide.

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 says when to use this tool: 'to resume a long-running task, check what an agent last did, or hand context to a fresh LLM session.' It also explains the behavioral difference from alternatives like agent_update or vault_read by mentioning that it pulls related context from memory/vault, which is not covered by siblings. This gives clear usage 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 this is a non-readonly, non-destructive, open-world operation; the description adds meaningful behavior beyond that by stating the agent persists across sessions, state is saved under a deterministic vault key, and the agent should not be used for one-shot tasks. It could mention duplicate-name/default behavior but is not required for basic safe 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?

The description is compact, front-loads the core purpose in the first clause, and then spends the remaining sentences on actionable usage rules and alternatives. No redundant or filler sentences are present.

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 of this complexity, the description gives enough to invoke it safely: when to and when not to use it, how state persistence works, the name-key relationship, and the related workflow tools. The lack of an output schema is acceptable because the description doesn't need to explain return values for a simple spawn/create operation.

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

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

Schema coverage is 100% and parameter descriptions are good, but the tool description adds a meaning not in the schema: the name is tied to a persistent vault key (`agent/<name>`), and 'context' is implied to be starting data. This goes beyond merely repeating the schema and gives the agent a clearer mental model of the arguments.

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 object: 'Create a persistent NAMED agent with a goal' and clarifies it survives sessions with state under an `agent/<name>` vault key. It distinguishes itself from sibling tools by naming memory_add for ephemeral data and by scoping when agent_spawn is appropriate.

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 is explicit about when to use it ('task is ONGOING and will span multiple sessions'), when not to use it ('one-shot tasks', 'ephemeral background data'), and which alternatives to use instead: agent_update, agent_recall, agent_ledger, memory_add, or the relevant direct tool. This is strong routing guidance.

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

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

The description contradicts the annotations: idempotentHint is true, yet the description states 'Creates a new vault version automatically' and 'appends it to the agent's accumulated learnings,' implying each call has a cumulative effect and is not idempotent. This is a serious contradiction that misinforms the agent about the tool's behavior. The description does disclose mutations, but the contradiction undermines behavioral transparency.

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

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

The description is concise and well-structured. It opens with the core purpose, then lists side effects, and ends with the status enum. Every sentence earns its place, with no fluff or redundancy.

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

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

Despite the clear purpose, the description is incomplete because it contradicts the idempotency annotation, creating confusion about the tool's behavior. It also does not mention return values (there is no output schema) or prerequisites, but the primary gap is the idempotency inconsistency, which means an agent cannot safely predict outcomes. The description covers some aspects but is inadequate for a mutation tool given the 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?

Schema description coverage is 100%, so all parameters already have descriptions. The tool description adds minimal value beyond restating the status enum ('Status options: active | blocked | complete') and referencing 'progress and findings.' It does not provide additional meaning for parameters like findings or nextStep beyond the schema. 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 states a specific action ('Update') on a specific resource ('a persistent agent'), and clearly distinguishes it from siblings like agent_spawn, agent_recall, and agent_ledger by mentioning 'progress and findings.' It also describes the key side effects (vault version creation, insight extraction), so an agent knows exactly what this 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 implies use for updating an agent's progress and findings, but it does not explicitly mention alternatives or when not to use it. There is no contrast with siblings like agent_spawn or agent_recall, so an agent must infer the usage context. The context is clear but lacks explicit routing 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 and openWorldHint. The description adds that Finch loads saved memory to personalize answers and that it runs a separate LLM call, implying cost and potential redundancy. It also warns that calling it may not add value if the caller already has the data. These details go beyond annotations, though they do not exhaustively describe all behavior, so a 4 is appropriate.

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 block but front-loads the purpose ('Ask Finch anything') and then lists use cases, usage guidance, and an exclusion. Each sentence carries information, though the prose is somewhat dense and could be more structured (e.g., bullet points). It remains concise and to the point, warranting a 4.

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 tool with 2 parameters and no output schema, the description is complete for an agent deciding when and how to call it. It covers purpose, use cases, exclusions, and conversation continuity. The only minor gap is the absence of specifics about how memory is loaded, but that is not essential for invocation. This is near-perfect contextual completeness.

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

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

With 100% schema description coverage, the baseline is 3. The description adds specific semantics for the 'messages' parameter – it is for continuing a conversation across tool calls – which is more actionable than the schema's generic 'context'. It also frames 'question' as open-ended ('Ask Finch anything'). This adds meaningful value beyond the schema, earning a 4.

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

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

The description clearly states the action ('Ask') and resource ('Finch') with explicit categories of use (analysis, opinions, explanations, strategy, ideas). It distinguishes itself from siblings like memory_* and vault_* by covering general conversational queries, which none of the siblings do. The tool's purpose is unambiguous.

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

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

Provides a specific list of when to use (research, content ideas, code explanations, etc.) and an explicit exclusion: if the caller is a reasoning model with sufficient data, answer directly instead of calling this tool, because it runs a separate LLM call and may be redundant. It also instructs how to pass previous messages for conversation continuity. This is exemplary usage guidance.

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

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

The description adds useful behavioral context with 'permanent timeline' and 'system-wide audit log', implying entries are persistent and broadly visible. The annotations already cover the safety profile (non-read-only, non-destructive, open world), and the description is consistent with them, though it does not disclose return behavior, retention limits, or immutability details.

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

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

The description is tightly written and front-loaded with purpose, followed by useful examples and one clarifying permanence statement. The only redundancy is the type list, which repeats schema information, but it is compact and does not significantly bloat the description.

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 log/write tool with four parameters and no output schema, the description provides the essential operating context: what to record, useful example events, supported categories, and persistence semantics. It does not mention the return value or explicitly disambiguate from other write tools, but those gaps do not prevent correct invocation.

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

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

Schema description coverage is 100%, so the description does not need to explain parameters. The 'Types' list merely duplicates the enum already present in the schema, and there is no additional guidance about how to structure metadata or detail values.

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 ('Log an event') and a well-defined resource ('Finch Chronicle - the system-wide audit log'). It also gives concrete examples of what counts as an event, distinguishing chronicle_add from the read-oriented siblings like chronicle_list and chronicle_search.

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

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

The description provides clear content guidance via the italic event examples and the type list, so an agent knows this is for audit-style logging. However, it never explicitly says when not to use it or names alternatives like vault_save or memory_add for actually performing those actions, which could lead to overuse as a general action tool.

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

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

Annotations already mark the tool as read-only, and the description adds useful behavioral context: recent events, reverse chronological ordering, and type filtering. It does not discuss retention or limits, but those are either non-critical for a read-only log or covered by the schema.

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

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

The description is two sentences with no filler. It front-loads the core read behavior and ordering, then introduces the filtering capability.

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, read-only list tool with fully documented parameters and an output schema, the description provides sufficient context for an agent to invoke it correctly. No critical information 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 coverage is 100%, so the schema already documents both type and limit, including enum values and default/max. The description's examples like 'vault saves, agent activity, automations' add illustration but no new semantic meaning beyond the schema.

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

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

The description states a specific verb ('Read'), a specific resource ('Finch Chronicle event log'), and observable behavior ('Returns recent events in reverse chronological order'). It is clear but does not explicitly distinguish itself from sibling tools like chronicle_search or chronicle_stats.

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 'your AI runtime timeline' implies when this tool is useful, and 'Filter by type' gives parameter-level guidance. However, there is no explicit when-to-use versus alternative guidance, nor any pointer to chronicle_search or chronicle_stats.

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 and openWorldHint, so the safety and open-world behavior are covered structurally. The description adds that matching occurs against event titles and details, which is helpful but not a deep behavioral disclosure. No contradiction exists.

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 tight sentences plus illustrative examples. The core action is front-loaded, and there is no filler or redundant content. Every sentence earns its place.

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

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

For a read-only search tool with a rich schema, an output schema, and safe annotations, the description covers the essential context. Optional filtering and limits are already documented in the schema, so their absence from the description is not a gap. It could be slightly stronger by mentioning the optional type filter, but it remains complete enough.

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 query, type, and limit. The description's phrase 'matches against event titles and details' restates the query schema description, and the examples add flavor but little new semantic information. 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 opens with a specific verb and resource: 'Search the Finch Chronicle by keyword.' It clarifies what is matched ('event titles and details') and includes concrete example queries, so an agent can tell this apart from sibling tools like chronicle_list or chronicle_stats without ambiguity.

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 the tool is useful: 'finding when something specific happened' and gives realistic example queries. It does not explicitly name alternatives or state when not to use it, but the examples and search framing provide clear practical 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 establish readOnlyHint and openWorldHint, and the description supplements that by disclosing the aggregated output shape: breakdown by event type, heatmap, busiest days, and top categories. It does not contradict the annotations and gives a clear picture of what the tool returns.

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 tight sentences with no filler: the first enumerates the output dimensions and the second gives the intended use case. 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 one-parameter read-only statistics tool that has an output schema and clear annotations, the description fully covers what an agent needs to select and invoke it appropriately.

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% because the single 'days' parameter is already documented with its default of 30 and maximum of 90. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as producing activity stats for the AI runtime and enumerates the concrete output dimensions: event type breakdown, daily activity heatmap, busiest days, and most active categories. This distinguishes it from the related chronicle_list, chronicle_search, and chronicle_add 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?

The description explicitly states when to use the tool: 'Use to understand how heavily you're using the runtime.' It provides clear context but does not name alternatives or state when not to use it.

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, so the write nature is already apparent. The description adds valuable behavior beyond annotations: same project creates a new version with full history, auto-links to related entries, and is styled like git. This gives the agent meaningful 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 compact and front-loaded: the core action and resource appear first, followed by useful contextual behavior and usage guidance. Every sentence contributes meaning without redundancy or filler.

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

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

For a tool with six well-documented parameters and no output schema, the description provides sufficient context: what the tool does, where it stores data, how versions work, and when to invoke it. Minor omissions like return values or error cases are not critical given the schema and annotations already cover invocation essentials.

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

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

Schema description coverage is 100%, with each parameter already documented in the input schema. The description does not add new meaning to individual parameters; the project key behavior is already present in the schema's project param description. This meets the baseline but does not exceed it.

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

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

The description opens with a specific verb and resource: persist a coding/debugging session as a versioned Markdown snapshot in Finch Vault. It differentiates from vault_save and other siblings by specifying the code/<project> key, versioning behavior, and auto-linking. An agent can immediately understand what this tool does and how it is distinct.

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 ('Call this at the end of a substantive coding task') and an explicit when-not-to-use caution ('not for every single file read or trivial edit'). It references vault_save for versioning but does not explicitly name vault_save as the alternative for general-purpose saves, so it stops short of full 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, indicating a safe, non-mutating operation. The description adds what it checks (services and env vars) and what it shows ('which env vars are set and which services are reachable'), which is useful. However, it doesn't disclose potential side effects or rate limits, but for a health check these are less critical. No contradiction with annotations; it adds modest context.

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

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

The description is a single, well-structured sentence that fronts the main purpose and then provides usage guidance. It's concise and to the point, 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?

For a zero-parameter, read-only health check tool, the description is nearly complete. It specifies what services are checked, when to use it, and what output to expect. Given the simplicity, there is little missing; a minor gap is the exact output format, but the description's mention of 'shows which env vars are set and which services are reachable' 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?

The tool has no parameters, so the schema carries no burden. The description fully explains what the tool does without needing parameter information, as there are none. It exceeds the baseline because it doesn't need to compensate for any schema gaps.

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: 'Health check for all Finch services', naming the specific services (Convex backend, Firecrawl, Supermemory, API keys). This is a specific verb+resource combination and distinguishes it from siblings like 'finch_status', which likely is a simpler status check. It's not a full 5 because it doesn't explicitly contrast with 'finch_status'.

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 on when to use it: 'Run this when something is broken or before starting a long research session to confirm everything is live.' This is explicit about usage timing. It doesn't explicitly say when NOT to use it or name alternatives, but the context is clear enough that an agent can decide.

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

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

The description discloses that this is an AI terminal with tool calling and lists concrete actions such as saving to vault, spawning agents, and creating automations. This adds behavioral specificity beyond the annotations' readOnlyHint=false and openWorldHint=true, though it does not discuss side-effect risks or failure modes.

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

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

The description is a single dense sentence that front-loads the tool's identity and then lists capabilities with no filler. It is slightly overloaded with the seven-item list, but each item adds useful information for an agent deciding to use the tool.

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 free-text chat tool with simple parameters, the description provides enough context to select and invoke it: the tool's purpose, capabilities, and single-prompt input style are all covered. It does not describe the response format, but that is less critical for a chat-oriented tool without an output schema. Sharper guidance on when to prefer dedicated siblings would improve completeness.

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

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

The input schema already documents both parameters with 100% coverage, so the description need not repeat them. It does not add extra meaning about message formatting or agent_id behavior, so the 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 clearly identifies a specific verb and resource: chat with Finch Terminal, an AI terminal with tool calling. It enumerates concrete capabilities (spawn agents, save to vault, search memory, create automations, estimate swaps, list agents, get wallet balance), which distinguishes it from narrow sibling tools even without naming them.

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 'all from a single prompt' provides a clear usage context: use this tool for natural-language, multi-step, or cross-capability requests. It does not explicitly state when not to use it or how it differs from ask_finch, so exclusions are absent, but the intended use is strongly implied.

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

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

Beyond the readOnlyHint annotation, the description adds valuable behavioral context: no sign-in is required, it reveals whether the session token is configured, and it positions itself as a first-line diagnostic that tells the agent where the problem lies. This gives a clear picture of side effects, auth requirements, and expected diagnostic value, with no contradiction to 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 concise sentences are front-loaded with the tool's purpose, followed by its return content and clear usage guidance. Every sentence earns its place, with no redundant or filler phrases.

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

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

With no output schema, the description compensates by explicitly listing the returned fields and explaining how to interpret them in terms of auth, network, or tool failure. For a zero-argument health-check tool, this fully covers invocation, return value interpretation, and practical usage 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?

The tool has zero parameters and the input schema is already complete with 100% coverage. There is nothing for the description to add about parameter meaning, so the baseline of 4 applies.

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

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

The description clearly identifies a Finch MCP health-check tool: it checks whether Finch MCP is working and enumerates concrete outputs such as version, tool count, session-token configuration, and a client config snippet. However, it does not explicitly differentiate itself from the similarly named finch_diagnostics sibling, so clarity is strong but sibling distinction is only implicit.

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 timing guidance: 'Run this FIRST if anything feels off' and explains how the tool distinguishes auth, network, and tool-level failures. It does not mention when not to use it or direct the agent to alternatives like finch_diagnostics, so it provides clear context but no exclusions or alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds meaningful behavioral context: the wallet is local and keys never leave the machine. This reassures the agent about privacy and side effects. The return format is not described, but an output schema exists to cover that.

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

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

The description is two sentences with no filler. The first sentence states the action directly and the second adds relevant security/context details. 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 simple zero-parameter, read-only tool with an output schema, the description is complete. It covers what the tool returns conceptually, the wallet's role, and key security characteristics. 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?

This tool takes zero parameters and the schema coverage is 100%, so there is nothing for the description to add about parameter meanings. The baseline of 4 applies because no parameter documentation is needed.

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 clear verb and resource: 'Get your Finch wallet address.' It further explains what the wallet is used for (signing requests and receiving on-chain assets), which distinguishes it from sibling tools like get_wallet_balance and wallet_sign_message. The purpose is immediately identifiable.

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 useful context about when this address matters: it is the local MCP wallet for signing and receiving assets. It does not explicitly name alternatives or state when not to use this tool, but the zero-parameter read-only nature makes the usage situation clear enough.

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 and openWorldHint, and the description adds meaningful behavioral context: live on-chain data, network (Base mainnet), and no API key required. This goes beyond the annotations by clarifying the data source and access requirements 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 two tight sentences with no fluff. The primary purpose is front-loaded, the optional usage is clearly stated second, and the live-data/no-API-key detail is useful and concise.

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

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

This is a low-complexity read-only tool with one optional parameter, full schema coverage, annotations, and an output schema. The description covers what assets are checked, which chain, whose wallet, how to override, and the live/auth nature of the data. 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 coverage is 100% for the single parameter, but the description adds nuance by clarifying the address is optional and can refer to any wallet, not just the Finch wallet. This is meaningful semantic enrichment beyond the schema's brief 'default: your Finch wallet' note.

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 checks ETH and USDC balances on Base mainnet for the user's Finch wallet, with an optional address override for any wallet. This is a specific verb+resource combination and is readily distinguishable from sibling tools like get_wallet_address or wallet_sign_message.

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 the default behavior (checking the Finch wallet) and how to extend it (pass an optional address to check any wallet). It does not explicitly name alternatives or exclusions, but the usage context is clear and the optional parameter guidance is practical.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description reinforces read-only behavior. It adds valuable context beyond annotations: the automatic case-insensitive name match behavior and the local-vault mode behavior. It does not contradict the annotations, and the extra context meaningfully shapes how an agent should interpret results.

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 front-loaded with the core purpose and remains compact overall. The 'Read-only.' phrase is redundant with the annotations, but the remaining sentences each contribute meaningful context about scope, usage, and mode-specific 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 zero-parameter, low-complexity tool with read-only and open-world annotations, the description covers purpose, usage timing, and mode behavior. The only notable gap is that it does not describe the shape of the returned project list, which would help an agent know whether it can directly pass the result to workspaceProject, though the usage hint partially compensates.

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

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

The tool has zero parameters, so the schema already fully covers parameter needs. The description still adds semantic context by defining what a 'project' means in this system and how it relates to vault_save/agent_spawn, which is more than the empty 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 uses a specific verb and resource ('List your Finch workspace projects') and clarifies that these are the same Projects used to organize Agents and vault content, which distinguishes it from vault_list, memory_list, and similar sibling tools. It immediately communicates exactly what the tool does and what domain it operates in.

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 tells the agent when to check this tool ('before passing workspaceProject to vault_save/agent_spawn') and when it is irrelevant ('No effect / nothing to list in local-vault mode'). This is direct workflow guidance with both a positive and negative usage condition.

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

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

The description discloses substantial behavior beyond the annotations: auto-deduplication against the recent 50 memories, force:true override, ~30s indexing for sourceUrl, full-text keyword search semantics, and a possible-conflict hint that is explicitly not an LLM verdict. There is no contradiction with the provided annotations; readOnlyHint:false and destructiveHint:false align with a non-destructive write operation.

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

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

The description is dense but every sentence earns its place: purpose, differentiation, use cases, retrieval semantics, deduplication rules, conflict behavior, and next steps are all covered. It is front-loaded with the core purpose, and while long, the length is justified because it presents genuinely decision-relevant 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 five parameters, no output schema, and minimal annotations, this description is exceptionally complete. It explains what happens on save, what deduplication means, how to override it, how sourceUrl ingestion behaves, and how to handle conflict hints. An agent can confidently invoke the tool and respond appropriately to its results without guessing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantic context beyond the schema: deduplication applies to recent 50 memories, force bypasses that check, and sourceUrl content becomes searchable in ~30s. It also advises using a short title when providing a URL. The tags parameter remains schema-only, which prevents a 5, but the added context is meaningful.

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: 'Add content to your Finch memory,' and immediately distinguishes itself from vault_save by emphasizing instant, versionless, type-free storage. It also lists concrete use cases (notes, decisions, preferences) and clarifies that retrieval is keyword-based rather than embedding-based, leaving no doubt about what this 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 explicitly contrasts memory_add with vault_save and gives clear direction: use memory_add for instant notes/decisions/preferences, and use memory_consolidate when folding conflicts into one memory. It also prescribes a follow-up workflow when possible conflicts appear, telling the agent to read existing memories and decide whether to supersede them or consolidate.

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 provides extensive behavioral transparency beyond the annotations. It states that it is a two-pass process, requires no API key, and crucially assures that 'Originals always remain intact' – a key safety detail. It explains the switching behavior of 'summary' parameter, which is a non-obvious side effect. The annotations only indicate not read-only, open-world, and not destructive; the description adds the nuance that the tool is safe (does not delete originals) despite being a write operation. No contradictions.

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 but information-rich, with efficient use of format: it uses bold headers for passes and a clear list-like structure. Every sentence contributes essential usage information. It front-loads the purpose and safety guarantee early. No fluff or redundancy.

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

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

Given the tool's complexity (two-pass workflow, optional 'limit', and 'summary' switching behavior), the description covers all necessary aspects. Combined with the 100% schema coverage and the lack of an output schema (so no need to describe return values), the description fully equips an agent to use the tool correctly. It explains the two-pass workflow, the role of each parameter, and the safety guarantee.

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 each parameter has a description. However, the description adds significant meaning beyond the schema: it explains that 'topic' is used in both passes, 'summary' switches the tool from 'return' to 'save', and 'limit' is only relevant in PASS 1. This is critical operational semantics not in the schema. The description's explanation of 'summary' as the trigger for PASS 2 is a key addition.

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 explicitly states the tool's purpose: 'Clean up fragmented knowledge after heavy research sessions' and clearly distinguishes it from siblings like memory_add or memory_search. The verb 'consolidate' plus the resource 'memories' clearly differentiates it from other memory tools. It provides a specific scenario ('after heavy research sessions') and the two-pass nature, making it unmistakable.

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

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

The description provides explicit step-by-step instructions for both passes: PASS 1 and PASS 2, and clearly states when to use each. It also implies when not to use it (e.g., not for simple recall, use memory_search instead) by outlining the consolidation workflow. The behavior is unambiguous: first call fetches memories, second call saves the merged summary.

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 provide readOnlyHint and openWorldHint. The description adds valuable behavioral detail beyond those annotations: it reveals that the tool uses full-text keyword search rather than embeddings, and warns the agent to phrase queries using words that likely appear in the saved memory. This is helpful, non-obvious 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?

Three tight sentences: purpose, usage timing, and query mechanics. No filler or repetition, and the most decision-relevant information is front-loaded.

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

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

The description explains what the tool does, when to use it, and how to phrase the query. An output schema exists, so return-value documentation is not the description's job. Nothing essential is missing for an agent to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful guidance for the 'topic' parameter ('phrase your topic with the words you expect were actually used when the memory was saved'), which goes beyond the schema examples. The optional 'limit' is not discussed, but the schema already covers it.

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

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

The description names a specific verb ('Retrieve'), a specific resource ('memories'), and a target ('for a topic'), and adds a distinguishing feature: 'formatted as AI-ready context'. This clearly separates it from sibling list/search tools even though no sibling is named.

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: 'Use at the start of research tasks to prime with everything stored about a topic.' It communicates when to use the tool effectively, though it doesn't explicitly name alternatives or when-not-to-use 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?

Behavioral traits are thoroughly disclosed beyond the annotations: 'PERMANENT,' 'cannot be recovered,' 'Requires confirm: true,' and the instruction to show the user and get agreement. This adds meaningful context about irreversibility and safety that goes well beyond the destructiveHint flag.

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-loads the most critical information ('PERMANENT') before explaining the action. Every sentence serves a purpose: stating the action, irreversibility, ID source, confirmation requirement, and user safety.

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 clear destructive action, the description covers all necessary context: what it deletes, how to get IDs, the confirmation requirement, and user-consent steps. The annotations and schema already handle the remaining details, and no output schema is needed for this operation.

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

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

The schema already documents both parameters with high coverage (100%), including the confirm flag's role as a guard against irreversible loss. The description reinforces these semantics but does not add substantive new meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description states a precise action—'Delete a specific memory by its ID'—with a strong emphasis on permanence. It clearly distinguishes itself from related memory tools by focusing on deletion and referencing memory_search/memory_list as ID sources rather than as 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 tells the agent to obtain IDs from memory_search or memory_list and mandates showing the user the memory and getting agreement before deletion. It provides clear context for when to invoke the tool, though it does not explicitly name alternatives or exclusions, which is acceptable given the uniqueness of deletion.

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 communicate that this is a write operation and not destructive. The description adds meaningful behavioral context: the two-pass state machine, per-fact deduplication, and that no API key is needed. It does not describe what pass 2 returns or whether stored facts can be overwritten, so a small transparency gap remains.

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 front-loaded with purpose, then moves into a clearly labeled two-pass workflow. The sentence about choosing facts earns its place by removing ambiguity about who extracts. The 'Best for' line is a compact usage note. No excess filler or repetition of schema details.

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

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

For a tool with no required parameters and no output schema, this description covers the workflow, the side effect, and ideal inputs well. Minor omissions are the exact return of pass 2 and behavior when both 'text' and 'facts' are supplied, though the schema notes that facts skip pass 1 entirely.

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 explaining the relationship between 'text' (pass 1) and 'facts' (pass 2) and clarifying the division of labor: the caller decides facts; the tool stores them. The optional 'source' parameter is left to the schema, which is acceptable.

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

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

The description opens with a specific action and resource: 'Save discrete facts, preferences and decisions to memory as individually searchable atoms' rather than a wall of text. It clearly communicates the extraction-and-storage workflow and distinguishes itself from other memory tools by emphasizing the two-pass design and the caller's responsibility for choosing facts.

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 when-to-use guidance: 'Best for chat logs, research notes, meeting summaries.' It also explains the two-pass procedure and that providing facts skips pass 1. It lacks explicit when-not-to-use or named sibling alternatives, so it is clear but not exhaustive.

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 and openWorldHint, so the safety profile is covered. The description adds substantial behavioral context beyond that: it specifies the tool combines memory and vault entries, identifies gaps, suggests next actions, and returns a structured set of fields (confidence level, what you know, coverage timeline, gaps, recommended next steps). This gives the agent a clear picture of what the report contains and what to expect, going well beyond the annotations.

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

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

Three tightly structured sentences: the first states the core purpose and functionality, the second gives direct usage guidance, and the third lists the return structure. Information is front-loaded with no filler. Every sentence earns its place, making it both concise and highly scannable.

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

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

For a read-only aggregation tool, the description covers all essential aspects: what it does, when to use it, and what it returns. Though there is no output schema, the return items are enumerated. The depth parameter is adequately documented in the schema. The description is complete for an agent to decide when and how 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% for both parameters (topic and depth), so the schema already fully documents their meanings. The description adds no additional detail about parameter nuances—for example, it doesn't explain how 'depth' affects the report or the default behavior. Since the baseline is 3 when schema coverage is high and the description doesn't add value, a 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 ('Get a full intelligence report') and resource ('any topic'), explicitly differentiating from sibling tools by noting it combines memory AND vault entries. This clearly distinguishes it from single-source tools like memory_search or vault_search, and the mention of 'knowledge gaps' and 'next actions' sets it apart from generic search.

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 usage context: 'Use this before starting any research or trade decision to see everything Finch already knows.' This tells the agent when to invoke it. However, it does not explicitly state when not to use it or name alternatives, though the context implies it's the high-level aggregation tool versus more targeted siblings. A clear when-to-use without exclusions earns a 4.

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

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

Annotations already indicate readOnlyHint=true and openWorldHint=true, so the description doesn't need to restate those. It adds that results are sorted by most recently added, which is behavioral context beyond the annotations. However, it doesn't mention any limitations like maximum limit or potential absence of memories, but that's minor.

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

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

Two concise sentences with zero waste. The primary action is stated upfront, and the sort order is included. Front-loads the key usage context (no search query) before elaborating.

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 no required parameters, output schema exists, and annotations provide safety and open-world hints. The description covers purpose, usage context, and result ordering. Nothing crucial is missing for an agent to correctly call this tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds 'without a search query' to clarify the tool's scope, but does not add syntax or format details for tag or limit beyond the schema. Baseline 3 is appropriate when schema covers parameters.

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

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

The description clearly states the tool lists 'most recent Finch memories' without a search query, distinguishing it from sibling tools like memory_search which require a query. It also mentions sorting by most recently added, adding specificity beyond the name.

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 says it is useful for browsing or auditing before clearing, but does not explicitly contrast with memory_search or other memory tools. It implies usage context but lacks explicit 'when not to use' or alternative tool 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=true and openWorldHint=true, so the agent knows it is safe and may not be limited to local data. The description adds the specific output fields (total memories, memory space, connected sources), which is useful context beyond the annotations, but it does not disclose any potential latency, limitations, or how 'memory space' is computed. 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 concise sentences, front-loaded with the primary function and content, followed by a brief usage hint. There is no wasted text; 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 zero-parameter, read-only tool with an output schema available, the description covers the essential function and output constituents. It might have mentioned that it provides a summary rather than individual memory records, but the output schema likely conveys the return structure. The description is complete enough for correct invocation.

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

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

The tool has zero parameters and schema description coverage is trivially 100%. With no parameters to explain, the description does not need to add any parameter semantics. Baseline for 0 parameters is 4, and the description correctly avoids inventing unnecessary parameter guidance.

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

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

The description clearly states a specific verb ('show') and resource ('memory stats'), and enumerates the exact content: total memories stored, memory space, and connected sources. This distinguishes it from memory_list/search/context siblings, which focus on listing or searching individual memories rather than providing an aggregate profile.

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

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

The description gives a clear use case ('useful for auditing what Finch knows about you') but does not explicitly mention when not to use it or name sibling alternatives. While it implies a general auditing/overview purpose, it lacks direct comparisons to memory_list or memory_search, leaving the agent to infer the distinction.

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 signal read-only and open-world behavior, and the description adds meaningful behavioral detail: 90-day time-decay sorting and the lexical, non-semantic matching failure mode. This goes well beyond the structured annotations and helps an agent predict results accurately.

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 focused sentences front-load the core operation and follow with the most important caveat plus a clarifying example. No filler, and every clause contributes to correct usage.

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 moderate-complexity read-only search tool with an output schema, the description covers behavior, ranking, usage fit, and limitations. An agent has enough context to decide when to call 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 descriptions cover the basics (query, limit, default 10), but the description adds vital semantics to the main 'query' parameter: it's an exact-token lookup, not a semantic understanding query. This corrects the potentially misleading 'Natural language query' schema label and includes a concrete example.

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: full-text keyword search over stored memories. It also notes 90-day time-decay weighting and explicitly differentiates from semantic/meaning-based tools, making it distinct from siblings like memory_list and ask_finch.

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 states when the tool is a good fit (exact-token lookups such as env var names, contracts, IDs) and gives a concrete negative example for semantic queries. It does not name an alternative sibling for the semantic case, but the exclusion is explicit 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 declare readOnlyHint=false and destructiveHint=false, so the description need not repeat that it mutates data. It adds useful context: packets are saved to vault as type='workflow' with versioning and sharing, and steps can be tool calls or prompts. However, it does not disclose any side effects like overwriting an existing packet with the same name or how updates are reconciled.

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 efficient and well-structured: it states the core purpose first, defines the resource, gives an example, and explains the step format. It is longer than absolutely minimal but every sentence adds clarity, and the concept is inherently non-trivial. The front-loading of the action is good.

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 that creates/updates a multi-step workflow, the description covers the essential concept, provides an example, and mentions persistence details (vault, type='workflow', versioning, sharing). No output schema exists, so no return format is needed. It lacks explicit guidance on how an update is triggered (e.g., by name) but overall the agent has enough to call it correctly in most cases.

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 (name, description, steps, tags) is already explained in the input schema. The tool description adds value by clarifying the structure of a 'step' (tool call with args vs prompt) and the purpose of the 'steps' array, but it does not go beyond the schema's individual parameter descriptions. Baseline 3 is appropriate given high 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 opens with a clear verb+resource: 'Create or update a Packet'. It defines what a Packet is and gives a concrete example ('daily-research' packet with a sequence). It is easily distinguished from siblings like packet_run, packet_list, and packet_share by its focus on creation/updating.

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 when to use it (when you need to create or update a workflow) but does not explicitly guide against alternatives. It never mentions that packet_run executes a packet or that packet_list lists them, leaving the agent to infer routing. No exclusions or conditional recommendations are provided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds useful context by clarifying user scoping ('your Packets') and the storage location (vault), plus what fields are returned. This goes beyond the annotations without contradicting them.

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

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

The description is two compact sentences with no filler. It front-loads the core action and then concisely lists the output fields, making it easy to scan and understand.

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 a single optional parameter and an output schema, the description is complete. It covers scope, resource type, and returned information; the optional search parameter is already documented in the schema.

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

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

The input schema fully documents the only optional parameter, 'search', with 100% schema description coverage. The description does not mention search/filtering, but the schema carries the burden, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists 'all your Packets' and clarifies that packets are reusable workflows stored in the vault. It also specifies the output fields shown, distinguishing it from sibling tools like packet_create, packet_run, and packet_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 explains what the tool does but gives no guidance about when to use it versus alternatives. It does not mention that it should be used for read-only overviews, nor does it point to packet_create/packet_run/packet_share for other operations.

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?

Adds meaningful behavior beyond annotations by describing the output as sequentially formatted steps and specifying how tool steps versus prompt steps should be handled. The destructiveHint=true annotation already signals potential side effects, so the description does not need to restate that, though it could be clearer about whether the call itself has side effects or simply returns steps for the agent to execute.

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

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

Two sentences with no wasted words. The core action is front-loaded, and the second sentence earns its place by explaining how to use the returned steps correctly.

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 tool, the description gives sufficient high-level context: what it accepts, what it returns, and how to consume the return value. With no output schema, it could be more explicit about the exact step format and error behavior, but it is otherwise complete enough for correct invocation.

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

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

Schema coverage is 100% and the only parameter, 'name', is already described as 'Packet name to run'. The description's 'by name' phrasing adds no new meaning beyond the schema, 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?

States a clear verb and resource ('Load and execute a Packet by name') and clarifies that the result is a list of steps for sequential execution. This makes it distinct from siblings like packet_create, packet_list, and packet_share without needing to inspect their 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?

Provides useful post-call guidance: execute returned steps in order, calling tool steps directly and treating prompt steps as instructions. However, it does not name alternatives or state when packet_run should or should not be used instead of packet_list, packet_create, or packet_share; the selection context is only implied.

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

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

Beyond the annotations (destructiveHint=true, openWorldHint=true), the description reveals that every step becomes publicly readable, that copies remain after unpublishing, and that users should re-read for secrets. This materially changes how an agent should approach the call and is excellent behavioral disclosure.

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?

Four sentences, each carrying essential information: purpose, public exposure warning, confirmation requirement, consent rule, and reversal limitation. It is front-loaded with the primary purpose and 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?

Given the destructive/public nature of the action and no output schema, the description is complete enough for an agent to decide when to call it, what precautions to take, and what consequences to expect. 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 coverage is 100%, so the baseline is 3. The description adds genuine value by emphasizing the confirm requirement and by warning not to pass a wallet address for authorName unless the user asks to be identified, which goes 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 ('Publish a Packet to the community') and the outcome ('others can discover and use it'). This clearly distinguishes packet_share from related siblings like packet_create, packet_run, and vault_unpublish.

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 not to publish ('Never publish on the user's behalf without them explicitly asking'), requires confirm: true, and identifies vault_unpublish as the reversal tool. It could more explicitly contrast with local packet creation, but the key usage boundaries are 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 destructiveHint=true and readOnlyHint=false, but the description adds substantial non-obvious behavior: the operation is permanent, it deletes ALL version history, it cannot be undone, and it requires explicit confirmation. This goes well beyond what the annotations provide and is critical for safe 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?

Every sentence earns its place. The warning 'PERMANENT' is front-loaded, the destructive scope is stated immediately, and the safety workflow is packed into a single clear paragraph 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?

For a 2-parameter destructive tool with no output schema, the description covers the essential elements: what is deleted, permanence, confirmation requirement, and the safe invocation workflow. An agent has everything needed to use the tool correctly and avoid irreversible mistakes.

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 explains key and confirm. The description adds meaningful context by reinforcing 'confirm: true' as a hard requirement and by hinting that entries have a title an agent should display to the user. This is modest but real added semantic value above 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 names a specific verb and resource ('Delete a Finch Vault entry and ALL of its version history'), establishes permanence, and clearly distinguishes the operation from browse/read tools like vault_list and vault_history. An agent can immediately identify what this tool does and what makes it different.

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 procedural guidance: use vault_list to browse first, and show the user the exact entry (key + title) before confirming. It also states the confirm: true requirement. It lacks an explicit 'when not to use' clause, but the workflow instructions are strong enough to rate above baseline.

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 readOnlyHint=true, so the tool is expected to be non-destructive. The description adds beneficial context by explaining the output format: 'Shows lines added (+) and removed (-)', which goes beyond the schema and annotations. It also clarifies the direction of comparison (fromVersion to toVersion), helping the agent understand the behavior. This exceeds baseline given the annotations cover safety.

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 highly efficient: a single sentence of 25 words. It front-loads the core purpose (compare two versions) and immediately provides a memorable analogy (git diff) to aid understanding. The detail about the output format is included without extra fluff, and every word 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?

With 3 parameters, all required and fully described, the tool is relatively straightforward. The description covers the purpose and output format, and the schema handles parameter details. No output schema exists, but the description hints at the return format (added/removed lines). This is adequate for an agent to invoke the tool correctly, though more explicit notes on error cases or limits would be nice.

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

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

The schema has 100% coverage, describing each parameter (key, fromVersion, toVersion) with types and descriptions. The description adds value by indicating that fromVersion is the older version and toVersion is the newer version, which is not explicitly stated in the schema. This clarifies the semantic ordering, which is crucial for correct invocation.

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

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

The description clearly states the tool's purpose: to compare two versions of a Vault entry, analogous to git diff. It specifies the resource (Finch Vault entry) and the operation (comparing versions), distinguishing it from sibling tools like vault_read (which presumably reads a single version) and vault_history (which might show all versions). The analogy to git diff immediately conveys the expected behavior.

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?

While the git diff analogy implies appropriate use cases (e.g., reviewing changes between versions), the description does not explicitly state when to use this tool versus alternatives like vault_history or vault_read. It lacks explicit guidance on when not to use it or which sibling to choose instead. The usage is implied but not directly instructed.

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 readOnlyHint annotation already establishes non-destructiveness, and the description adds that the output is a 'structured bundle' covering the full vault or a type. It does not disclose output format details or sensitive aspects like whether the credential type is included, so it adds only modest behavioral context beyond the annotations.

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

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

Two efficiently structured sentences: the first delivers the core action and scope, the second provides relevant use cases. There is no filler, redundant phrasing, or buried 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?

With one optional parameter and a readOnly annotation, the description covers basic invocation. However, there is no output schema and 'structured bundle' is vague about the actual return format, size implications, or handling of sensitive credential data, leaving an agent without full context for consuming the result.

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

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

The input schema fully documents the single optional type parameter, including its enum and meaning. The description restates the optional-type idea in plain language ('entire ... or a specific type') but adds no semantic detail 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 states a specific verb ('Export'), resource ('Finch Vault'), and scope ('entire ... or a specific type'), along with the deliverable ('structured bundle'). This clearly differentiates it from vault_read, vault_list, and vault_save by framing it as a bundle-producing export 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 explicit use cases: archiving, syncing to GitHub, and passing context to another agent. It does not state when not to use it or point to alternatives like vault_read or vault_list for direct in-place reads, so it falls just 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 declare readOnlyHint=true, covering the safety profile. The description adds genuinely useful behavioral context beyond that: the ownership scoping ('Only returns credentials owned by the authenticated user'), which tells the agent that requesting someone else's credential will yield nothing. This is meaningful context that annotations do not convey, though error/not-found behavior is not disclosed.

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

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

Two sentences with zero waste: the first states the action and target, the second adds the ownership constraint. The primary verb and object are front-loaded, and every clause earns its place.

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

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

For a single-parameter, read-only tool with 100% schema coverage, the description covers the essential semantics: what is retrieved, how it is identified, and a key access constraint. The only gap is behavior for a non-existent credential (error vs. empty result), but this is minor given the tool's simplicity and the annotations covering safety.

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

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

Schema description coverage is 100% and the parameter description ('Credential name as used in vault_store_credential') already fully explains the expected value with a reference to the corresponding writer tool. The description itself adds no parameter detail, so the baseline of 3 applies.

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

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

The first sentence names a specific verb ('Retrieve'), a specific resource ('stored credential from the vault'), and the retrieval key ('by name'). The second sentence adds the ownership scope ('owned by the authenticated user'). This clearly distinguishes vault_get_credential from sibling tools like vault_list, vault_search, and vault_history without needing to open their 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?

Usage is implied rather than stated: the schema's parameter description references vault_store_credential, hinting that this is the read counterpart to a store operation. However, there is no explicit guidance on when to choose this over siblings like vault_read or vault_search, and no when-not-to-use 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?

Given readOnlyHint=true is already present, the description adds meaningful behavioral content by describing the returned information: commit message, author agent, size, and timestamp. It also communicates that the operation is non-mutating through 'get' and 'shows.' No contradiction with annotations.

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

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

Two short sentences with no filler. The purpose is front-loaded, the git log analogy clarifies behavior quickly, and the output fields list is a compact, high-value addition.

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

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

This is a simple read-only tool with one fully documented parameter and no output schema. The description sufficiently explains what will be returned (each version with metadata), and nothing critical 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?

The schema already fully documents the single key parameter with 100% description coverage. The description adds little beyond reinforcing that the key identifies a 'vault entry,' which is consistent with the baseline for complete 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—'Get the full version history of a Finch Vault entry'—with a strong mental model via 'like git log.' This clearly distinguishes the tool from siblings such as vault_read, vault_diff, and vault_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 description gives clear context for when to use the tool: whenever the full chronological version history of an entry is needed. It does not explicitly name alternatives or exclusions, but the 'version history' framing provides enough guidance for an agent to choose appropriately.

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

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

Annotations already established idempotency and non-destructive behavior. The description adds the concrete fact that 'duplicate links are updated in-place', which gives useful operational clarity beyond the hint. No contradiction or misleading behavior is 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?

The description is compact and well-structured: a purpose statement, a list of valid relations, an example, and a behavioral note. It is front-loaded with the most important info. The relation list slightly duplicates the schema enum but is still useful for readability and remains concise.

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

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

The tool is a simple write operation with a complete schema and no need for output documentation. The description covers purpose, relation semantics, an example, and duplicate handling. It does not mention potential prerequisites like, that both entries must exist, which is an assumption but not a critical omission given the tool's simplicity.

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 clearly defined (fromKey: source, toKey: target, relation: relation type). The description adds an example and repeats the relation names, but it doesn't introduce new parameter semantics beyond what the schema already provides. 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 states a specific verb ('Create') and resource ('semantic relation between two Finch Vault entries'), clarifies it builds a knowledge graph, and lists the exact relation types. This clearly distinguishes it from read-only siblings like vault_read or vault_related, which focus on retrieving entries or links.

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 concrete usage examples ('link a synthesis entry...', 'mark a newer analysis as supersedes...'), giving an agent a clear sense of when to use the tool. However, it doesn't explicitly contrast with alternatives such as vault_related for reading links, 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 indicate readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral context beyond annotations by stating that results are previews, not full content, which sets correct expectations for what the tool returns.

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 most important facts are front-loaded: what the tool does名言 and the preview limitation. 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 filtered-list tool with four optional parameters, full schema coverage, an output schema, and read-only annotations, the description is complete. It covers the tool's scope, filters, and return behavior without requiring additional 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?

The input schema has 100% description coverage for all four parameters, so the schema already documents each parameter clearly. The description adds only a high-level mention of 'type, agent, or pinned status,' which does not materially go beyond the schema.

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

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

The description uses a specific verb and resource: 'List Finch Vault entries.' It also clarifies what kind of operation this is by mentioning filter dimensions and that it 'Returns previews, not full content,' which distinguishes it from full-content readers like vault_read.

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

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

The description implies when to use this tool: when you want a filtered list or overview of Vault entries. It does not explicitly name sibling alternatives such as vault_search or vault_read, nor does it state when not to use this tool, so guidance is present but mostly inferred.

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

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

The description discloses a meaningful observable effect beyond the annotations: 'Pinned entries always appear first in vault_list and are prioritized in memory_context and search results.' This tells the agent the downstream consequences of pinning, which is valuable context that idempotentHint=true and destructiveHint=false alone do not convey. It does not contradict the annotations; the reversible toggle nature is consistent with idempotentHint=true.

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: sentence one states the action, sentence two explains the behavioral effect, and sentence three gives the use case. It is front-loaded with the core operation and contains zero filler.

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

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

For a simple 2-parameter tool with 1 required parameter, full schema coverage, and safety annotations (idempotent, non-destructive), the description's coverage of what, effect, and when is sufficient for an agent to call it correctly. The only unstated detail is the return payload after pinning, which is a minor gap for a toggle operation with no output schema.

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

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

Schema description coverage is 100% — both `key` ('Entry key to pin or unpin') and `pinned` ('true to pin, false to unpin (default: true)') are already documented in the schema. The description's general pinning semantics complement but do not add parameter-specific detail beyond what the schema provides, so the 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 dual verb and resource: 'Pin or unpin a Finch Vault entry.' This clearly distinguishes it from sibling operations like vault_save, vault_tag, or vault_delete, and the 'Finch Vault entry' scope separates it from the memory_* family. The dual pin/unpin behavior is stated upfront, matching the `pinned` boolean parameter.

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 final sentence, 'Use for your most important research, key prompts, or canonical references,' provides explicit selection criteria for when this tool is appropriate. However, it does not name alternatives or exclusion conditions (e.g., when to prefer vault_tag or vault_save instead), so it offers clear context without explicit when-not-to-use guidance.

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

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

Annotations already carry readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the return payload (full content, version, tags, linked entries). It does not contradict the annotations and is consistent with the read-only nature, though it omits behavior for missing keys.

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 states the core action and the return shape with zero wasted words. The most important scope constraint ('by its key') appears early.

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, single-parameter read operation with annotations covering its safety profile, the description is nearly complete: it names the input and the return fields. Minor gaps are the absence of error behavior for nonexistent keys and explicit sibling differentiation, but these are not critical for a simple read tool.

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

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

Schema description coverage is 100%, so the sole parameter 'key' is already documented with an example in the schema. The description reiterates reading 'by its key' but adds no new semantic detail beyond what the schema provides, keeping this at the baseline of 3.

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

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

The description states a specific verb and resource ('Read a Finch Vault entry by its key'), and the qualifier 'by its key' clearly distinguishes it from search/list/history siblings. An agent can tell this is the single-entry-by-key read operation without opening any other 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?

No guidance is given on when to use this tool versus alternatives like vault_search or vault_list, and no exclusions are stated. The appropriate trigger (knowing an exact key) is only implied by the parameter shape, never made explicit.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds genuinely useful behavior beyond the annotations: it discloses bidirectional traversal (outbound links and inbound links) and the ability to filter results. It doesn't specify edge behavior such as handling of nonexistent keys or traversal depth, but the read-only nature covers the most important risk.

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

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

Three sentences with minimal fluff; the first sentence front-loads the purpose, and the second and third each add worthwhile value (return bundle and filter semantics). Minor redundancy exists between 'Traverse the Finch Vault knowledge graph' and 'get all entries linked to a given entry,' but it reads naturally.

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 2-parameter tool with a fully described schema and a read-only annotation, the description is nearly adequate. The main gaps are unstated traversal depth behavior (are linked entries one hop or recursive?) and no mention of what the returned entries contain; since no output schema exists, the description carries a small burden it partially meets.

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 `key` and `relation` are already fully documented, including the enum with per-value descriptions. The description's 'derived entries, superseded versions, continuations' restates enum domains in business terms, adding mild semantic color, but no genuinely new format, syntax, or interaction details.

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 operation ('get all entries linked to a given entry') on a specific resource (the Finch Vault knowledge graph) and details the scope by explicitly noting it returns both inbound and outbound links. It's clearly distinguishable from siblings like vault_read (single entry) or vault_search (content search), though it never actually names a 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?

The final sentence gives partial guidance on when to filter ('to find only derived entries, superseded versions, continuations, etc.'). However, it offers no explicit statement of when to use this tool versus alternatives like vault_read, vault_list, vault_link, or vault_search, and no exclusions or prerequisites.

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

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

Discloses non-obvious behavior beyond annotations: same key triggers git-style version snapshot and patch to v+1; 10MB entry limit; content over 600KB auto-offloads to blob storage. This is exactly the kind of behavioral context annotations cannot convey.

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?

Four dense, purposeful sentences with no filler. Versioning behavior, type constraints, size limits, and sibling alternatives are all front-loaded efficiently.

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?

Very strong overall for a 10-parameter tool with no output schema, covering update semantics, limits, and alternative tools. However, it misses the 'credential' enum value and does not mention vault_store_credential as the likely alternative for credentials, leaving a real routing 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 baseline is 3. The description adds real value though: it explains the key semantics ('Same key = update'), enumerates accepted types, and reveals size/offload constraints. Minor omission: the schema enum includes 'credential' but the description's type list omits it.

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

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

States a specific action ('Save or update a versioned artifact') on a clear resource (Finch Vault), with the key behavior of same-key updates and explicit differentiation from memory_add and code_session_save. The versioning semantics are immediately understandable.

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

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

Explicitly names alternatives and conditions: use memory_add for quick unstructured notes, and code_session_save for coding sessions. This gives an agent clear routing guidance beyond the tool's own schema.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering safety and openness. The description adds genuinely useful behavioral context beyond that: results are ranked by lexical/near-word matching, and the tool returns previews. This helps the agent calibrate expectations about query sensitivity and output content.

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

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

Three sentences with no filler: the first sentence identifies the tool, the second explains matching behavior and query strategy, the third notes filtering and output. Every sentence earns its place, and the most important information is front-loaded.

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

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

For a search tool with a full input schema and an output schema, the description covers the essential behavioral distinction (lexical vs semantic), query strategy, optional filtering, and output format in the form of ranked previews. Nothing an agent needs to invoke 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%, and the schema already documents query semantics ('specific keywords work better'), type filtering, and limit behavior. The description reinforces the query guidance but does not add meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The first sentence states a specific verb ('Search'), resource ('Finch Vault'), and scope ('titles, content, and tags'). It also distinguishes this tool from semantic/embedding search by explicitly saying 'This is lexical matching, not embeddings', so an agent can tell it apart from related search tools 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 gives clear usage context: it is full-text/lexical, so short specific phrases work better than long abstract descriptions, and it optionally filters by type. It stops short of naming explicit alternative tools or saying 'use X instead when...', but the guidance is sufficient to select and use the tool 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?

Beyond what annotations state (readOnlyHint=false, destructiveHint=false), the description reveals that credentials are stored under type=credential, are excluded from normal search and export, and persist across agent sessions. This is behavior an agent cannot infer from annotations alone.

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

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

Two tight sentences. The first states the core purpose and key constraints (secure storage, type=credential, excluded from search/export). The second explains the intended use case. No filler or redundant phrasing.

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 store operation, the description gives the essential behavioral facts (type and exclusion) and a motivating use case. It does not state what happens on name collision, but that is a relatively minor missing detail and not likely to mislead an agent attempting to store a credential.

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% parameter description coverage, and the description does not add parameter-specific syntax or format details. That is acceptable; the baseline of 3 applies because the schema already documents name, value, and description, and the description conveys the storage context without duplicating parameter explanations.

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 (store) and resource (credentials in the vault), and immediately specifies the scope: API keys, tokens, or secrets. It also adds a distinguishing trait (type=credential, excluded from normal search and export) that separates it from sibling tools like vault_save or vault_search.

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 clear usage context: use this when you need to persist API keys, tokens, or secrets and have them accessible across agent sessions. It does not explicitly exclude other uses or mention alternatives, but the storage scope is precise enough for an agent to decide when to call it.

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 a mutating but non-destructive, idempotent operation. The description adds valuable context by specifying that content is untouched and that replace=true overwrites existing tags, which clarifies the scope of the mutation beyond the raw annotation flags.

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 deliver the core action, the scope constraint, the use case, and the key parameter behavior. Every sentence carries useful information, with the main purpose front-loaded and no redundant 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 three-parameter tool with full schema coverage, the description is complete: it states the operation, the target, the non-destructive constraint, the use case, and the replace behavior. The annotations cover safety and idempotency, and no output schema is expected, 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?

Schema coverage is 100%, so the baseline is 3. The description adds meaning by emphasizing the target must be an existing Finch Vault entry and by clarifying the replace behavior in plain language, reinforcing the schema's parameter descriptions without contradicting 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 names a specific verb and resource: 'Add or replace tags on an existing Finch Vault entry.' It also distinguishes itself from content-modifying tools by stating 'without modifying its content' and clarifies it targets only tags, which separates it from siblings like vault_save.

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

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

It provides clear context: this is for organizing entries retroactively on existing entries, not for creating or editing content. However, it does not explicitly name alternative tools or state when not to use it, though the 'without modifying its content' phrasing implicitly excludes content-editing workflows.

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 what the annotations say, the description adds an important behavioral caveat: previously copied content still remains with the recipients. This discloses a real, non-obvious consequence of the operation and helps an agent set correct expectations.

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

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

The description is two sentences with no filler. It front-loads the core action and the intended use, then adds the key behavioral caveat. 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 one-parameter tool with supportive annotations and no output schema, this description is complete: it explains the action, the usage, the limitation, and the examples in the schema. An agent has what it needs to decide and invoke correctly.

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

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

The schema already has 100% description coverage for the single `key` parameter, including a concrete example. The tool description doesn't add new parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description names the specific operation: making a shared Vault entry private and removing it from the public community listing. It also explicitly differentiates the action from related sharing/publishing flows by naming packet_share, so an agent can tell the tool apart from siblings like vault_delete and packet_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?

It tells the agent exactly when to use the tool: to reverse vault publishing or a packet_share. It also gives practical boundaries by explaining that unpublishing stops future discovery but does not retract content already copied, which helps an agent avoid choosing the wrong cleanup action.

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

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

The description goes well beyond the annotations by warning that signatures are not inert, that they can authorize off-chain orders and session logins, and that a crafted string can move real value without an on-chain transaction. It also discloses the confirm requirement and the provenance rule for challenges, which is critical behavioral context annotations cannot convey.

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 longer than average, but every sentence earns its place for a security-critical endpoint. It front-loads the CAUTION, states the legitimate use, explains the risk, and gives concrete operational instructions. There is no filler.

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

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

For a mutating, open-world wallet-signing tool, the description covers the purpose, the risk, the mandatory confirm flag, the exact user-facing expectation, and the provenance rule for challenges. No output schema exists, but the absence of a return-value description does not hamper correct invocation given the tool's primary risk is in the signing action itself.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by explaining that confirm guards against attacker-supplied text and that message must be shown verbatim to the user, reinforcing why both parameters exist and how they interact.

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 ('Sign'), a clear resource ('an arbitrary message with the user's wallet'), and the exact standard (EIP-191 personal_sign). It clearly distinguishes this from sibling wallet tools like get_wallet_address and get_wallet_balance, which are read-only address/balance lookups.

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 states when to use this tool ('proving wallet ownership and auth challenges') and gives explicit safety-based usage constraints, such as requiring confirm: true and showing the user the exact text. It does not name alternative signing tools, but none appear among siblings, so the use-case framing plus safety guardrails are sufficient.

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