willow-mcp
Server Quality Checklist
Latest release: v2.13.0
- Disambiguation3/5
Namespaced prefixes (store_, grove_, knowledge_) separate domains clearly, and most tools have well-distinguished purposes. However, with 134 tools, an agent could easily confuse similar verbs across families (e.g., store_delete vs gap_delete, or grove_watch vs grove_watch_all) and the descriptions, while thorough, add to a high cognitive load for selection.
Naming Consistency3/5Uses lowercase snake_case consistently, but the verb-first vs noun-first patterns are mixed: some tools are verb_noun (store_put, gap_log, fork_merge) while others are noun_verb (integration_status, statement_reconcile, fleet_health). Prefixes are composable but not perfectly uniform, and a few oddities (kb_at, whoami) break the pattern.
Tool Count1/5At 134 tools, this is far beyond even a 'large' toolset; the rubric caps 'too many' at 25+ and describes 50+ as extreme mismatch. Even if each tool is individually useful, no agent can reasonably discover or disambiguate among this many tools in one server, making it practically unusable as a coherent unit.
Completeness4/5Within each domain the CRUD/lifecycle coverage is remarkably complete (e.g., store has get/put/update/delete/search/purge, forks have create/join/log/merge/delete/status). The only gaps are deliberate exclusions (e.g., no hard delete) or missing operations that are 'CLI-only' by design (e.g., no tool to ratify federated servers).
Average 4/5 across 130 of 134 tools scored. Lowest: 1.5/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 554 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under Apache 2.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says 'preset: override standing default', which implies a state-changing operation, yet annotations declare readOnlyHint=true. This is a direct contradiction – the tool appears to modify a default even though it is marked read-only. The description provides no further behavioral context (e.g., what exactly is resolved, what 'apply' does, side effects) beyond the annotations, and the contradiction makes the behavior unreliable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short but not concise in a useful way – it uses cryptic fragments ('AS-8', 'checkbox IDs') without expository context. It is not front-loaded with the most critical information (required params), and it lacks a clear structure that would help an agent parse the tool's purpose and parameters quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters (2 required), no output schema, and cryptic jargon, the description is far from complete. It does not explain what an exposure preset is, what 'seed destination' means, what the tool returns, or how to use the required `app_id` and `agent_id`. The annotations cover safety but not usage context. An agent would have to guess or introspect other tools to understand this one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry meaning for all parameters. It briefly explains `destination` (enumerates values), `preset` ('override standing default'), and `fields` ('custom dotted paths (checkbox IDs)'), but it completely omits `app_id` and `agent_id`, which are required. The explanations are terse and do not give full semantics (e.g., what values for `preset` are allowed, how `fields` are formatted, or the purpose of the IDs).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5Does the description clearly state what the tool does and how it differs from similar tools?
The definition states a verb ('Resolve and apply') and a resource ('exposure preset for a seed destination'), but the resource is opaque jargon ('AS-8', 'seed destination') with no definition of what an exposure preset is or what 'resolve and apply' means operationally. It does not distinguish itself from any of the numerous sibling tools, and the purpose remains ambiguous for an agent encountering it fresh.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to call this tool versus any alternative. The description lists possible values for `destination` but gives no context about when a caller would want this tool, what prerequisites exist, or what conditions favor it over other exposure-related tools such as exposure_config_get or agent_seed_mirror. No sibling is referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, openWorldHint, and destructiveHint, which cover the main behavioral aspects. The description adds that it returns rows and lists fields, but does not disclose additional behavior such as error handling, pagination, or side effects. Since the annotations cover the primary traits, a score of 3 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using a single sentence plus a list of fields. It is straightforward and avoids unnecessary verbosity. The structure is simple and readable, though the field list embedded in a sentence could be more formally organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the return fields but lacks parameter explanations and any mention of output schema (though an output schema is indicated to exist). Without parameter semantics, the tool is not fully usable. The presence of many sibling tools with similar purposes also requires more contextual clarity, but the description does not address this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Neither the description nor the input schema explains the parameters 'limit' and 'app_id.' The schema lacks any descriptions (0% coverage), and the description does not mention them. Users have no guidance on what these parameters control or how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly indicates the tool returns fleet status rows and explains the content (presence and agent activity). It lists the fields in each row, making the purpose evident. However, it does not explicitly state the action (e.g., 'returns' or 'gets'), though this is implied.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the many sibling tools (e.g., grove_agents, fleet_status). No comparison or selection criteria are given. The only hint is 'Requires grove_read,' which is a permission note, not usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Provides details about security scanning, network isolation, and authorization requirements, but no clear statement on side effects or error handling. Repetitive text may confuse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness1/5Is the description appropriately sized, front-loaded, and free of redundancy?
Very long and repetitive, with similar paragraphs repeated three times, making it verbose and inefficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers security context but lacks explanation of output format, error conditions, and parameter semantics; incomplete for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No description of parameters; schema has zero coverage; only vague mentions of authorization fields in security text, but not systematic explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb 'Submit' and resource 'task to Kart sandboxed execution queue'. Clear and distinct from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives; only mentions that signing is via CLI, not MCP, but doesn't direct agent when to call this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by detailing the permission requirements and that this is an egress operation, and it warns that stubs refuse when prerequisites are unmet. It does not mention side effects or return behavior, but given the openWorldHint and readOnlyHint are false, some of this is expected. It provides useful failure-mode information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The first sentence is concise and to the point. The second paragraph, while explanatory, is somewhat verbose with metaphors like 'egress needs THREE keys' and could be streamlined, but it remains readable and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the expected response format, error handling beyond 'stubs refuse', and meanings of the parameters. Since there is no output schema, this is a notable gap. An agent would struggle to invoke the tool correctly and interpret results, making it incomplete for a complex API-calling operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the six parameters (app_id, name, method, path, body, params). With zero schema description coverage, the agent receives no guidance on what these parameters mean or how to format them, making it impossible to use the tool correctly without external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: calling an external API through a registered integration adapter. It provides a specific verb and resource, distinguishing it from other tools like integration_status. However, it does not explicitly name sibling alternatives, so it falls short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the three prerequisites (integration_net capability, operator's consent, and an egress lease) and notes that stubs will refuse if any are missing. It does not, however, compare this tool to alternative calling tools or state when it should be chosen over them, leaving usage guidance somewhat implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description ends with 'Read-only,' but the annotations declare readOnlyHint=false. This is a direct contradiction about whether the tool modifies state, which is a serious transparency failure for an agent relying on the description. The extra context about checklist, envelope, and findings is useful, but the contradiction overrides it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately compact and front-loaded with the orchestrator context and verification goal. The em-dash list efficiently conveys the key checkpoints. The brief 'Read-only' sentence is short and clear, though it hurts the overall definition because it contradicts the annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity verify tool with two required parameters and no output schema, so the description captures the core purpose and timing. However, it does not state what a successful or failed verification returns, and it gives conflicting safety signals due to the readOnly contradiction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the two parameters. It only implies that app_id and dispatch_id identify a dispatch, but it does not explain the expected format, ownership, or relationship. The description does not provide enough semantics beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: it checks a completed dispatch's handoff and confirms the closeout exists and its declarations hold. The bulleted checks clearly distinguish this from generic handoff reading or writing, though it does not explicitly name a sibling like handoff_read to reinforce the distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage timing: 'Run this before agent_clear releases the specialist for its next packet.' This anchors when the tool should be invoked, but it does not describe when not to use it or what alternative to choose if verification isn't needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotency and non-destructiveness. The description adds value by revealing the signature verification behavior when WILLOW_PGP_FINGERPRINT is set and the need for ratified status. It does not contradict annotations and provides some context beyond what the annotations specify.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no fluff. The core purpose is front-loaded, and the second sentence packs the prerequisite and parameter options efficiently. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main action and the slice parameter, and it mentions the signature verification condition. However, it does not define app_id and agent_id, nor does it explain the return value or any side effects. Given the moderate complexity, it leaves some gaps that an agent would need to infer from context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'slice' parameter with its allowed values, but app_id and agent_id are not described at all. The description only partially covers parameter meanings, leaving two of three unspecified, which is insufficient for a tool with zero schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Mirror a ratified home seed into SOIL collection willow_agents_seeds (AS-5).' It names the verb, resource, and destination, making the tool's purpose clear. It doesn't explicitly differentiate from siblings but the action is distinctive enough to avoid confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a prerequisite ('Requires ratified status') and a conditional requirement (signature verification if the fingerprint env var is set), but it does not explicitly state when to use this tool versus alternatives. No guidance is given on when not to use it or which sibling tools to prefer in other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses deterministic ordering (alphabetical within each hop) and the token-budget stopping condition. This adds meaningful behavioral context. It does not mention any output shape or side effects, but for a read-only graph walk the annotation covers the main safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the algorithm and include a useful parameter clarification. The final 'Read-only.' is somewhat redundant with the annotation, but the overall size is appropriate and focused.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description does not explain what the returned context looks like or how the token budget affects the result. It also omits semantics for the required app_id and optional db_path parameters. A graph-walk tool with this complexity needs more detail to be successfully invoked.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema_description_coverage at 0%, all parameter semantics must come from the description, but only anchor is explained ('symbol name or fqn'). app_id, db_path, hop_depth, and max_tokens are left to inference from their names, and app_id/db_path remain ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific operation: BFS traversal from an anchor symbol along import and inherit edges until a token budget is reached. The verb+resource (BFS walk on code graph) is specific, but it does not explicitly distinguish itself from sibling code graph tools like code_graph_explain or code_graph_impact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to prefer this tool over its siblings (code_graph_explain, code_graph_search, code_graph_impact, etc.). The intended use case is implied by the BFS description, but there are no explicit conditions, exclusions, or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Behavioral traits are disclosed beyond the annotations: it records an 'acknowledged' history entry that is never erased, alters state to stop surfacing a mismatch, and returns unknown_uid if the commitment does not exist. This is additive to the provided idempotentHint and destructiveHint, giving a clearer model of side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and reasonably concise, but the metaphor 'split-stick halves match again' is extraneous and may confuse rather than clarify. The structure is simple, though the metaphor could be replaced with a direct explanation for better clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description explains the action and its effect, it does not provide context on what a 'commitment' is, the role of uid and app_id, or any prerequisites (e.g., whether the commitment must exist beforehand). The lack of parameter elaboration and the absence of an output schema description besides the unknown_uid return leave it incomplete for a standalone call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines two parameters (uid and app_id) without any descriptions, and the tool description does not mention or explain these parameters at all. With schema coverage at 0%, the description fails to compensate, leaving an agent without any guidance on what values to provide or what they represent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action as 'Mark a commitment change as seen by the operator' and explains the effects: recorded as an acknowledged history entry (never erased) and stops surfacing as a mismatch. It also notes the return value for missing commitments. The cryptic metaphor 'split-stick halves match again' adds some ambiguity, but the core purpose remains unambiguous and distinct from sibling tools like commitment_ingest or commitment_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the appropriate usage condition: when a commitment change needs to be acknowledged and no longer should appear as a mismatch. However, it does not explicitly name alternative tools or state when not to use it, leaving some inference needed. The lack of explicit comparison to similar tools (e.g., commitment_ingest, grove_ack) reduces the guidance offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false, so the safety profile is already clear. The description adds a behavior detail: it checks each record for a non-empty source field, and returns a structured object with specific fields including pass/warn/fail outcome. This adds value beyond annotations. However, it doesn't disclose what triggers 'warn' vs 'fail' thresholds, or how limit/domain affect the scan. Some behavioral ambiguity remains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at three sentences, front-loads the core purpose, and includes the return structure. It's efficient without fluff. Minor deduction for not explaining parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only verification tool with annotations covered, the description is reasonably complete but leaves gaps: no explanation of how 'limit' interacts with scanning (does it scan all records or just first N?), what 'domain' filters, and what the 'recommendation' field contains. Given the existence of a clear return schema in prose, it's adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the three parameters (app_id, limit, domain), and the description only mentions checks on knowledge records without explaining the meaning of app_id, limit, or domain. The description does not compensate for the lack of schema documentation. An agent would need to infer usage from parameter names, which is risky for 'domain' and 'app_id' roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific and unambiguous purpose: verify source provenance of knowledge records, checking each for a non-empty source field. The verb (verify) and resource (knowledge records) are clear. It doesn't explicitly distinguish from the sibling tools knowledge_check or frank_verify, but that's partially mitigated by the named dependency on knowledge_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says it requires 'knowledge_read' permission, which is a precondition but not a usage condition. It doesn't explain when to use this tool versus knowledge_check or other verification tools. There's no when/when-not guidance beyond the inherent 'verification' context. This is minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions the permission requirement (grove_read) but adds no information about side effects, return format, pagination, or rate limits. The read-only nature is already implied by the annotation, so the description adds little beyond what's already known.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using only two sentences to convey the essential purpose and parameters. There is no redundancy or unnecessary detail, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description provides enough context for the primary use case, but it omits the 'app_id' parameter and does not elaborate on the behavior of flags (e.g., whether they are boolean or have states). Given the tool's simplicity, it is reasonably complete but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'flag' parameter by listing valid values and clarifies 'channel_name' as an optional restriction. However, it omits the 'app_id' parameter present in the schema, leaving its purpose unexplained. Schema coverage is 2 of 3 (66%), and the description adds some meaning but is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and the resource (messages) with a specific filter (by flag). It distinguishes from other grove tools by focusing on flags, though it doesn't explicitly differentiate from grove_search or grove_get_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides some usage context: 'across all channels (or one channel)' and mentions the permission 'Requires grove_read.' However, it does not explain when to prefer this tool over alternatives like grove_search or grove_get_history for listing messages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the fact that it 'Requires grove_read' permission, which is useful context beyond the annotations. However, it doesn't describe any other behavioral traits, such as whether the thread is flattened or nested, or any ordering.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with two sentences that get to the point. The primary action and key parameter are front-loaded. It could be improved by adding a brief note on when to use it, but for its size, it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one key parameter and no output schema. The description conveys the core purpose and the required parameter. However, it lacks detail on the expected output format (e.g., does it return a list of messages?) and any special behavior like error conditions. Given the low schema coverage, it could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description mentions 'message_id: ID of the parent message', which adds clarity to the purpose of that parameter. However, it does not explain the role of app_id at all, so the coverage is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves 'a message and all its replies', specifying the resource (message thread) and the action (get). It is distinguishable from siblings like grove_get_history and grove_get_identity by explicitly mentioning replies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. No exclusions or conditions are given. 'Requires grove_read' is a prerequisite, but not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint=false annotation, the description discloses that it is read-oriented yet leaves a hash-chained ledger, indicating side effects. It also states it 'never guesses' and mentions integrity checks, providing additional behavioral expectations not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is verbose with multiple clauses and parenthetical asides, making it longer than necessary. It could be streamlined to focus on the core action and key conditions without the repetitive phrasing about 'served,' 'queued,' and 'unavailable.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately explains the possible return statuses (served, queued, unavailable) and the associated resolved tool or reason. It covers the main scenario but omits details like error formats or edge cases, which is acceptable for a routing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes query and app_id with no descriptions, and the description provides no information about these parameters. Schema coverage is 0%, and the description does not compensate by explaining their roles or expected formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool routes a natural-language intent to the appropriate willow-mcp verb, providing a specific action and resource. It also distinguishes this from merely searching or executing, and the mention of 'human-sealed phrasing' and 'match threshold' adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the routing behavior and status outcomes but does not specify when a user should choose this tool over alternatives like agent_route or dispatch_send. There is no explicit context or condition for use, leaving the agent to infer applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond annotations by explaining that the `by_human` flag is sourced from the caller's identity (server env or OAuth binding), never from the app_id. It also emphasizes the record is durable and cannot be forged by providing a custom attested_by. This adds meaningful behavioral context beyond the generic readOnly/destructive hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise but contains some redundancy; the concept of the attester being the calling identity is stated twice in different forms. The structure is a single paragraph plus a clarifying note, which is acceptable but could be tightened to reduce repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the core function and a key security behavior, but lacks details about expected return values, error conditions, or side effects beyond creating a durable record. It does not mention whether the record is immediately visible to other tools or if there are any constraints on status values. Without an output schema, the description should provide more completion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only clarifies the role of app_id (it's not used for attribution). It does not explain the meaning or constraints of key parameters like status, statement, evidence_ref, or subject_type. Required vs optional fields are not elaborated, leaving the agent uncertain about valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary action: 'Create a durable attestation/rejection/change-request record'. It specifies the subject types and statuses, and clarifies that the attester is the calling identity, which distinguishes it from related list/query tools like human_attestation_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It mentions the attester is the calling identity but does not state conditions for use (e.g., 'use this when you need to log a human attestation') or contrast with sibling tools like human_required_enqueue or human_attestation_list. No 'when not to use' is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive; the description adds that items are returned 'newest first' and include a 'by-status tally,' which are behavioral details beyond what annotations provide. It also clarifies the default filter behavior, making the tool's behavior transparent for a read-only list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, front-loading the main purpose and then adding the most critical parameter detail. Every word earns its keep, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema, the description is thin. It does not define `app_id` (a required parameter), the `kind` or `limit` parameters, or explain the structure of the 'by-status tally.' An agent would have to guess at required inputs and response format, making this description incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only elaborates on the `status` parameter ('defaults to open; pass "" for all'). Other parameters (`kind`, `limit`, `app_id`) receive no explanation, leaving `kind` especially ambiguous and failing to compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'human-required queue items', and adds ordering ('newest first') and output detail ('by-status tally'). It is specific, though it does not explicitly differentiate from the similarly named sibling 'grove_human_required', so it loses one point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description: it lists items that need human attention. The note about `status` defaulting to 'open' and passing '' for all gives a usage hint, but there is no mention of when to use this tool versus alternatives or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the readOnlyHint/destructiveHint annotations by enumerating the output components and giving symbol format examples. The 'Read-only' note reinforces the annotation accurately. It doesn't contradict annotations and provides useful behavior context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core action, and every sentence adds value. It lists expected output, clarifies symbol naming, and notes the read-only property without redundancy. No irrelevant or repeated information beyond the safety hint, which is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description states what will be returned and how to specify `symbol`, but does not explain `app_id` or `db_path`, and offers no guidance on prerequisites or when this tool should be selected over closely related sibling tools. There is no output schema, so more explicit information about return structure or error behavior would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry the burden for all parameters. It does explain the `symbol` parameter well with format and examples, but `app_id` and `db_path` are completely undocumented. Since two of three parameters lack any semantic guidance, the description only partially compensates for the schema's gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Explain a symbol') and the resource, specifying that it returns the signature, file location, and inbound/outbound edges. It is easy to understand what the tool does. However, it does not explicitly distinguish this from sibling tools like code_graph_walk or code_graph_search beyond the output details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies an appropriate use case: to explain a symbol by getting its signature, location, callers, and callees. It does not provide explicit guidance on when to use this tool versus related code_graph siblings, nor does it mention exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, so the explicit 'Read-only' phrase adds no safety information. However, the detailed matching order and the effect of omitting kinds do provide behavioral context beyond the annotations and schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very compact and efficient: a meaningful matching chain in the first sentence, then the critical filter parameter and read-only note. It front-loads the important fuzzy behavior and avoids filler, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core search behavior and the `kinds` filter, but it does not explain what `app_id` means, what `db_path` is used for, how `max_results` is applied, or what shape of results to expect. With no output schema and no additional parameter documentation, agents may struggle to correctly populate the required and useful arguments.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the `kinds` parameter and implies that `query` is the symbol search term. It leaves `app_id`, `db_path`, and `max_results` unexplained, and with 0% schema description coverage this is a real gap, especially for a required parameter like `app_id`.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool performs fuzzy symbol search over the code graph, with a specific ranked matching strategy. This distinguishes it from sibling tools like code_graph_walk, code_graph_explain, or knowledge_search by tying the purpose to searchable symbols in the graph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It indicates what the tool does but does not tell an agent when to choose it over related search tools or graph tools. There are no references to alternatives such as code_graph_suggest, code_graph_explain, or grove/knowledge search tools, leaving usage selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that expired entries are skipped and purged, which is a destructive side effect. However, the annotations declare destructiveHint=false, creating a direct contradiction. The purge behavior is exactly the kind of behavioral detail that should either match the annotation or update it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the purpose first, then gives the key omission, pagination contract, and expiry behavior in exactly the order an agent needs. Every sentence earns its place with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides the return shape ({contexts, next_cursor}) and pagination semantics despite no output schema, which is strong. However, it leaves the required app_id parameter unexplained and does not describe what an individual context entry looks like, preventing a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains cursor behavior through the pagination contract and implies limit usage, but it never explains the required app_id parameter or how it scopes the saved context keys. That is a significant gap for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists saved context keys with save/expiry times, explicitly notes values are omitted, and points to context_get for values. This distinguishes it cleanly from sibling context tools while naming the exact resource and operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit pagination instructions ('pass the returned next_cursor as cursor') and tells the agent when to use context_get instead. It doesn't explicitly state when not to use this tool versus other context-related siblings, but the core routing guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description carries less burden. It adds meaningful context by framing flags as durable traces and ordering them most-recent-first. But it doesn't disclose behavior like limit handling, whether only flags from a certain timeframe are returned, or what a flag object contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler. The verb, resource, ordering, and purpose are all packed efficiently around the em dash. Every phrase contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The simple parameter set and annotations lower the bar, but the 0% schema description coverage and absent output schema mean the description is the only place to explain the required `app_id` and the response shape. It does neither of those, leaving an uncertain agent to guess what a flag record is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameters. The description mentions 'recent' facts are but doesn't explain `app_id` or `limit` at all, despite `app_id` being required. An agent must rely entirely on the schema's bare names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'List', a resource ('recent friction flags'), and an explicit ordering constraint ('most recent first'). It also clarifies the record's source and relationship to `friction_scan`, which differentiates it from the sibling tool that runs the actual scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is the durable output viewer for `friction_scan`, so an agent can intuit when to use it after a scan. However, it gives no exclusions or alternative candidates, such as 'use friction_scan when you need a fresh scan instead of viewing past flags.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly documents that missing keys return {error: not_found} and indicates side-effect-free access with 'Read-only;' – behavior that's aligned with annotations and covers the key error case. The description doesn't cover what happens on success beyond returning it, but for a read-only fetch this is sufficient. One of the better aspects of the documentation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences tightly pack purpose, error semantics, and side-effect behavior without excess. The inscription 'hard-link' and 'shared document store' adds some color, but may be overly compressed, making it slightly opaque for a new reader.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only accessor without output schema, it covers the key scenarios: the index (exact ID), the miss case ({error: not_found}), and the absence of side effects. Misses the response shape, but that's acceptable for a read-only read of a simple interface, and the description handles all core aspects adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description bears full responsibility for explaining the parameters, but it completely fails to distinguish app_id from atom_id, nor does it explain which is the 'exact' ID. The phrase 'by its exact ID' is singular, but there are two required parameters, leaving the reader to guess that atom_id is the identifier and app_id is a namespace (or similar distinction), which is the primary weakness of this documentation. The description adds essentially no value over the parameter names themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+object: 'Fetches a knowledge-base entry by its exact ID from the shared document store' – a direct accessor that is clearly distinct from the fuzzy search alternative. However, the exact composition of the key (app_id vs atom_id) is ambiguous, and the phrase 'hard-link to knowledge_base' is cryptic, making the core purpose slightly fuzzy around the edges.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
'By its exact ID' implies a when-to-use scenario (you know the ID, use this), and the mention of a 'hard-link to knowledge_base' gestures at an alternative, but it's not explicit. The description fails to truly contrast with knowledge_search and leaves the choice to inference, but doesn't leave it entirely to chance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful context: it requires the knowledge_read permission and returns a structured {flags, recommendation, evidence} result. This gives the agent useful behavioral expectations 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tight sentences with no filler: purpose, checks, return shape, and permission. It is front-loaded with the core function and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the return shape, permission requirement, and high-level behavior, which is good given the strong read-only annotations. However, with no output schema and zero parameter descriptions, the agent still lacks enough detail about how to set the parameters and interpret the evidence and recommendation fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for its three parameters, and the description does not explain what app_id, limit, or domain control or how they affect the health check. The parameter names and defaults offer some self-evident hints, but the description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states this is a health check on knowledge records and names the specific checks performed: unsourced records, missing domains, and duplicate content. It is distinct enough from siblings like knowledge_search and knowledge_ingest, though it does not explicitly differentiate itself from knowledge_verify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'health check' and lists the checks performed, so an agent can infer when to call it. However, it does not explicitly state when to prefer this over alternatives like knowledge_verify or knowledge_search, and the 'mem_check analog' reference is only useful if the agent already knows mem_check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all-false stubs (readOnlyHint: false, destructiveHint: false), so the description carries full burden and delivers: it discloses a real side effect ('successful write is logged to that subject's disclosure chain'), a hard authorization requirement (verified kb_promotion consent grant), and a non-obvious behavior (subject_id is never written, only checked). The pointer to the design doc is a bonus. No contradictions with annotations; this is a genuine value-add.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The opening sentence is tight and front-loaded, and the param-signposting ('`subject_id` (guardian-consent seam):') is a good structural pattern. The second paragraph, however, is a dense wall of parenthetical-heavy prose that could be broken up or trimmed, and the doc path in the middle interrupts the flow. Efficient, but not maximally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write tool with no output schema, no annotations, and no schema descriptions, the description covers the hardest conceptual piece (the consent seam) admirably and tells an agent the key side effect. But it leaves 5 of 6 parameters undefined, never clarifies the difference from near-sibling kb_ingest, and says nothing about the return value or duplicate behavior. Meaningful, but only partial coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 6 parameters, so the description must compensate. It does a stellar job on subject_id — explaining semantics, side effects, when to set it, when to leave it empty, and pointing to docs. But that is 1 of 6 parameters: app_id, content, source, domain, and tags remain completely unexplained, which is a real hole for an agent with zero schema help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource: 'Add a knowledge atom to the Postgres knowledge base' — precise and unambiguous, followed by a useful behavioral qualifier about duplicate checking. However, it does not differentiate from the sibling tool `kb_ingest`, which appears to occupy nearly the same semantic space; an agent has no way to distinguish the two from the text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes implicit guidance — 'Check for duplicates first' signals a precondition, and the consent-grant requirement tells when a non-owner subject is allowed. But there is no explicit when-to-use vs when-not-to-use statement and no mention of alternatives like kb_ingest, store_put, or commitment_ingest. The guidance is useful but the reader must infer the usage boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond the annotations: flags are produced from classifier misses above a configurable threshold, and the delta is never auto-applied — a human ratifies it. This clarifies the workflow and reinforces the read-only, non-destructive nature of the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The action is front-loaded, and both the threshold mechanism and the human-ratification caveat earn their place by explaining what the tool does and why it is safe.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a one-parameter list tool with no output schema, so the description should explain what the returned flags look like and how app_id affects results. It does neither. The conceptual explanation is strong, but an agent still has open questions about how to actually invoke it correctly and interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter, app_id, with 0% schema description coverage, and the description does not mention app_id at all. An agent must infer its meaning and valid values purely from the parameter name, with no guidance on how it scopes the returned flags or how to obtain it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states "List open rule-delta flags" — a specific verb and resource. The "rule-delta" qualifier and the threshold explanation give it a distinct identity among the many list-style siblings, though it never explicitly names or differentiates itself from similar tools like friction_flags_list or nest_intake_queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful workflow context: these flags are proposed rule changes that a human must ratify, and the classifier never rewrites its own rules. This implicitly tells an agent when this tool is relevant for human review. However, it gives no exclusions, no alternative tool routing, and no guidance for choosing it over the many sibling list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint: false), the description explicitly states that the file remains in place, the item is removed from the pending queue, and the decision is logged as feedback. These side effects are not in the schema or annotations, providing valuable behavioral context. It does not mention reversibility or permissions, but that is minor given the non-destructive guarantee.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the primary action and packs the key behavioral details efficiently. Every clause adds information; there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers the core behavior well. However, the missing parameter semantics and lack of mention of prerequisites (e.g., whether the item must already be staged) leave minor gaps. The annotations cover the safety profile, so the overall completeness is adequate but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has two required parameters (app_id, item_id) with no descriptions, and the schema description coverage is 0%. The description mentions 'staged item' but does not clarify which identifier refers to what, nor the relationship between them. The description fails to compensate for the lack of parameter metadata, leaving the agent to guess the semantics of app_id and item_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Skip a staged item') and its effects (leave file in place, remove from pending queue, log as feedback). It is specific enough to distinguish from siblings like nest_promote or nest_intake_file, though it doesn't explicitly name an alternative. The purpose is unambiguous and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to defer an item without deleting or moving it) but does not explicitly contrast it with alternatives like nest_intake_file or nest_intake_flags. There is no clear 'use when' or 'use instead of' guidance, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: 'Non-blocking' and 'Requires grove_read.' These are meaningful traits not captured by the annotations. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. The main behavior is stated first, followed by non-blocking and dependency notes, then a terse Args section. Every sentence earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only watch tool, the description covers purpose, non-blocking behavior, a dependency, and two of three parameters. Output schema and annotations cover return values and safety. The missing app_id explanation and lack of sibling differentiation are the main gaps, but overall it is mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains channel_name ('Channel to check') and since_id ('Return messages with id greater than this value'), adding real semantics. However, app_id is present in the schema but completely unexplained, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Return any new messages in a channel since since_id.' This is specific and actionable. However, it does not differentiate from sibling tools like grove_watch_all or grove_get_history, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The only usage guidance is 'Requires grove_read,' which is a prerequisite rather than guidance on when to use this tool versus alternatives. It does not mention grove_watch_all, grove_get_history, or any exclusion criteria, so the agent is left to infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the read-only safety profile (readOnlyHint=true, destructiveHint=false), so the description nicely layers on the pagination envelope ({items, next_cursor}) and the supersedes-edge retirement mechanic behind current_only — behavior not visible from any structured field. It stops short of stating ordering guarantees or pagination maximums, hence a 4 rather than a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with clear structure: what's listed, the return envelope, and the boolean flag behavior. The "willow...recorded story" metaphor is the only ornamentation and it's brief; otherwise every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter, no-output-schema list tool this covers the essentials: purpose, field list, return shape, pagination, and the key filter. But the undocumented required app_id and limit bounds are real holes, and since no output schema exists, mentioning ordering or error semantics would have meaningfully improved completeness. Adequate, with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must fully carry parameter documentation, but it only addresses current_only (and implies cursor usage via next_cursor). The required app_id parameter is never explained, and limit has no bounds or semantics noted — a significant gap given no fallback help exists in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
"List recorded lineage atoms (id, title, whether current, tags)" is a specific verb+resource statement with an inline field list, immediately telling an agent what result to expect. The "index of what parts of this willow have a recorded story" provides a shorthand mental model, though the product-name metaphor is slightly cryptic and the description never names a sibling for contrast, keeping it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when the tool is appropriate: it's "the index" for enumerating recorded lineage atoms, with an explicit pagination contract and a documented boolean switch ("Pass current_only=True to hide atoms that a later supersedes edge has retired"). It gives clear context for common call patterns but doesn't state exclusions or mention alternatives like lineage_why/lineage_link, so it misses the explicit when-not-to-use guidance needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint: true and destructiveHint: false, and the description's verb 'List' reinforces that it is a read-only operation. The description adds transparency by detailing what the queue contains (files, predicted track) without implying any side effects. It does not mention potential costs or limitations, but the read-only nature is well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that communicates the key aspects: the action (list), the subject (pending review queue), the source (files staged by nest_intake_scan), the state (awaiting decision), and an extra detail (predicted track). There is no redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a good overview of what the tool does but leaves out important context. It does not describe the output format, pagination, ordering, or how to interpret the 'track' field. The unexplained 'app_id' parameter further reduces completeness. However, the core purpose is covered, so it is above a minimal score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines a required 'app_id' parameter, but the description gives no explanation of its purpose or expected format. With 0% schema description coverage, the description should compensate, but it does not even mention the parameter. An agent would be left guessing what app_id refers to, which is critical for a required parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists the pending review queue, and it specifies the content: files staged by nest_intake_scan awaiting a confirm/override/skip decision. It also mentions the predicted track, which adds specificity. This distinguishes it from sibling tools like nest_intake_scan or nest_intake_file, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives, but its purpose is clear enough for an agent to infer it is for retrieving the queue. There is no mention of conditions or contexts where it should be preferred, such as 'use this when you need to see pending items'. This leaves some ambiguity in usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description reveals critical behaviors: it only flags (never blocks), it persists and dedupes flags, it is model-free and deterministic (no LLM, no egress), and it must be driven externally. These details significantly inform the caller about side effects and operational constraints, going well beyond the annotation hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is notably verbose and repetitive. It restates the same idea in multiple ways (e.g., 'agent has stopped being *other*' and 'naming where the agent stopped disagreeing'), and includes extensive meta-commentary about model-free operation, non-blocking behavior, and external invocation. While the main purpose is front-loaded in the first sentence, the overall length and redundancy detract from clarity and maintainability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives substantial context about the tool's domain and side effects (flagging, persistence, deduping), but it omits critical details: it does not define the output/return value (e.g., success flag, list of flags created), does not specify error conditions, and leaves parameter semantics incomplete (especially app_id and the precise meaning of floor/window). Without these, the tool is not fully self-contained for an agent to use reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description partially explains parameters: 'turns' is explicitly defined as a list of role/text/timestamp objects, and 'floor' and 'window' are referenced as 'friction floor' and 'window of agent turns'. However, the meaning of the numeric 'floor' threshold and the exact role of 'window' in the scan are not precisely clarified, and the required 'app_id' parameter is entirely unexplained. Schema coverage is 0%, so the description adds some value but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: scanning a transcript window for the 'mirror failure mode' where an agent reflects the user while the user escalates. It also specifies key constraints (deterministic, no LLM, non-blocking) and distinguishes itself from a listing tool like friction_flags_list by focusing on detection rather than enumeration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit usage context: it is a deterministic checker that flags issues without blocking, and it must be invoked from outside the watched model (harness/monitor). However, it does not explicitly state when to prefer this tool over alternatives (e.g., when to use friction_scan vs. friction_flags_list), nor does it outline clear conditions for invocation beyond the general scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds that it requires grove_write and that a different identity requires grove_relay, which are useful beyond annotations. However, it doesn't explain what happens on broadcast (e.g., who sees it, any side effects beyond the broadcast itself). With annotations providing some base, a 3 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose and prerequisite are in the first line, followed by a clear Args list. Every sentence adds value with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two optional parameters and no output schema, so the description is largely sufficient for calling it. However, the app_id parameter is undocumented, which is a notable gap given the zero schema coverage. An agent may not know what to pass for app_id, reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the schema provides no descriptions for parameters. The description only explains the 'sender' parameter (defaults to grove_sender, different identity requires grove_relay). The 'app_id' parameter is entirely unexplained, leaving a gap. This is a significant deficiency given the zero coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool broadcasts a heartbeat, a specific verb and resource. While it doesn't explicitly name a sibling alternative, the purpose is clear enough to distinguish from other grove tools like grove_send_message or grove_ack.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to signal liveness) and mentions a prerequisite (requires grove_write) and a special case (different identity requires grove_relay). It doesn't explicitly say when not to use it, but the context is sufficient for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description correctly aligns with a safe read operation. The description adds useful behavior: the priority ordering (priority-first, then newest) and the default filtering (open_only=true). It also notes a permission requirement (grove_read), which is valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, with a clear first line stating the queue's nature, followed by ordering and usage guidance. The bullet-style parameter notes are succinct and avoid redundancy. It loses a point for not being perfectly front-loaded—the permission requirement is tucked in the first paragraph but could be more prominent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list operation with two relevant params), the description covers ordering, filtering, and the permission context. The output schema is present, so return values are handled. The missing app_id documentation is a minor completeness gap, but overall the tool is adequately described for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters (limit, app_id, open_only) with 0% schema description coverage, meaning the schema provides no titles or descriptions beyond names. The description explains limit and open_only, but app_id is completely undocumented in both schema and description, which is a significant gap. The description adds meaning for two params but misses one.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: polling a queue of work awaiting human action (consent, attestation, review, onboarding). It differentiates from siblings like grove_inbox and grove_flagged by focusing on human-required items that gate fleet progress, though it doesn't explicitly name a sibling as an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use: 'Poll this to see what needs the operator before the fleet can proceed.' It implies a routine check, but doesn't explicitly say when NOT to use it or mention alternatives like human_required_list. However, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: false) are minimal, so the description carries the transparency burden — and it delivers: auto-creation side effect, the sender default oddity (never a literal "Auto"), the grove_relay permission requirement, and the sender_forbidden error. This meaningfully extends beyond the structured annotation fields 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose and side effect, followed by an efficient Args block. At ~90 words it is efficient with no redundancy, and the per-parameter docs are terse but complete. It earns the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description omits what the call returns (Ack? Message object?) and leaves app_id undocumented. The identity/permission contract is admirably complete, but the missing parameter and no return contract keep it from being fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate — and it covers 3 of 4 parameters with real behavioral detail (defaults, permission fallbacks). Unfortunately, app_id is entirely undocumented, leaving a gap for the agent on that parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Send'), resource ('a message to a Grove channel'), and a unique side effect ('Creates the channel if it doesn't exist'). The purpose is immediately clear and distinguishable from the many sibling tools, though no specific sibling is named to sharpen the contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides the permission prerequisite ('Requires grove_write') and default behaviors, which tells the agent when it is permitted to use the tool. However, it does not say when NOT to use it or point to alternatives like grove_reply or grove_bus_send for different intents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds contextual behavior: it suppresses person names, date timeline, and source filenames (explaining why: they are content, not structure), and it notes the full digest is local-CLI only. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then explains what is suppressed and why, and ends with the scope limitation. It is concise, with no filler, and every sentence earns its place. It could be slightly tighter but is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output content well (category breakdown, clusters, secret kinds, file-reading method) but omits any explanation of the input parameters (app_id, db_path) and does not state preconditions (e.g., must have a seeded Nest DB). Since there is no output schema, the description also doesn't specify the exact structure of the Markdown. These gaps make it incomplete for a tool with 0% schema parameter coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description bears the full burden of explaining parameters. It never mentions app_id or db_path, what they mean, or how they are used. An agent would have to infer that 'app_id' identifies a Nest DB, but no explicit semantics are provided. This is a critical gap for a tool with two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('map'), resource ('seeded Nest DB'), and output format ('one-page Markdown'), and scopes it to 'the WALLED view'. It also contrasts with the 'full unwalled digest' which is explicitly a local-CLI affordance, so an agent can distinguish this tool from any potential alternative that might return the full dataset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that this is the MCP-accessible digest (the full unwalled digest is never returned over MCP), effectively excluding that alternative. However, it does not explicitly name sibling tools like nest_scan or nest_status or state conditions for when to pick this over them, so it stops short of explicit 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states this is a write/close operation ('Close a human-entry session'), which aligns with readOnlyHint=false. It explains the difference from handoff_write_v4 (which needs a dispatch_id). However, no annotations cover side effects or state changes; the description doesn't mention what happens on close, whether it's idempotent, or what the response contains. Since this is a session-writing tool with three required params, the description adds moderate behavioral value on top of the sparse annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured paragraph, front-loading the purpose and then enumerating the key fields. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, field semantics, and comparison to a sibling, which is remarkably complete given zero schema descriptions and no output schema. What remains unclear is where 'project' and 'workspace' originate (does the system infer them from the session, or must the caller provide them?), and whether 'findings' has a specific expected shape (array of what?). These are contextual gaps, but the tool is still quite usable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must be the sole source of parameter meaning. It does name `narrative`, `summary`, `findings`, and `next_bite` with inline descriptions, and clarifies `app_id`, `session_id`, and `project` via prose. However, it doesn't cover `workspace` or `narrative` format beyond
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: closing a human-entry session and producing a markdown closeout with narrative, summary, findings, and next_bite. It also clarifies the distinction from the sibling handoff_write_v4, which requires a dispatch_id. This is strong but not perfect — it doesn't explicitly say what a 'human-entry session' is or when to use it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the context of use (human-entry sessions vs. dispatched work) and the required inputs (project-scoped markdown closeout, needs only the session). However, it doesn't specify when this tool should be called in a workflow, what prerequisites exist (e.g., must a session be open?), or what distinguishes an appropriate use from an inappropriate one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states that the session is DROPPED after this call and per-call nonce sets are freed, yet the annotations specify destructiveHint=false. This directly contradicts the annotation, so the behavioral transparency score must be 1 despite the otherwise rich detail about ReceiptLog and classification behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but organized: purpose, exit_declaration structure, reconciliation logic, side effects, prerequisites, and handoff relationship. It is front-loaded with the core action. The reference to 'willow-gate seam Phase 4 / H3' adds minor noise but does not undermine usability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with no output schema, the description covers requirements, the exit_declaration shape, reconciliation behaviors, error on missing session, and the post-condition that the session is dropped. It does not fully spell out the successful response shape, but it provides enough context for an agent to invoke and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the load. It explains the exit_declaration object well: 'tools' as willow-gate classes, plus self-scored pass_count/fail_count/drift/state_hash, and what the server diff does with it. It also links app_id and session_id to the bound-session prerequisite. Some precise formatting details are missing but the compensation is strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Close a bound session and reconcile what you DECLARE you did against what the receipt log shows you actually did.' It clearly identifies the tool's role and differentiates it from siblings like session_bind, session_handoff_write, verify_call, and receipts_tail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives prerequisite context: a live session bound to app_id is required, and it tells the agent to call session_bind first. It also explicitly says that handoff tools should still be run alongside this one because the tool 'never blocks a handoff.' This is strong usage guidance, though it does not explicitly name an alternative tool for situations where this tool should be skipped.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint=false, which matches the mutating `attach` action Mendescribes. The description adds the not_found error behavior and return shape, which is useful. However, it does not disclose any side effects beyond updating the routing row (e.g., whether it overwrites prior results, effects on downstream processes), so behavior is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the action, the parameters tied to their purpose, the return payload, and the error case. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple shape scrap (4 params, no nested objects), the description covers the outcome attachment semanticallycourt, the return value (including the not_found error), and names the companion agent_route tool as the relationship. It omits only the role of `app_id`, which is reasonably inferable as a namespace/filter, and there is no output schema to carry return-type details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverageaving no property descriptions. The description clarifies `routing_id` (identifies the row), `result` (outcome text), and `status` (e.g. 'done'/'failed'), but `app_id` is left undefined. It adds value but not fully compensating for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('attach the outcome...result text plus status') targeting a specific resource (the routing_decisions row identified by routing_id). It clearly connects to its upstream agent_route tool and is distinct from siblings like dispatch_send or agent_clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use the tool ('close the loop on an agent_route call') which gives clear context, but does not mention when not to use it or contrast with any alternative (e.g., dispatch_* or store_update). No exclusions or conditional guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces the read-only nature. It adds valuable behavioral context beyond annotations: the ranking is based on 'keyword overlap with symbol names + file paths' and explicitly excludes embeddings and LLM, informing the agent about the lexical, non-semantic nature of the tool. This context helps the agent set appropriate expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, remarkably concise with no fluff. It front-loads the core purpose, then adds the method and a critical differentiator. Every sentence earns its place, and the structure makes it easy to scan and extract the key purpose and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema, so the description should at least hint at return value characteristics, which it does not. While it clarifies the core purpose and read-only nature, it omits parameter explanations (especially app_id and db_path) and doesn't mention output format or behavior details like pagination or error handling. Given the tool's relative simplicity, some aspects are adequately covered, but the parameter ambiguity and lack of output information leave gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It only vaguely references 'task description,' which maps to the 'task' parameter, but it provides no explanation for 'app_id', 'db_path', or 'max_results'. The description fails to clarify these parameters, leaving the agent to guess their purpose, especially since the schema offers no hints. This is a significant gap given the zero coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool suggests files most relevant to a task description, with a specific ranking mechanism (keyword overlap with symbol names and file paths). It also distinguishes itself by explicitly noting 'No embeddings, no LLM', which sets it apart from sibling tools like code_graph_search or code_graph_explain. The verb+resource structure is precise and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by highlighting that it avoids embeddings and LLMs, suggesting a fast keyword-based approach. However, it does not explicitly name alternative tools or state when to use this versus others among the many code_graph siblings. There is no direct 'when-to-use' or 'when-not-to-use' guidance, only an implied niche.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a surprising side effect: it purges expired entries when returning an expired error. This goes beyond the annotations, which only say readOnlyHint=false and destructiveHint=false. It also specifies the exact error shapes, making behavior predictable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the primary purpose is in the first sentence, and the error behaviors follow in a single second line. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter tool with no output schema, it covers the core action and error cases. However, it omits any explanation of what app_id is for and doesn't mention any constraints (e.g., key uniqueness, TTL semantics beyond the expired purge). Given the spare schema, more detail would help an agent use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description provides no extra meaning for 'key' or 'app_id'. It doesn't clarify the relationship between the two or the expected formats. The description alone does not compensate for the missing schema descriptions, leaving the agent to guess at the parameter roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('a saved context by key'), and the error behaviors make the purpose unambiguous. It distinguishes itself from siblings like context_save, context_list, and context_expire by focusing on retrieval of a single keyed value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for reading a specific context, but it does not explicitly contrast with context_list (list all) or context_expire (force expiry). No alternatives are named or excluded, so the agent must infer when to choose this over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this read-only and non-destructive; the description adds useful behavior beyond those: requires grove_read, dedupes by id, applies a merge cap after dedupe, and orders newest-first. That is genuine added context about permission and processing behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence defines the inbox, one line gives the permission, and an args block clarifies parameters. Every sentence earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return values need no explanation. The description covers message scope, authorization, defaults, dedupe behavior, and pagination cursor. The main shortfall is app_id and the lack of an explicit sibling alternative, but overall an agent can invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must shoulder the burden. It explains agent, since_id, and limit well, including defaults and polling semantics. However, app_id is completely undocumented in both the schema and description, leaving a real parameter gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource: an agent's fleet inbox containing @mentions, direct bus messages, and the agent's dedicated channel. It is not a tautology, but it does not explicitly contrast itself with sibling tools like grove_bus_receive or grove_get_history, so it falls just short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The message-source list and cursor parameter imply polling usage, and 'Requires grove_read' gives a prerequisite. However, it never states when to prefer this over alternatives or when not to use it, so the agent has to infer routing from the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds 'Requires grove_read,' which conveys a permission requirement. It does not describe side effects or output format, but the annotation already covers safety, so the added requirement is meaningful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured, consisting of two short sentences with no redundant information. It communicates the essential purpose and a requirement efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the purpose is clear, the description omits details about the parameter and potential output structure or pagination. It does not fully equip the agent to invoke the tool correctly without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, app_id, has no description in the schema or the tool description. The description does not clarify whether it is required, what it represents, or how it affects the listing. This leaves ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List), the resource (all active Grove channels), and the fields returned (name, type, description). It is sufficiently specific to distinguish from other list tools like store_list or store_search_all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear purpose but does not explicitly mention when to use this tool over alternatives, nor does it describe any filtering or use-case constraints. It implies a simple listing operation but lacks explicit 'when-not' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds value by stating the read behavior returns credential source (env/vault) but never the credential value, which is an important safety disclosure. Also clarifies stub-specific content, enriching what the annotation alone does not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence that front-loads the core action ('List every integration adapter') and packs the essential output characteristics and safety qualifier without filler. Every clause earns its place; nothing can be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers what information is returned and the credential-source safety caveat, which is good. But the app_id parameter is unexplained despite being required, and there is no guidance on the expected scope or any edge cases such as empty results or how stubs are marked. The overall picture is incomplete for a tool that needs a required input.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is no description of the sole parameter app_id in the input schema and no mention of it in the tool description. Schema description coverage is 0%, so the description must compensate, but it remains silent on what app_id means, how it filters the listing, or where an agent would retrieve a valid value. The param name alone provides minimal hinting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') and resource ('integration adapter'), with precise scope: live adapters and declared stubs. It also lists the returned dimensions (status, credential source, missing items and implementation criteria), which clearly distinguishes it from siblings like integration_status or integration_call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is plainly implied: this is the overview tool for all integration adapters. However, it does not explicitly explain when to use this versus sibling alternatives like integration_status, integration_call, or federation_list_servers. No exclusions or when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, covering the safety profile. The description adds non-obvious behavior beyond annotations: deduplication by phrasing, chronological ordering (newest first), and the emptiness condition ('Empty when every routed intent has a sealed home'). This is exactly the kind of behavioral context an agent needs and can't infer from annotations alone. Minor deduction for not covering unsubscribe/auth behavior, which is contextually light for a read of app-scoped data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences achieve maximum information density: the first labels and scopes the resource, the second details ordering and deduplication, the third explains the empty state. Every clause carries meaning. The only friction is the density of the 'teach-queue'/'sealed home'/'oracle learns' metaphor, which is charming but slightly cryptic for the first-time reader—a tradeoff worth noting, though the subsequent prose rewards the effort.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, annotation-covered queue listing, the description thoroughly grounds the agent in what this tool is for and where it sits in the 'teach-queue' workflow. With no output schema present, the primary omission is any hint of what each item looks like (an object with an 'id'? a 'statement'?) or what 'seal' and 'reject' mean observably—two actions the description explicitly tasks the agent with enabling. The tradeoff: the state model is now so clear that matter feels minor. The description does everything except itemize the queue entries and their lifecycle outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at a critical 0%, the description bears full responsibility for parameter semantics, yet it says nothing directly about limit or app_id. It implies limit-style pagination via 'newest first' ordering and hints at app scoping through 'seal... home', but never bridges these to the actual parameters. An agent can infer from the 'limit' name + default that it bounds result size, but 'app_id' gets no semantic grounding—its role as a scoping key for the pending queue is entirely unexplained. For a tool whose description excels elsewhere, this is a clear semantic gap in the parameter contract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a concrete resource ('teach-queue: natural-language intents nestor_tole_route couldn't serve') with specific semantics: what the queue holds, its ordering (newest first), dedup behavior (by phrasing), and empty-state condition. It clearly differentiates from siblings nestor_tool_route and nestor_tool_seal by framing this as the intermediate review state in the workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it — 'intents nestor_tool_route couldn't serve... what a human should seal (or reject)' establishes the trigger condition of the routing workflow. However, this is implied through narrative rather than an explicit directive; there's no direct comparison to alternatives or stated conditions for when not to use it. The exclusion of siblings is ideally direct, not assumed from naming convention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context beyond that: it explicitly says 'Structure only; no content,' disclosing that content is not returned, which is a meaningful behavioral trait not available from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The main action and scope are front-loaded, and the clarifying 'Structure only; no content' is placed after the core purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema, read-only annotations), and the description covers the return content and structural nature. However, since schema coverage is 0%, the description should at least hint at what app_id and db_path refer to. Its silence on parameters leaves a meaningful gap for an agent deciding how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. However, the description does not explain 'app_id' or 'db_path' at all. It only indirectly hints at a database context via 'Nest DB,' but the actual meaning of the parameters is left to the schema field names, which are ambiguous without elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Counts') and resource ('seeded Nest DB'), and enumerates the exact dimensions counted (sources by status, fragments by type, topical categories by size). It also clarifies 'Structure only; no content,' which distinguishes it from content-retrieval siblings like nest_scan or nest_digest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when count summaries are needed and when the DB is 'seeded,' but it does not explicitly reference sibling tools or state when NOT to use it. No exclusions or alternative routing guidance is provided, leaving some inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds meaningful behavioral context beyond annotations by stating the response structure (status, count, commitments, next_cursor) and that only facts are returned, never the event body. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary purpose, and each sentence adds value — the field restriction, pagination mechanics, read-only nature, and state filter are all stated without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with no output schema, the description covers the essential operational details: response format, pagination, and state filtering. It does not address error handling or what happens with invalid state values, but these are minor given the explicit read-only nature and simple parameter semantics. Overall adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden for parameter meaning. It explains 'state' (filters to ACTIVE/WITHDRAWN) and 'cursor' (pass next_cursor from response), but does not explain 'app_id' (required) or 'limit' (default 50). The partial coverage is insufficient for a tool with zero schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists commitments, specifies the exact fields returned (uid/title/when/who/state/acknowledged/history length), and explicitly excludes the event body. This distinguishes it from sibling tools like commitment_ingest and commitment_acknowledge without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit pagination instructions (next_cursor as cursor) and explains the state filter behavior (ACTIVE/WITHDRAWN, case-insensitive, omit for all). However, it does not mention when to prefer this over related commitment tools (e.g., commitment_surface) or any conditions that would make it inappropriate, so usage guidance is partial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only safety, and the description adds genuine value beyond them: the exact return shape {format, path, exists, config}, the semantic meaning of exists=false (built-in defaults apply), and the referenced scoping (AS-8). This is exactly the kind of contextual detail agents need.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences earn their place: behavior, return contract, and safety. Only the cryptic '(AS-8)' reference feels like unneeded noise that could be explained or dropped.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read tool, the return contract and edge-case semantics (missing file) are well covered without an output schema. The missing explanation of the app_id parameter prevents a higher score — it's the one thing an agent would need to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description never explains what app_id is or how it maps to the config file mentioned. The description mentions 'each seed destination' but doesn't tie this back to app_id, forcing the agent to guess the parameter's role — a real gap for a required argument.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb-resource pair, "Read the standing exposure defaults" from the config file, and explains its role relative to the sibling exposure_slice. Any agent can distinguish this from the broader sibling list without opening another schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly implies when this applies — querying defaults that govern exposure_slice calls without an explicit preset. However, no explicit alternatives or when-not-to-use guidance is given, leaving routing decisions to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and non-destructive. The description adds behavioral context beyond annotations by explaining that workers reports every heartbeat-publishing process and that stranded is true only when pending work exists without a live runner. This clarifies the semantics of the reported data without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the core purpose, and each sentence adds meaningful value. The concept of stranded tasks is explained once, concisely, without redundancy. It is well-structured and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately communicates what the tool returns conceptually: queue counts, worker heartbeats, and a stranded flag. It covers the essential semantics an agent needs to interpret results, though it does not specify exact response fields or error conditions. For a simple one-parameter health check, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the single parameter app_id, and the tool description does not mention app_id at all. While the parameter name is self-explanatory (an application identifier), the description fails to compensate for the schema's lack of detail, leaving the agent to infer the expected value format and scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: reporting task queue counts by status and live worker heartbeats. It uses specific terminology (pending, stranded, workers) and explains the key distinction between queued and stranded tasks, which sets it apart from sibling tools like fleet_status or integration_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does 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 need to understand queue depth in the context of worker liveness and detect stranded tasks—but it does not explicitly name alternatives or provide when-not-to-use guidance. The context is clear enough for an informed agent, but it lacks explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and destructiveHint=false, providing minimal behavioral detail. The description adds meaningful behavior: it 'Snapshots selected environment variables so env_check can later spot drift', discloses that the fork is 'recorded in the SOIL store' (persistence), and explains fork_id auto-generation. This goes beyond the annotations and helps the agent understand side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, three sentences, with the main purpose in the first sentence. It efficiently covers the core concept, a behavioral side effect, ID handling, and lifecycle pointers. No redundant filler; it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5-parameter schema, no output schema, and sparse annotations, the description covers the core concept, snapshot behavior, ID generation, and lifecycle. However, it leaves gaps for parameter meanings (app_id, topic, etc.) and does not mention what the tool returns. For a creation tool, the lifecycle context is helpful but the parameter semantics gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. Only fork_id is explained ('pins an explicit ID; omit it to auto-generate'). The other parameters (app_id, title, created_by, topic) receive no semantic explanation in the description, leaving the agent to guess their meanings from the schema titles alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Open a fork' and clarifies it as 'a named, bounded unit of work (feature branch + PR tracking)', which is a specific verb and resource. It distinguishes itself from sibling tools like fork_log, fork_merge, and fork_delete by positioning itself as the creation step. The lifecycle pointers further reinforce that this tool creates forks, not logs, merges, or deletes them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly tells when to use this tool: to open/start a new fork. It explicitly routes to related tools for other stages: 'Log changes with fork_log; close with fork_merge or fork_delete.' It also references env_check for later drift detection, showing a usage context. However, it does not explicitly contrast with fork_join, which seems to be the counterpart for joining an existing fork.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the read-only and non-destructive annotations by declaring that grove_read is required and that the identity is resolved from the specialist registry. It also clarifies the output semantics, including the optionality of registered role/display name. This goes beyond what the annotations alone provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: the first sentence explains the core purpose, the second gives the required permission, and the third resolves potential confusion with the human-facing variant. Every sentence contributes useful information without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only identity retrieval tool, the description covers the scope, key output fields, permission requirement, and disambiguation from the canonical version. The main gap is the complete lack of documentation for the app_id input parameter, which prevents the context from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, app_id, has zero schema description coverage, and the tool description does not mention it at all. An agent cannot infer whether app_id selects a different identity, overrides a default, or is relevant only in specific cases. The description adds no meaning beyond the bare property name and default value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool resolves this agent's own Grove identity from the specialist registry and explicitly lists the expected outputs: app_id, grove_sender, and role/display name. It also distinguishes this agent-side tool from the human/dashboard variant, leaving no ambiguity about what is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage context: use this for agent-side Grove identity, as opposed to the human/dashboard version. It also states the prerequisite grove_read. It stops short of explicitly enumerating when not to use it or naming direct sibling alternatives, but the intended context is well implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations already marking the tool read-only, the description adds the permission requirement 'Requires grove_read' and details matching behavior: query is a 'case-insensitive substring match.' This is behavioral context not present in the schema or annotations. It does not disclose pagination or default channel scope, but the output schema and read-only annotation reduce the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the purpose and prerequisite are in the first sentence, and the parameter details follow in a clean list. Every sentence adds value, with no filler or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core behavior and two of three parameters, and the output schema plus read-only annotations handle return values and safety. It omits what app_id does and what the default search scope is when channel_name is not given, which are relevant for correct invocation. Given the tool's relative simplicity, the gap is moderate but not crippling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry parameter meaning. It explains query as a case-insensitive substring and channel_name as an optional restriction, which adds real semantics. However, app_id is left unexplained in both description and schema, leaving one of the three parameters ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Search Grove messages by content.' This clearly identifies what the tool does and distinguishes it from sibling tools like grove_get_history or grove_list_channels, which cover different retrieval modes. The prerequisite 'Requires grove_read' adds context without obscuring the core purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implicit: use when searching messages by content. The description names no alternatives or exclusion conditions, and the only condition provided is the prerequisite 'Requires grove_read,' which is a permission dependency rather than a comparison with sibling tools. An agent must infer when to choose this over grove_get_history or knowledge_search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Read-only' is redundant. However, it adds non-obvious behavioral details: the tool returns {error: not_party_to_dispatch} when app_id is not a party to the dispatch, and it ties this to a specific issue/ticket (B-54, #242) and to the same check in dispatch_read. It also clarifies the tool reads two distinct artifacts. This is meaningful disclosure 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then usage, then an error condition. It is three sentences with minimal fluff. The inclusion of the issue reference 'B-54, issue #242' is somewhat noisy but provides traceability. Overall it is efficient and avoids redundancy, though it could be tightened by dropping the redundant 'Read-only' given the annotation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with two parameters and no output schema, the description covers the main purpose, usage context, and a key error case. However, it leaves out essential details: it does not describe the structure of the return value (beyond the error), does not explain dispatch_id at all, and does not mention any pagination or content format of handoff.json. The annotations cover safety, but the agent still lacks enough to fully anticipate the tool's behavior without external context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameters. It provides only a partial hint about app_id—its role in the party check as 'from_app, to_app, reply_to, or orchestrator'—but never defines what either parameter means, their expected formats, or how dispatch_id is used. An agent cannot infer from the description alone what values to supply for dispatch_id or how app_id should be structured, which is a significant gap given zero schema help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: 'Read the closeout of a completed dispatch: the structured handoff.json findings plus the closeout.md narrative.' It names the exact artifacts read, and immediately distinguishes its role from siblings by noting it is what the orchestrator reads before verify_handoff and what a successor agent reads. It also contrasts with dispatch_read via the shared party-check reference, so the agent can tell them apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states two usage scenarios: 'What the orchestrator reads before verify_handoff, and what a successor agent reads to pick up the thread.' This gives clear context for when to invoke it. It does not explicitly list exclusions or when not to use it, but the phrase 'same packet-party check as dispatch_read' hints at a sibling that behaves similarly, implying a selection criterion. The lack of an explicit 'use X instead when...' is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that the tool pauses automation and records the calling app as source_agent. These are behavioral side effects that are not evident from the schema or annotations, adding useful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences with inline enum lists for kind and priority. It is well-structured, with no redundant information, and directly conveys the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not mention the return value or post-conditions, and since there is no output schema, agents have no information about expected responses. It also omits details about side effects beyond recording source_agent and pausing automation, leaving some contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'kind' and 'priority' parameters with allowed values, but leaves 'title', 'summary', 'assignee', and 'source_ref' undefined. Since the schema provides no descriptions for any parameters, this partial coverage helps but does not fully clarify the remaining fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: enqueue work that pauses automation until human action. It specifies the verb 'enqueue' and the resource (work requiring human intervention), and lists relevant kinds and priority levels, effectively distinguishing it from resolution or listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to create a human-required task) but provides no explicit differentiation from sibling tools like human_required_resolve or human_required_list. It does not state when to use this tool versus alternatives, leaving the agent to infer from the action verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that this is a promotion into the shared KB, the guardian-consent seam requiring a verified kb_promotion grant for non-owner subject data, that subject_id is opaque and never written, and that committed promotions are logged to the subject's disclosure chain. This adds substantial behavioral context beyond the sparse annotations, though the effect of the supersede parameter is not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into tight thematic chunks: purpose, prerequisite, slice selection, exclusions, and subject_id handling. Every sentence adds domain value, though the subject_id paragraph is dense and could be broken out more cleanly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Strong coverage of source requirements, slice options, forbidden content, and consent/grant behavior for a mutation tool with no output schema. But it omits semantics for tier, supersede, and sensitivity, and does not describe return/error behavior, leaving meaningful gaps for a 7-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates for slice (listing voice_only | work_context | full and the exposure.json default) and subject_id (guardian-consent semantics). However, tier, supersede, and sensitivity are left unexplained, and agent_id only appears inside a file path, leaving several parameters underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action—promote a ratified agent_seed slice into Postgres KB—and narrows the resource to agent_seed slices with explicit exclusions (persona.cast, context.personal_note). This clearly differentiates it from sibling ingestion/promotion tools like knowledge_ingest and kb_promote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit prerequisites (ratified + trusted seed at $WILLOW_HOME/seeds/{agent_id}.json), valid slice values, and a clear rule about what it never promotes. It does not explicitly name an alternative tool for excluded content, so the guidance is clear but not strongly comparative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by clarifying the non-destructive nature (hidden but still retrievable via kb_at), the required role, and the need for mapped tags. This is genuinely useful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two snappy sentences, front-loaded with the key concept. Slightly dense but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential semantics for a flat-parameter tool, but the return value is not described (e.g., confirms retraction or returns the tombstone). Minor gap only.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description flags reason as required and implies the role/tag requirement, but doesn't define what kind of reason is expected. Partial help for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('tombstone') and its effect: the atom is hidden from default search but remains fetchable by ID. This unambiguously distinguishes it from a hard delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to retract instead of delete or flag, nor when not to use it. The description explains the behavior but doesn't route the agent toward the right choice among sibling mutating tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so this is a write operation that is not destructive. The description adds that the operation is idempotent per (from, relation, to), which is useful behavioral context beyond the annotations. It does not describe error handling or side effects but is transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and includes examples and idempotency. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behavior and idempotency but does not mention return values, error cases, or the purpose of app_id and context. Given there is no output schema, some additional context about expected outcomes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the relation parameter with valid verbs and indicates the edge direction via from_id and to_id. However, app_id and context parameters are not described, leaving a gap for a tool with 5 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool adds a provenance edge without rewriting a node, and gives concrete examples like 'motivated_by' and 'derived_from'. It is a specific verb+resource and distinguishes itself from sibling tools that record or query lineage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use this tool (when you want to add an edge without rewriting the node) but does not explicitly name alternatives or state when not to use it. It implicitly differentiates from lineage_record by saying 'without (re)writing a node', but this is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds non-obvious behavioral context: it relies on a snapshot taken at fork_create and reports both changed and missing variables. The return behavior is stated, which is especially valuable since there is no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the core behavior, then gives the use context and expected return, and finishes with a clear safety note. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is mostly complete for a safe read-only diagnostic: it explains what it compares, when it is called for, and what results are returned. The missing parameter definitions and lack of any note about what happens if no snapshot exists or if the diff is empty leave moderate gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain app_id or fork_id beyond implicitly referencing the 'snapshot taken at fork_create'. The fork_id is contextually hinted, but app_id is entirely unexplained, so the agent has to guess which application or fork scope it refers to.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Diff') and names the exact resource ('current process environment against the snapshot taken at fork_create'). It also states the return content ('variables that changed or went missing'), making the tool's purpose immediately identifiable and distinct from generic audit or log tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context that this tool is meant to be used before merging a fork, to catch environment drift. It does not explicitly name alternatives or state when not to use it, but the 'before merging' guidance plus the fork-family siblings makes the invocation context clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating operation (readOnlyHint false) but not destructive (destructiveHint false). The description adds specific error behavior ('Errors if the fork is unknown or already closed'), which is not covered by annotations. It does not mention success return behavior, but given the annotation coverage, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the primary action, and no wasted words. The purpose, downstream link, and error conditions are packed efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and error conditions but leaves `app_id` unexplained and does not describe the success response or any side effects. Given the moderate complexity and the presence of annotations covering read-only and destructive hints, the description is not fully complete but meets a baseline. The missing app_id semantics and return behavior are notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description carries the full burden of explaining parameters. It explains `component` explicitly ('an agent, repo, or subsystem name') and implies `fork_id` through the error condition, but `app_id` is left completely unexplained. The agent cannot correctly determine the semantics of all required parameters from this description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Register'), the resource (a fork participant), and the specific semantic of the component name. It also differentiates from the sibling fork_log by explaining the downstream use. This distinguishes it from fork_create, fork_merge, and fork_log without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that this is a prerequisite for logging changes via fork_log, providing context for when to use it. However, it does not explicitly state when not to use it or mention any alternatives beyond the implicit fork_log, so it lacks exclusions. Still, the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the description's 'Append' matches. It adds the 'open fork' precondition, which is useful. However, it doesn't disclose side effects beyond appending, permission requirements, or failure behavior. Given the low complexity and annotation coverage, a 3 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, core action front-loaded, and parameter meanings woven in naturally. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple append tool with no output schema and safe (non-destructive) annotations, the description covers purpose, parameter semantics, and downstream usage. Missing details like the meaning of app_id/component or the exact format for type/ref are minor given the tool's simplicity. It's nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It clearly explains type, ref, and description, and indirectly implies fork_id via 'open fork'. However, app_id and component are left completely unexplained, leaving gaps for 2 of 6 parameters. The explanation adds value but is incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Append one change entry') on a specific resource ('an open fork's log') and differentiates it from siblings like fork_merge/fork_delete by explaining that it records changes that those tools later tally. This clearly distinguishes it from related operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when this tool is used ('before fork_merge/fork_delete') and explains that entries are tallied downstream, implying the logical sequence. It doesn't explicitly list exclusions or alternatives, but the relationship is made clear enough for an agent to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds valuable context by stating this is 'bookkeeping only' and 'does not write to the knowledge base', clarifying the side-effect boundary. No contradiction with annotations. It could mention more about state changes or return behavior, but it is sufficient for a simple bookkeeping tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The primary action is front-loaded, the boundary condition ('bookkeeping only') is stated immediately, and the alternative tool guidance is appended without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no output schema and only three parameters, the description covers the core purpose and distinguishes it from a sibling. However, it omits any explanation of what a successful call returns, how the note parameter is used, or how app_id/gap_id identify the target gap. These gaps make it minimally viable but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no guidance on app_id, gap_id, or note. The parameter names are somewhat self-explanatory, but the description does nothing to compensate for the complete lack of schema-level parameter descriptions, leaving an agent to guess at required identifiers and the meaning of the optional note.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action 'Mark a gap as being worked or answered' with a clear resource and scope. It explicitly distinguishes itself from gap_promote by noting it is bookkeeping only and does not write to the knowledge base, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names gap_promote as the alternative to use when actually landing a verified answer and closing the gap. This gives a clear when-to-use versus when-not-to-use directive, telling the agent to choose this tool for marking status and gap_promote for finalizing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses a concrete behavioral guarantee: 'The result always includes _continuity_filter showing exactly what was searched, so an empty list is legible.' It also specifies ordering ('newest first') and the limit effect. These details add real value 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three tight sentences with the primary action and scope front-loaded. Every sentence contributes: the fetch semantics, the usage timing, and the result legibility guarantee. There is no filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only fetch with no output schema, the description covers the key purpose, usage, and a result marker. However, it does not explain what a 'knowledge atom' includes or what the full return shape is, and it leaves `app_id` undefined. These gaps prevent it from being fully complete for a caller who needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for both parameters. It explains `limit` ('up to `limit`'), but it completely omits `app_id`, which is the only required parameter. An agent would not know what value to supply for `app_id` from the description alone, leaving a critical semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch') and a clearly defined resource ('knowledge atoms marked for session-startup continuity') with explicit selection criteria ('domain “continuity” or tagged “continuity”'). This clearly distinguishes it from the many sibling knowledge and store tools by specifying a unique scope and ordering ('newest first').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear contextual guidance: 'Call early in a session to recover standing decisions and in-flight state.' This tells an agent when to invoke it. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this. It adds useful behavioral detail beyond the annotations: the exact not_found error contract and the 'when available' caveat for persona file path. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core purpose and scoped to the essential facts: what is fetched, what is returned for unknown agents, and the read-only usage context. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, error behavior, and read-only nature, which is helpful given there is no output schema. However, it omits the semantics of app_id and include_permissions, and does not describe the successful return shape beyond persona text and file path. An agent could still call it correctly but would be guessing about the optional parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains agent_id as the lookup key, but app_id is required and unexplained, and include_permissions (a boolean with a default) is not described at all. This leaves a meaningful gap for an agent deciding how to invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch') and resource ('one specialist's registry row by agent_id'), and clarifies what the row contains (compiled persona text, persona file path). This clearly distinguishes it from sibling tools like specialist_list, which would return multiple rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use context: an orchestrator inspects a specialist before dispatching work to it. It does not explicitly name alternatives or exclusions, but the singular 'one specialist's registry row' and the read-only framing make the intended use reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and non-destructive, so the description does not need to repeat that, and it doesn't contradict them. It adds value by describing the response structure ({registry, specialists, total}) and the effect of include_permissions, which is useful 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two well-structured sentences that front-load the primary action, give the data source, explain the optional parameter, and mention the return structure. No redundancy or filler; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's output shape, read-only nature, and the alternative for single lookups. However, the unexplained app_id parameter, which is required, means an agent cannot correctly invoke the tool without further information. This prevents the description from being fully complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for parameter documentation. It explains include_permissions clearly ('when include_permissions=true — each one's permission set'), but provides no explanation for app_id, which is a required parameter. An agent would not know what to pass for app_id, leaving a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the specialist registry, enumerating agents the orchestrator can route work to, with role metadata and optionally permissions. It specifies the source file and the return shape, and explicitly contrasts with specialist_get, making its unique purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It names the alternative specialist_get for a single agent's full row, giving a clear when-not-to-use pointer. However, it does not explicitly state general use cases (e.g., 'use this to discover available agents'), but the purpose is evident. The guidance is present but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations: it explains the _collection field in each hit and the pagination mechanism with next_cursor. It also clarifies the read-only nature, consistent with readOnlyHint, and does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise but includes a slight redundancy in 'across every SOIL collection you can see — all of them, or only your manifest's store_scope if one is set.' It is well-structured with clear separation of scope, output, and pagination details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the core purpose and pagination are covered, the description omits any explanation of required parameters like app_id and query. This makes the description incomplete for an agent to correctly invoke the tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the four parameters (app_id, query, limit, cursor). Since schema description coverage is 0% and the description does not compensate, it adds no value to parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a token-AND search across all visible SOIL collections, with a clear distinction from store_search. It also notes the optional store_scope restriction, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use this tool when the target collection is unknown and to prefer store_search otherwise. This provides a direct usage guideline and differentiates from the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, open-world, non-destructive; the description adds that it needs no API key and uses DuckDuckGo HTML. It also discloses the exact output fields and a dependency for include_handoffs (web_net + consent.internet + live egress lease). This goes beyond the annotations without contradicting them, though it omits details like pagination or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loading the core purpose and return format in the first sentence. It then details parameters efficiently without fluff. Each sentence adds value, though the second paragraph could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a web search tool, the description covers the essential points: what it does, what it returns, and key parameter behaviors. But it lacks information on pagination (max_results behavior), error handling, and the required app_id semantics, which are non-obvious. Given the absence of an output schema, more details on result structure would be beneficial, but the tool's simplicity and open annotations reduce the burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 5 params but 0% coverage in the schema itself; the description compensates partly by explaining trusted_only and include_handoffs with specific behaviors. However, it does not clarify app_id (which is required), max_results (though default 8 is self-explanatory) or query beyond the obvious. With no other source for these, the description only covers 2 of 5 parameters, leaving the agent to infer the rest.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Purpose is specific and clear: 'Open web search via DuckDuckGo HTML (no API key).' It states the return fields (title, url, snippet, source, hostname) and even signals the intended use cases (current events, tech news, live open web). This distinguishes it from positional siblings like willow_institutional_search and willow_web_fetch, so an agent can quickly select it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear use cases: 'Use for current events, tech news, and queries that need the live open web.' It also hints at alternatives by mentioning 'institutional' in a sibling, but does not explicitly say when *not* to use this tool. The parameter-level guidance for trusted_only and include_handoffs is constructive, including the prerequisite for handoffs, but it doesn't contrast with sibling tools explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the core behavioral effect: clearing assignment state and freeing the agent for the next packet. It does not contradict the annotations (readOnlyHint=false aligns with the mutation described; destructiveHint=false is consistent because the action is a lifecycle reset, not a destructive delete). It adds context beyond annotations by explaining the positive outcome (ready for next packet) and the lifecycle placement, though it omits details like idempotency, error behavior, or what happens if called incorrectly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that packs the action, condition, and lifecycle context without fluff. It is front-loaded with the primary purpose and efficient in phrasing. A minor structuring improvement would be splitting the condition from the effect, but overall it is concise and well-ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description supplies the essential lifecycle context and effect, but it lacks explanations for two parameters and does not address edge cases like repeated calls, missing verification, or failure conditions. Given that the tool is a mutation with no output schema and no parameter documentation, the missing parameter semantics leave a notable gap in completeness, though the workflow context compensates partially.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% property coverage, so the description must shoulder the burden. It explains target_app (the app whose assignment state is cleared) and dispatch_id (the dispatch being cleared), but leaves app_id and session_id unexplained. Without clarification, an agent may confuse app_id with target_app or guess at the role of session_id. Partial coverage warrants a below-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action (release a specialist / clear live assignment state) and the specific resources affected (target_app's assignment for dispatch_id). It also frames the tool within the dispatch lifecycle (send → accept → handoff → verify → clear), which clearly distinguishes it from sibling tools like verify_handoff and agent_dispatch_result. An agent can immediately grasp what this tool does and why it differs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a precise condition for use: only after the handoff has been verified. It also identifies itself as the final step of the dispatch lifecycle, giving the agent an unambiguous ordering relative to other operations. This directly answers when to call the tool and implicitly warns against calling it before verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds semantic behavior beyond the annotations by explaining that it returns the files/symbols that import the given files, and it explicitly states 'Read-only', which aligns with readOnlyHint. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and well-structured: it states the purpose, gives a concrete parameter example, and notes read-only behavior. No unnecessary words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core operation and the most important parameter example, but it omits explanations for `app_id` and `db_path`, and does not describe the return format. It is adequate but not fully complete for an agent invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides useful semantics and an example for `file_paths`, noting they are repo-relative. However, `app_id` and `db_path` are not explained at all, and with no parameter descriptions in the schema, this is only partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: identifying which files/symbols import from the given files, framed as 'blast radius'. It is specific and distinguishable from sibling graph tools like search, explain, walk, and suggest, even though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description directly conveys the use case: determining the impact of changes by finding importers of specified files. It does not explicitly mention alternatives or when not to use the tool, but the intended context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the `readOnlyHint=true` annotation, the description explicitly says 'Read-only — never parses an entry into a connectable spec and never ratifies anything.' It also adds root-resolution behavior via the environment variable. This is materially useful behavioral context beyond the 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core operation, then adds essential constraints. The final quoted sentence is slightly rhetorical, but all other content earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the return value is only implicitly described, and the required `app_id` remains unexplained. The root semantics and non-mutating behavior are well covered, but this is not quite complete for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The `root` parameter is well documented: it is a filesystem path with a clear default (home directory, fallback to `$WILLOW_MCP_FEDERATION_SCAN_ROOT`). However, `app_id` is required and has zero schema coverage nor any mention in the description, so an agent has no information about what value to supply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the operation: scan `.mcp.json` files under `root` that the ratified registry does not yet own, and frames it as a 'Shadow-IT scan'. It also names the question answered — 'Which MCP servers exist that willow-mcp does not know about' — which distinguishes it from known-server lookups like `federation_list_servers`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual guidance: it is the first question an orchestrator must answer before federating. It does not explicitly name alternatives or state when not to use the tool, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description need not repeat that. It adds valuable context beyond annotations: the drift-diagnostics behavior (reconciling against Postgres), the Postgres requirement, and the roster-scope limitation. This meaningfully extends what the annotations alone convey. It doesn't contradict annotations in any way.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense, information-rich sentences with zero filler. Every clause adds value: the scope ('canonical fleet roster'), the content ('every registered agent and its declared state'), the enhancement ('drift diagnostics'), the prerequisite ('requires Postgres'), and the sibling routing. This is effectively front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only diagnostic tool with one parameter and no output schema, the description covers the essential context: what it reads, what it adds, the dependency, and how to route to the correct sibling. Minor gaps: no description of the return format or the shape of 'drift diagnostics,' but these are not critical for this tool's function. The sibling routing compensates for most missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain what 'app_id' means, how it filters the roster (e.g., per-app scope?), or any format constraints. With a single required parameter and zero schema documentation, the description bears full responsibility but gives no guidance on this parameter. This is a clear gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read'), a precise resource ('canonical fleet roster (fleet.json)'), and its scope ('every registered agent and its declared state'). It explicitly names what it is not (fleet_health) and what it adds ('drift diagnostics'), which clearly distinguishes it from siblings in the same family.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the alternative 'fleet_health' and the condition that selects it ('for liveness signals rather than roster membership'). However, it doesn't explicitly state when NOT to use this tool beyond the fleet_health contrast, nor does it provide prerequisites beyond 'requires Postgres.' This is clear but could be stronger with explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds the error behavior for unknown fork_id and confirms read-only status, which is useful context. It does not detail the exact structure of the environment snapshot or change log, but these are secondary details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence listing the record contents, followed by a terse error note and declaration of read-only. Every element adds value, and there is no redundancy or verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with no output schema, the description covers the key return elements and error behavior. It lacks parameter clarifications, which are partially mitigated by the explicit fork_id reference, but the absence of app_id explanation and the absence of any example or format details make it slightly incomplete for a tool with this many sibling fork operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% coverage; the description provides no explicit explanation of app_id or fork_id beyond a passing reference to fork_id in the error case. It fails to explain the purpose of app_id, leaving the agent to infer it from context. The description should at least clarify that fork_id identifies the fork and app_id scopes it, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a full record for one fork, enumerating the specific fields (title, state, participants, change log, environment snapshot). It also distinguishes it from fork_list and fork_log by the scope (one fork vs list/log), and mentions the error case for unknown IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving detailed information about a single fork, which is clear from the 'one fork' phrasing and the fields listed. It does not explicitly name alternatives or provide when-not-to-use guidance, but the read-only nature and single-fork scope make the intended usage reasonably inference-able.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the write nature (non-read-only) and the side effect of incrementing asked_count, which is consistent with the annotations. It also states the return object, providing transparency about outputs. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and focused. It includes the core action, the deduplication mechanism, and the return value without any extraneous detail, achieving high efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich set of sibling tools, the description does not explain the overall workflow or prerequisites, but it does convey the tool's role in maintaining a backlog of knowledge gaps. It mentions the return value (helpful since no output schema exists) and the priority mechanism, making it sufficiently complete for its intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description only clarifies the role of 'topic' and 'question' as the deduplication key. It does not explain 'app_id', nor does it specify any constraints or optionality for parameters, leaving a significant gap in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Log or bump...') and the specific resource ('we don't know this yet' entry). It distinguishes itself from sibling gap management tools by highlighting the bump behavior and priority signal, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when encountering a knowledge gap, and explains the deduplication behavior. However, it does not explicitly compare against alternatives like gap_list or gap_resolve, leaving some inference to the reader.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already say readOnlyHint=false and destructiveHint=false. The description adds the clearing of the needs-reply flag, the grove_write permission requirement, and the sender identity/grove_relay behavior. This goes beyond annotation redundancy and gives concrete behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded: purpose, effect, permission, then a structured Args list. It is efficient and free of filler, though the Args block could be tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation that clears a flag, the description covers purpose, permissions, and parameter semantics. Missing details like error handling or response format are minor given no output schema and the relative simplicity of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains channel_name, correlation_id, original_id, and sender, including default behavior and relay permission. The only unmentioned parameter is app_id, which is optional with a default and arguably not critical for ack operations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Acknowledge) and resource (received message, original), and explicitly says it clears the needs-reply flag. This distinguishes it from siblings like grove_reply or grove_flag 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for acking messages but does not explicitly contrast it with alternatives like grove_reply, grove_flag, or grove_watch. There's no 'when not to use' or explicit alternative routing, though the purpose is clear enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the permission requirement ('Requires grove_read'), the sort order, and the computed age_secs field in each entry. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: the core action and permission, the entry format, and the intended use case. The primary behavior is front-loaded and there is zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and safety annotations in place, the description covers purpose, sort order, permission, return-entry shape, and recommended usage context. The only material omission is the semantics of app_id, which leaves the definition slightly incomplete for a tool that accepts a parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% — the sole parameter app_id has no schema-level explanation — and the description never mentions app_id either. For an optional parameter with a default this is not catastrophic, but the description fails to compensate for the schema gap, leaving an agent unsure whether app_id filters the result set or scopes the fleet query.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List fleet agents') plus a distinguishing sort criterion ('by most-recent HEARTBEAT, newest first'). It also names the required permission and the exact shape of each entry, which clearly differentiates it from siblings like grove_fleet_status, fleet_status, and fleet_health that presumably summarize rather than enumerate per-agent heartbeat data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The closing sentence gives explicit context for when to call this tool: 'Use this to see who is currently alive in the fleet before addressing or coordinating with them.' This is a clear when-to-use directive, though it does not name alternatives explicitly or state when NOT to use it, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive operation. The description supplements this with important behavioral details: the write permission required, the default sender identity, and the relay permission for a different identity. It does not detail behavior when flags already exist, but given annotations, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short lines plus an args list. Every sentence provides necessary information, and the most critical information (action and permission) is front-loaded. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 parameters and no output schema. The description covers 3 parameters and provides the enum values for flag, which is good. But the missing app_id explanation is a gap, and there is no description of return values or side effects. It is usable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It does explain message_id, flag (including allowed values), and sender (default and permission nuance). However, it completely omits the app_id parameter, which appears in the schema with a default but no description, leaving an agent to guess its purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Set a flag on a message.' It is immediately clear what the tool does and is distinct from sibling grove_unflag, which removes a flag. The list of flag values further clarifies the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is used to set a flag, and it states permission requirements ('Requires grove_write' and 'A different identity requires grove_relay'). However, it does not explicitly name alternative tools like grove_unflag or mention when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, indicating a safe read operation. The description adds 'Requires grove_read' (a permission hint) but does not describe additional behavioral aspects such as rate limits or error conditions beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a short main sentence followed by three parameter explanations. No unnecessary verbosity, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (though not shown), so return values need not be explained. The description covers the essential operation and parameters. Minor gaps include potential error scenarios, but these are not required given the simplicity and output schema presence.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Each parameter is given a detailed, practical explanation. channel_name includes a pointer to find names via grove_list_channels, limit specifies max and default values, and since_id explains pagination logic explicitly. This far exceeds the bare schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and resource 'message history from a Grove channel', distinguishing it from siblings like grove_list_channels and grove_search. It accurately reflects the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions the required permission 'grove_read' but does not explicitly state when to use this tool versus alternatives like grove_search or grove_get_thread. The use case is implied but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark destructiveHint as false and readOnlyHint as false (implying a write operation), yet the description clarifies the write action and required permission (grove_write). It also discloses the sender identity behavior and the need for grove_relay for alternate identities. This adds useful context beyond annotations, though it doesn't discuss potential side effects or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with an Args list that is easy to scan. It front-loads the purpose and permission. While it could be more terse (e.g., merging permission notes), it is not verbose. The use of a bullet list for args is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple write operation with no output schema, descriptions need not explain return values. The description covers parameters, permissions, and alternate sender behavior. It lacks details on failure conditions or validation rules (e.g., what happens if reply_to_id is invalid), but for typical usage this is sufficient. Given the moderate complexity, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain parameters. It does for channel_name, content, reply_to_id, and sender, but app_id is entirely omitted. The description adds meaning for sender's default and permission model, but the incomplete coverage of app_id leaves a gap. Despite the gap, the description covers the essential parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Reply') and a specific resource ('to a message in a thread'), with key parameters defined. It distinguishes from sibling tools like grove_send_message (new message) and grove_get_thread (read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly say when to use it vs alternatives, the context of replying in a thread is clear. It does specify a permission requirement (grove_write) and conditions for using a different sender (grove_relay). It does not state when not to use it, but the nature of the action implies direct use for replies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false. The description properly discloses the mutation effects: writes two files and flips status to complete. However, it doesn't address idempotency, what happens if the dispatch is already closed, or error surface. destructiveHint=false combined with a tool that flips status could mislead — the description partially corrects this but doesn't fully resolve side-effect ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences carrying real information: what the tool does, which files each parameter feeds, the state transition, and the downstream contract. No filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists alerting an agent to the return shapehare — the description doesn't mention what happens on success/failure, idempotency for an already-completed dispatch, or how the tool reports failure of the verify checks. For a state-changing tool these are notable gaps. But it does frame the lifecycle well by naming verify_handoff and agent_clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains what goes into findings (handoff.json), narrative (closeout.md), and clarifies the checklist_resolved and envelope_clean booleans as agent declarations. dispatch_id is implied by context; app_id is not explicitly tied. Good coverage of 4 of 6 params, but the identity params are only implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a precise, specific statement: 'Close out a dispatch you accepted: writes handoff.json...flips its status to complete.' The verb, resource, and effect are unambiguous in the first sentence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the workflow contract — that this finishes a dispatch and that verify_handoff will check the two state flags before the orchestrator releases the agent. Doesn't state explicit preconditions (e.g., what must exist before calling, whether a dispatch can be re-closed), but the acceptance phrasing covers the main trigger.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral traits beyond these: it explicitly states 'makes no network call' (a behavior not conveyed by the annotations) and details what the readout includes (live/stub, credentials, gate). It does not contradict annotations and enriches the agent's understanding of the tool's side effects (none) and output nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero filler. The first sentence front-loads the primary purpose and enumerates the readout components. The second sentence adds a critical behavioral trait (no network call) and a usage directive. Every clause earns its place; it is compact without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with only 2 simple parameters and no output schema, the description covers most essentials: what it reports, that it is offline, and when to use it. The main gap is the lack of parameter explanation, but the parameters are generic enough that an agent might infer their roles. The description does not describe pagination or detailed response format, but that is not necessary for such a lightweight readout.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the meaning of the two parameters, app_id and name. However, it does not mention them at all. It says 'for one integration' but does not map that to the parameters or clarify whether name refers to the integration name or something else. An agent is left to guess the distinction between app_id and name, which is a significant gap given the total absence of schema-level guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('readout') and resource ('one integration'), then enumerates exactly what it reports: live or stub, credential presence, and the three-key egress gate. It also explicitly notes it makes no network call, which further defines the tool's role. This clearly differentiates it from sibling tools like integration_list or integration_call without needing to consult their schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: 'ask this before asking for a lease,' which tells the agent when to invoke it. It also implies this is a cheap, offline check by stating 'makes no network call.' However, it does not explicitly name alternative tools or state when NOT to use it, so it lacks explicit exclusions. This is still clear context for one key scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it discloses that input can be 'a slug id or free text', that it returns 'the lineage, not a blob', and that it synthesizes a plain-language answer. These details help the agent anticipate the tool's output shape and processing behavior 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states purpose, the second details input and output, and the third gives usage timing. There is no filler or repetition; the description is front-loaded with the core question and communicates a dense amount of useful information efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers most of what an agent needs: purpose, query semantics, return contents, and usage context. However, it omits any explanation of the required app_id parameter, and since there is no output schema, the description must carry the full burden of return-value documentation. It does explain return contents well, but the app_id gap is a notable incompleteness for a required parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explicitly explains the query parameter ('Give a slug id or free text') but says nothing about app_id, which is required. The query semantics are clear, but app_id remains ambiguous, leaving a gap in parameter understanding. Partial compensation for one of two parameters merits a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the exact question the tool answers ('why does X exist / where did X come from') and names the resource (recorded lineage). It then specifies the output contents (rationale, origin, authority, evidence, typed edges) and positions the tool as a distinct lookup verb ('This is the verb a curious agent runs before acting'), making it clearly distinguishable from lineage_list and lineage_record 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: 'This is the verb a curious agent runs before acting on something it didn't build.' This tells the agent when to use the tool (pre-action discovery) but does not explicitly name alternatives or state when not to use it. The guidance is implicit rather than comparative, so it misses the top score but provides enough context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false, and the description adds that it is non-destructive and idempotent, which goes beyond the annotation by explaining that staging is not a move and that repeated scans are safe. It also ties behavior to the pipeline step (nest_intake_file). It does not disclose internal state changes (e.g., how the review queue is stored), but the key traits are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences cover the entire behavior: the verb, resource, classification, staging, idempotency, non-destructive nature, the relation to nest_intake_file, and the folder override. The most important caveat (non-destructive) is front-loaded, and every word earns its place. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a scanning/staging tool with no output schema, the description lacks any mention of the return value or what the 'review queue' contains. It also omits prerequisites (e.g., what counts as a valid drop zone, whether app_id is needed for authorization). While it covers the core flow, an agent cannot anticipate what the tool returns or whether additional setup is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains the `folder` parameter by specifying it overrides default drop dirs and lists them, which is useful. However, it gives no explanation for the required `app_id` parameter, leaving agents to guess its purpose. With two parameters, a 3 is fair because one is well documented but the other is not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('Scan drop zone(s)'), defines the classifications ('classify new files by filename into tracks'), and names the follow-up action ('stage a review queue'). It distinguishes itself from sibling tools by explicitly noting non-destructive behavior and delegating the move operation to nest_intake_file, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool—before nest_intake_file—by stating 'nothing is moved until nest_intake_file' and explains the folder override. However, it does not explicitly name alternatives like nest_scan or nest_intake_queue, and only implies the context rather than giving explicit 'use this when' or 'instead of' guidance. Still, the idempotent, non-destructive note gives agents a strong usage cue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses side effects beyond the annotations: dry_run controls DB writes, return values exclude file content, inference is local by default but can leave the machine depending on OLLAMA_HOST, and document bodies are sent when off-box. It even corrects a previously overbroad privacy promise, which is unusually transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and output contract, then parameter behavior, then privacy edge cases. The final self-referential docstring correction is slightly meta but prevents reliance on an outdated promise. No filler sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It covers output shape, dry-run safety, model fallbacks, and privacy conditions thoroughly, which is essential since there is no output schema. However, required data parameters are undefined, and optional db_path/owner semantics are absent, leaving enough ambiguity to prevent confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It clarifies dry_run, use_embed, and use_llm well, but not the required app_id and folder, nor db_path and owner. The agent is left to guess the meaning of required parameters, which is a serious gap for a 7-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action set — walk a drop folder, extract/classify files, and write a SQLite Nest DB — and immediately clarifies the return contract: structure-only counts, never file content. This clearly distinguishes it from generic storage, search, or messaging siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides strong operational guidance: dry_run=True previews without writing, dry_run=False commits; use_embed/use_llm are explained by availability and fallback; and the off-box OLLAMA_HOST case is gated on consent.cloud_llm. It lacks an explicit 'use X instead' sibling route, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds meaningful behavioral context beyond the annotations: the tool registers the app/session pair, resolves human-vs-dispatch entry mode, and returns a specific orientation payload. With idempotentHint=true, readOnlyHint=false, and destructiveHint=false already declared, the description enriches the safety profile rather than just restating it. Re-entry behavior is not described, but the idempotent hint largely covers retry safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences with zero filler: the critical 'FIRST CALL' directive leads, the behavioral summary follows, and the closing-tool routing ends. The long enumeration of returned orientation items earns its place because there is no output schema to fall back on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The detailed orientation return list (project info, ORIENT.md, standing records, latest handoff, aliases, FRANK presence) compensates well for the missing output schema, and the close-session routing completes the lifecycle picture. Remaining gaps are minor: no prerequisites, error conditions, or re-entry semantics beyond what the idempotentHint implies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 5 parameters, so the description must compensate. It explains only dispatch_id ('pass dispatch_id when entering to work an assigned packet'), which is genuinely useful, but leaves app_id, session_id, project, and workspace without any added meaning beyond their bare names. Four of five parameters remain semantically thin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Registers the app/session pair, resolves the entry mode... and returns orientation' — with a clear scope. The opening 'FIRST CALL of any session' distinctly separates it from sibling session tools like session_read, session_bind, and session_reconcile. No ambiguity 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit positioning ('FIRST CALL of any session') and routes the agent to the appropriate complementary tools by path: 'session_handoff_write (human path) or handoff_write_v4 (dispatch path).' Also explains when to pass dispatch_id ('when entering to work an assigned packet'). Lacks an explicit 'when not to use' exclusion, but the lifecycle framing leaves little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value beyond those annotations by disclosing the exact not_found error shape for unknown sessions and characterizing the file as 'thin' rather than a full session object. No contradiction with annotations 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler. The core operation is front-loaded, followed by the error behavior and read-only confirmation. Every sentence contributes useful information, and the 'Read-only' sentence, while redundant with annotations, is short and non-harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read with no output schema, the description covers the operation, the content of the state file, and the unknown-session error path. A fully explicit success return envelope is not described, but the listed file contents imply what a successful read returns, so the definition is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the two undocumented parameters. It only paraphrases them as 'app/session pair' and does not explain format, meaning, or any constraints beyond their obvious roles. The schema supplies only titles, so the description adds minimal semantic value for invoking the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Read'), a precise resource ('thin per-session state file'), and the file's contents (entry mode, bound dispatch, project/workspace). It also names the related writer (session_enter), making the tool's role unambiguous and distinct from write-oriented session siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to read the per-session state written by session_enter. It does not explicitly list exclusions or compare with alternative readers, but the relationship to session_enter and the 'Read-only' framing provide enough guidance for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-destructive operation, so the description usefully adds the side-effect boundary: it writes to the ledger, returns a correlation id, and deliberately does not dispatch or notify. Idempotency and failure behavior are not covered, but the core behavioral contract is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry the full purpose, the critical non-effect, the return value, and the companion tools with no filler. The primary action is front-loaded before the alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description identifies the return value and related tools, which is helpful. However, with no output schema and zero parameter descriptions, the missing explanation of app_id and context is a real gap that an agent would need to infer from parameter names alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the input schema provides only names and types. The description maps 'task goes to that agent' to task/target_agent but does not explain app_id, the optional context object, or what values they expect, leaving a required parameter under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Record') and resource ('routing_decisions ledger'), states the return value (routing_id), and explicitly scopes behavior by noting it does not start or notify the target agent. This clearly distinguishes it from dispatch_send and agent_dispatch_result in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use this tool to log a routing decision, not to deliver work. It names the companion tools dispatch_send for actual delivery and agent_dispatch_result for completion reporting, leaving little ambiguity about workflow sequencing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavior beyond annotations: it writes to a local SQLite DB, uses no network/Postgres/external CLI, is idempotent because it upserts, and documents the default DB path and environment override. This is exactly the kind of context the annotations do not already provide, especially the safety and rerun implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: it states the operation, the usage timing, the environment constraints, and per-parameter notes in just a few sentences. Each sentence adds useful information, with no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with no output schema and minimal annotations, the description covers most context: operation, storage, idempotence, environment, and rerun behavior. However, the mandatory app_id parameter is entirely undocumented, which leaves a critical gap for an agent trying to construct a valid call. Otherwise it would be complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must carry the parameter documentation load. It does explain repo_root, db_path, and force, but it completely omits app_id, which is a required parameter in the schema. An agent could not reliably call this tool without understanding app_id, so the parameter documentation is materially incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: indexing a repository's Python and JS/TS files into a local SQLite symbol graph. It also describes what the graph contains (symbols, import/inherit edges, per-file stats) and clearly separates this setup operation from the sibling 'read tools' like code_graph_search and code_graph_explain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: 'Run once before the read tools.' This tells an agent when it should be used relative to the code_graph_* siblings. It does not explicitly enumerate when-not-to-use it or name the exact alternative tools, so it falls short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. It adds valuable behavioral context: it is silent by default, only speaks under specific conditions, and each surfacing carries only title + time, never the event body. This goes beyond the annotations and helps the agent understand what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It front-loads the core purpose, then explains the conditions, then the output format, and finally the parameter. Every sentence adds value without redundancy. It's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a read-only tool with annotations covering safety. It explains the trigger conditions, output content, and the 'now' parameter. However, it doesn't explain the return format beyond 'title + time only', which might be sufficient given no output schema. It also doesn't clarify what 'split-stick halves' means, but that's domain-specific jargon that might be understood in context. Overall, it's fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'now' as an ISO-8601 instant to evaluate against (default: current UTC), which adds meaning. However, it doesn't explain 'app_id' or 'lead_minutes' beyond what the schema shows (app_id is required, lead_minutes has a default of 15). The description mentions lead_minutes in the context of 'starting within lead_minutes' but doesn't elaborate on its format or constraints. Given the low coverage, the description partially compensates but leaves gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it surfaces commitments that deserve operator attention based on specific conditions (imminent, conflicting, or unacknowledged changes). It uses specific verbs ('surfaces', 'speaks') and a clear resource ('the dew-rule view'). It distinguishes itself from siblings like commitment_list and commitment_acknowledge by focusing on what needs attention rather than listing or acknowledging commitments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when the tool is relevant: when split-stick halves disagree, indicating a commitment is imminent, two active commitments conflict, or a change is unacknowledged. It also notes it is silent by default, implying it should be used to check for attention-worthy items. However, it doesn't explicitly contrast with alternatives like commitment_list or commitment_acknowledge, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses read-only behavior, consistent with annotations, and goes further by explaining HMAC signature verification: unverified packets are excluded from the main list and appear in a separate 'unverified' field with flags. This exceeds the annotation's basic readOnlyHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough and front-loaded with the main action and filters, but the HMAC signature explanation is somewhat verbose. It remains concise enough for an agent, though it could be trimmed without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers filters, pagination, and return structure, it fails to explain the required app_id parameter, which is essential for correct usage. Without an output schema, the description should have been more complete to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the filter parameters (to_app, from_app, status) and cursor for pagination, but completely omits the required 'app_id' parameter from the schema. It also does not clarify the effect of 'limit'. Since the schema lacks descriptions, this is a significant gap in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists dispatch packets newest-first with filtering options, and explicitly contrasts with dispatch_read for single-packet retrieval. It also notes the read-only nature, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus dispatch_read (for one packet's brief) and explains pagination via the cursor. It does not explicitly mention when not to use it (e.g., for sending), but the sibling dispatch_send implies that, making this adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only establish readOnlyHint=false and destructiveHint=false — the description goes far beyond them by disclosing real side effects: exact files written (meta.json, assignment.md), target directory ($WILLOW_HOME/dispatch/), the envelope/quota-gated Postgres exception (#333), and the dispatch_id-carrying return value. This is exactly the kind of state-mutating behavior an agent can't infer from 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Approximately 110 words and every clause earns its place: behavior → file artifacts → key params → lifecycle → edge case → return value. The 'Filesystem-backed unless an authority envelope...' sentence is syntactically dense but compact for the nuance it packs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an agent deciding whether to use this tool, the description is sufficient — it explains what happens, where, under what authority exception, and what comes back. But there's no output schema to fill the void, leaving the return shape partly inferential, and the valid phase values/context_refs format are pure guesses. It clears the bar but leaves real gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description is the sole documentation and it covers only 2 of 9 parameters — 'assignment_md is the full brief; reply_to names who verifies the handoff.' The highest-risk params (context_refs, phase) get zero help, and the schema only provides defaults for the others. Useful where it lands, but it's less than a quarter of the parameter surface.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource: 'Create a dispatch packet assigning work to another agent.' It clearly distinguishes itself from its sibling family through the lifecycle ('advances pending → working → complete via dispatch_accept and handoff_write_v4'). Naming the written files (meta.json, assignment.md) and directory cements the artifact contract.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is clearly implied and scaffolded: it's the creation step in a state machine whose continuation steps are dispatch_accept and handoff_write_v4, which is exactly the decision boundary an agent needs. However, it never explicitly enumerates when not to use it or points to an alternative by name — the agent must infer exclusions from the visible sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses that results are scanned and sandwich-wrapped if flagged, and that this is an egress lane requiring a lease. It also mentions that the capability allows spawning a server at all. This adds meaningful behavioral context about side effects and output handling that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two paragraphs with zero filler. The primary purpose is front-loaded in the first sentence, followed by necessary security context and output handling. Every sentence earns its place; no word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex federation tool with no output schema, the description covers authorization and output sanitization thoroughly but omits parameter semantics, return details, and error behavior. Given the tool's high complexity and the absence of output schema, the lack of parameter explanation and return type description makes it incomplete, though the security aspects are well addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for parameter meaning, but it does not. The description implies server_id and tool through its opening statement, but app_id and arguments are entirely unexplained. The schema itself only provides generic titles and type names, leaving the agent to guess that app_id identifies the calling app and arguments are passed to the downstream tool. This is insufficient compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Call one tool on one ratified downstream MCP server,' which states a specific verb (call), resource (one tool on a specific server), and scope (ratified downstream MCP server). It clearly separates this from sibling tools like federation_list_servers (which lists servers) and integration_call (which calls integrations). No ambiguity exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit and detailed authorization prerequisites (manifest capabilities, namespace permission, operator consent, egress lease, ratified registry), giving clear when-to-use context. However, it does not explicitly mention alternatives, exclusions, or when not to use this tool. It implies this is the general call tool but doesn't contrast with federation_discover or federation_list_servers, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it readOnlyHint=true and destructiveHint=false, and the description confirms 'Read-only.' Beyond that, it proactively discloses pagination behavior (returns {items, next_cursor}), the ordering ('most-asked first'), filter semantics, and the meaning of asked_count. This is exactly the kind of behavioral context that adds value on top of 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is two sentences, front-loaded with the operation and resource, then efficiently packing pagination, filtering, status values, ordering, and the read-only property with zero filler. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large toolset and 0% schema coverage, the description covers the core behaviors well but is incomplete. The required app_id and the limit parameter are undocumented, and there is no output schema or mention of the item structure beyond asked_count. For a tool that reports 'what we don't know yet,' the agent still needs to guess what each item contains, making it not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it does not. It explains cursor usage ('pass the returned next_cursor as cursor') and mentions filtering by topic/status, yet it omits the required app_id entirely and never explains the limit parameter. For a required parameter with zero schema documentation, this leaves a critical gap that the agent cannot infer reliably.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('List backlog gaps') plus a sorting qualifier ('most-asked first') and a memorable metaphor ('the fleet's shared what we don't know yet queue'). This clearly distinguishes gap_list from the many other list-style siblings (grove_list_channels, store_list, fork_list) and from the writing tools in its own gap_* family (gap_log, gap_resolve, gap_delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: how to paginate (pass next_cursor back as cursor) and how to filter (by topic and/or status with the allowed status values). It does not explicitly mention when not to use this tool or name an alternative tool, but for a pure listing tool the usage is self-evident from the resource name and the context described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: messages are 'ordered by priority', and it requires 'grove_read' permission. This extra detail enriches the agent's understanding without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a clear Args list, with no redundant wording. The primary purpose is front-loaded, and each parameter explanation is concise and directly useful. It earns its place without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown here) and moderate complexity, the description covers essential aspects: what it fetches, ordering, permission requirement, and key parameters. It does not describe return structure, but that is handled by the output schema. Minor omissions like pagination details are not critical for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains three of four parameters clearly: 'agent' (receiver), 'channel_name' (restrict to one channel), and 'since_id' (cursor for id greater than this). However, 'app_id' is not described, leaving a gap. Still, the explanations are meaningful and specific.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Fetch bus messages addressed to this agent (or broadcast), ordered by priority.' It uses a specific verb ('Fetch'), identifies the resource ('bus messages'), and differentiates from siblings like grove_bus_send (send) and grove_get_history (history) by focusing on receiving messages addressed to the agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (to receive messages addressed to the agent), but does not explicitly contrast with alternatives or provide when-not-to-use guidance. It mentions a prerequisite ('Requires grove_read'), which is helpful, but lacks explicit routing to or away from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (no read-only, no destructive hint), so the description carries the burden of explaining the operation. It reveals the sender-resolution default, permission requirements, and that a different identity requires grove_relay. It also explains correlation_id and ttl semantics. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with a one-sentence purpose, followed by a short prerequisite note and a linear Args list. Every line earns its place. Minor overhead from formatting spaces but overall well structured and not padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a send tool with no output schema, the description covers permissions, defaults, and parameter semantics. However, it doesn't mention what the return value indicates (success/error), whether messages are durable, or what happens when a message cannot be delivered. The app_id parameter is also unexplained. These gaps make it decent but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only semantic source for parameters. It documents 8 of 9 parameters clearly (channel_name, content, sender, to_agent, bus_type, priority, correlation_id, ttl), and adds useful value like the priority-to-mode mapping and ttl expiration behavior. The only omission is app_id, which keeps it from being a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear action and object: 'Send a structured bus message.' It adds meaningful qualifiers — 'addressed, typed, and prioritized' — which distinguish this tool from sibling messaging tools like grove_send_message and grove_bus_receive. No ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides helpful usage context, including the required grove_write permission and the extra grove_relay requirement when impersonating another sender. It does not explicitly say when to choose grove_bus_send over grove_send_message, but the structured-bus framing and parameter details imply the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only and not destructive, which aligns with the description's mention of clearing a flag (a modification). The description adds the permission requirement (grove_write) but does not describe potential side effects, error conditions, or return behavior, so transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and focused, with no unnecessary detail. It uses two clear sentences, effectively conveying purpose, permission, and key parameters without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the operation and the absence of an output schema, the description covers the essential aspects: what it does, permission, and key parameters. It does not mention edge cases (e.g., flag not present) or relationship to grove_flag, but for a straightforward unflag action it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains three of the four parameters (message_id, flag, sender), adds meaning for sender (default and permission), and clarifies the roles of the others. It omits app_id entirely, which reduces coverage but the description still adds value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (clear a flag) and the target (a message), and distinguishes it from sibling tools like grove_flag (which sets a flag) and grove_flagged (which lists flagged messages). It also mentions the permission requirement, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to remove a flag from a message) and notes permission requirements. However, it does not explicitly point to alternatives (e.g., grove_flag for setting a flag) or state when not to use it, which would make it fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotation, the description adds sorting order ('newest first') and filter options, giving useful behavioral details. It does not mention return format or error handling, but these are not critical for a read-only list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that fully conveys the tool's purpose and key options without redundancy. Well-structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the annotations (read-only) and schema, the description adequately covers the core functionality. It lacks explicit differentiation from sibling list tools, but the context of 'attestation records' is clear. The missing app_id/limit semantics slightly detract, but overall enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains the filtering behavior for subject_id, subject_type, and status, but does not clarify the semantics of app_id (required) or limit (pagination). Since the schema provides no descriptions, there is a gap for these two parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (list), the resource (attestation records), and optional filters. Distinguishes itself from sibling tools like human_attestation_create (creation) and human_required_list (different resource type).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates when to use (for listing attestations) but does not explicitly contrast with alternative list tools. However, the descriptive filters and 'newest first' orientation provide enough guidance for typical usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, and openWorldHint=false. The description adds important behavioral context: the row is updated in place (who/when/note), never deleted, and returns unknown_item if the id doesn't exist. This goes beyond the annotations by explaining the mutation semantics and error handling, which is valuable for an agent deciding whether to call this tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded. It states the purpose, the status values, the mutation behavior, and the error case in three sentences. Every sentence adds value, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 params, 2 required, no output schema), the description covers the key aspects: what it does, the status values, the in-place update behavior, and the error return. It doesn't specify the exact return format on success, but that's not critical for a mutation tool. The description is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'status' parameter's allowed values (resolved | dismissed | acknowledged) and mentions 'note' implicitly ('who/when/note'). However, it doesn't explain 'app_id' or 'item_id' beyond their names, which are fairly self-explanatory. The description adds some value for 'status' but leaves the other parameters to be inferred from their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to resolve, dismiss, or acknowledge a human-required queue item. It specifies the verb (resolve/dismiss/acknowledge), the resource (human-required queue item), and the allowed status values. This distinguishes it from siblings like human_required_enqueue and human_required_list, which handle different operations on the same queue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when a human needs to act on a queue item. It doesn't explicitly state when not to use it or name alternatives, but the context of 'human-required' and the sibling names (enqueue, list) make the usage context clear. It could be improved by explicitly stating that this is for updating the status of an existing item, not for creating or listing items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate that this is a non-read-only, non-destructive write, so the description carries behavioral weight. It discloses what is created (atom with domain/tags/source), the return shape, and a required schema-mapping prerequisite; 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences deliver behavior, comparison, return value, and prerequisite without wasted words. The core action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a small append operation with no output schema, this is nearly complete: it covers effect, return shape, and a critical precondition. The only notable omission is app_id semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description maps three of four params: content (free-text entry), tags, and source. The required app_id is never explained, which is a meaningful gap for a 0-coverage schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Append a free-text journal entry'), a precise target (a new atom in domain 'journal'), and contrasts itself with knowledge_ingest. This makes the tool's identity unmistakable even among many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use context for simple journal entries and explicitly contrasts with knowledge_ingest on domain choice and sensitivity tiering. It stops short of stating a direct 'use X when...' rule, but the alternative is identifiable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses idempotency, the side effect of replacing previous flag metadata, and the guarantee that 'Original content is unchanged'. This is useful behavioral context beyond the sparse readOnly/destructive hints and genuinely helps an agent understand the tool's impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences provide the action, idempotency, side effects, and constraints with no fluff. The purpose is front-loaded and the structure is clean and easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool's core behavior and prerequisites are documented, but with no output schema and no return-value description, the agent is left without success/failure semantics or a clear sense of what to expect after invocation. This is a visible gap for a mutating tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, and the description does not explain app_id, reason, severity, or refs. It only hints at the atom/tag context. An agent cannot infer the valid semantics or relationship between required parameters and their effects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Attach a visible integrity flag to an existing KB atom (tags only)'. It clearly identifies the operation and scope, and the tag-only qualifier helps distinguish it from other flag-related tools in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete usage prerequisites: 'Requires knowledge_curate and a confirmed schema with a mapped tags column'. This tells an agent when it is safe to call the tool, though it never explicitly names an alternative or states 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses that it reads from the fleet Postgres queue, is read-only, and returns an error for unknown task_id. While annotations already indicate read-only, the description adds error handling and poll semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, with the primary action first, followed by details. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description specifies return fields and error case. It covers the main use case but omits details like status values or other error responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has no descriptions for app_id and task_id. The description explains task_id as identifier from task_submit, but does not clarify app_id's role, leaving a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool polls a single task submitted via task_submit, and distinguishes it from task_list by focusing on a single task_id. It also specifies the returned fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage after task submission and for polling until completion, but does not explicitly contrast with alternative tools like task_list or task_submit. The 'poll until' suggests iterative use, but no explicit when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, covering the read-only and non-destructive nature. The description adds pagination behavior (returns items and next_cursor, pass next_cursor as cursor) which is valuable beyond annotations. There is no contradiction, but the description doesn't disclose other behaviors like rate limits or default state filtering details beyond what's implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly efficient, front-loading the core purpose and state options, then adding pagination details and a pointer to the alternative. Every sentence earns its place: purpose, pagination protocol, and usage distinction. No fluff or repetition of schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 4 parameters and no output schema, the description covers the key aspects: what it lists, the state parameter's meaning, pagination handling, and a sibling alternative. It doesn't mention the limit parameter's default or allowed range, but that's minor since the schema has defaults. Given the annotations cover safety, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter understanding. It explicitly explains the 'status' parameter by listing 'open', 'merged', 'deleted' with default 'open', and explains the 'cursor' parameter by describing the pagination flow (pass next_cursor as cursor). This goes beyond the schema's minimal property definitions and provides actionable semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List forks in one state' with specific states enumerated, and distinguishes it from fork_status as a summary vs full log. The verb 'List' plus resource 'forks' and filtering by state makes purpose unambiguous and differentiates from siblings like fork_status and fork_log.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use (find in-flight work units) and mentions using fork_status for a single fork's full change log, which serves as an alternative. However, it doesn't explicitly state when not to use this tool or mention other alternatives like fork_log, so it's strong but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotation destructiveHint: true, the description discloses that the operation tallies change-log entries as promoted, records outcome_note, and is irreversible. These are important behavioral side effects not implied by the annotation alone. This meets the standard of adding significant context about what the tool does beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and each sentence adds unique value: the primary action, the side effects, and the irreversibility are stated in three direct sentences. There is no redundant or filler content, and the most important information (what the tool does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential aspects: what it does, side effects, and irreversibility. It also guides the agent to fork_status for post-closure inspection. It does not discuss error conditions (e.g., calling on a non-existent fork) or prerequisites, but given the moderate complexity and absence of an output schema, this is largely sufficient for an agent to invoke the tool correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate by explaining parameters. It explicitly explains `outcome_note` as the close-out summary, but the two required parameters (`app_id` and `fork_id`) are not described at all. Since these are the critical identifiers, the agent is left without guidance on their meaning or format, which is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Close an open fork as MERGED'. It differentiates itself from siblings like fork_status or fork_delete by specifying the action results in the work being 'promoted' and being irreversible. The context that the fork 'cannot be reopened' further distinguishes it from other fork operations, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear contextual usage guidance: it is for when 'the work landed', implying the fork is ready to be merged. It also mentions that after closure the fork 'can only be inspected via fork_status', which implicitly tells the agent to use fork_status for inspection. However, it does not explicitly contrast with fork_delete or fork_join, so it stops short of naming alternatives explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explains the anchor_status values (anchored, unanchored, untrusted, unreadable) and what each means, including that only 'anchored' means the head was actually compared. It also notes the tool may take a moment on a long ledger, which is useful for the agent. The description does not contradict annotations, and it adds context beyond what annotations provide, though it could mention the exact return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but well-structured, with the core purpose front-loaded and the anchor check explained in a separate paragraph. It is longer than necessary but each sentence adds value, explaining the anchor mechanism and its statuses. The structure is logical, moving from the main function to the edge case and then to usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (chain verification with anchor comparison), the description is quite complete. It explains the anchor_status cases, the CLI-only anchor creation, and the read-only nature. However, it does not describe the return format or the exact structure of the verification verdict, which could be useful. The parameter app_id is also unexplained, which is a minor gap. Overall, it covers most of what an agent needs to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the undocumented parameter. However, the description does not explain what app_id is or how it affects the verification. The parameter is required, but its semantics are unclear. The description focuses on the tool's behavior rather than the parameter, leaving the agent to guess what app_id refers to. This is a gap, but the tool's purpose is clear enough that the parameter might be self-explanatory in context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool re-hashes the entire FRANK governance chain and verifies every prev_hash → hash link, detecting tampering, edits, or gaps. It also explains the additional anchor check, which distinguishes it from a simple chain verification. The verb 'verify' and resource 'FRANK governance chain' are specific, and the description differentiates it from siblings like frank_read and frank_append.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool (to verify chain integrity) and when not to (it's read-only, and the anchor creation is CLI-only, not an MCP tool). It also mentions the alternative for creating/refreshing anchors: 'willow-mcp frank-anchor'. This provides clear context and exclusions, helping the agent decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite destructiveHint=true, the description clarifies that this is a soft-delete/archive operation: the gap is retained with deleted=1 and only stops appearing in gap_list. It also discloses the return payload and the not_found error condition, adding important behavior 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and front-loaded, with each sentence earning its place: operation, purpose, behavioral effect, and return contract. No filler or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool, the description covers purpose, soft-delete semantics, visibility change, return format, and error behavior. The only notable gap is the undocumented app_id parameter, which prevents it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It only implies that gap_id identifies the gap and says nothing about app_id, its role, format, or how the two interact. The parameter names are somewhat self-explanatory, but the description does not fully document them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: "Soft-delete a single gap by id," which clearly identifies the operation and its target. It further distinguishes this from sibling gap tools by explicitly scoping it to "clearing junk or test entries from the backlog without disturbing its real gaps."
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the intended use case: clearing junk or test entries without affecting real gaps. It does not explicitly name alternative tools or exclusion conditions, but the "without disturbing its real gaps" phrasing gives meaningful context for when this softer deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say not read-only, not destructive, and not open-ended. The description adds crucial behavioral context: it refuses with unconfirmed_schema if the schema mapping isn't confirmed, requires Postgres, and is gated as its own permission. These are significant disclosures beyond the annotations, though it doesn't mention return format or side effects beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but every sentence contributes meaning—purpose, prerequisites, error behavior, and permission context. It is front-loaded with the core action and follows with necessary constraints. A slight trim could improve conciseness, but the structure is logical and not redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters, 5 required, and no output schema, the description covers the essential operational context: prerequisites, schema-confirmation gate, error condition, and permission separation. It doesn't explain the exact format of sources or the return value, but given the absence of an output schema, such details are less critical. The description is sufficient for an agent to understand when and how to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies the confirmed_by parameter ('a human name, an agent id, whatever this fleet uses as an identity, but never empty') and states that at least one source is required. However, it does not elaborate on app_id, gap_id, tags, or domain beyond the schema's names and defaults. This gives some semantic value but leaves room for more detail on the remaining parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Turn a gap into trusted knowledge,' a specific verb and resource that clearly distinguishes this from gap_log, gap_resolve, and knowledge_ingest. It explains the operation is promotion to a durable knowledge base, differentiating it from SOIL-only gap operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool and the conditions that must be met: it requires an answer, source, and confirmed_by, and it requires a schema-confirmation gate. It also contrasts with SOIL-only gap tools, names the specific alternative (knowledge_ingest) and the error case (unconfirmed_schema), and explains permission separation from gap_write. This is thorough and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the sparse annotations, the description discloses that the atom is updated in place, content and ID remain unchanged, the exact return shape is {id, domain} or {error: not_found}, and a confirmed 'knowledge' schema mapping is required. This is strong behavioral disclosure for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact, front-loaded with the core purpose, and every sentence adds value: scope, in-place behavior, return value/error, and a prerequisite. There is no repetition of schema information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation tool with no output schema, the description covers the operation, mutation semantics, return shape, and a key precondition. It falls slightly short by not explaining app_id or what a confirmed schema mapping entails, but it is sufficiently complete for correct invocation in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description needed to define all three required parameters. It implicitly maps atom_id and domain through context, but app_id is never mentioned at all, leaving a meaningful gap in parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('move') and a specific resource ('existing knowledge atom') with a clear target ('different domain'). It is distinct from sibling tools like nest_promote and gap_promote because it explicitly scopes the operation to knowledge atoms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The example 'lift a journal entry into a topical domain once it proves durable' gives concrete contextual guidance on when promotion is appropriate. It does not explicitly name alternatives or exclusion conditions, but the intended use case is clearly conveyed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive; the description adds useful behavioral detail: newest-first ordering, the exact receipt fields returned, and the app_id scoping. It does not mention pagination or limit behavior, but that is a minor gap given the simple read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core behavior, then adds scoping context in a second short sentence. Every clause adds value, and the output fields are listed compactly without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple two-parameter, read-only tool with no output schema, and the description adequately covers what it returns, how results are ordered, and who it is scoped to. The agent has enough information to call it correctly and understand the response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'app_id' as the scoping identity, but it does not describe the 'limit' parameter's meaning in terms of the number of receipts returned. The tool name and the phrase 'most-recent' hint at it, but the description does not fully carry the parameter-documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Return your own most-recent tool-call receipts'. It also specifies ordering ('newest first'), output fields, and scope ('scoped to your app_id'), which distinguishes it from sibling tools that query other identities or broader history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is a 'self-audit trail' and is 'never another identity's calls', which tells the agent when to use it and when not to. It does not explicitly name alternative sibling tools, but the scoping language communicates the main usage boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare the tool is read-only and non-destructive, so the safe behavior is covered. Beyond that, the description adds useful behavioral details: it returns a scope value (which may be null), and that output includes both names and a count. While it does not go into error cases or permission requirements, for a simple listing tool the disclosed behavior is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: it states the core function, adds the `store_scope` nuance, and closes with the return shape. It is only three sentences yet covers purpose, scope filtering, and output summary. This is concise without being terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the action, the scope narrowing, the output (collection names, count, and scope), and the usage context versus `store_list`, which is thorough for a read-only listing tool. The only omission is any explanation of the single `app_id` parameter, and no output schema is provided, but the description gives enough output shape for an agent to proceed. It is slightly incomplete but clearly sufficient for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only the parameter name `app_id` and type `string` with zero description coverage. The tool description does not explain what `app_id` means, its format, requirements, or how it affects the result. Even though the name is somewhat self-explanatory in the context of an app's store, an agent would have to guess its exact meaning and whether it is expected to be a literal ID or a filter context. This is a notable gap given only one parameter exists.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'List' plus a resource ('SOIL collections'), and explicitly narrows scope to the user's `store_scope`. It also clearly differentiates itself from `store_list` by noting that this tool is how you learn collection names when `store_list` requires a name. This makes the tool's purpose unambiguous and distinguishable from its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description directly tells when this tool is appropriate: when you want to know what collections exist in the store, and it contrasts with `store_list` by pointing out that `store_list` needs a collection name. It also explains the `store_scope` narrowing, so an agent knows this returns only what is visible to them. This is explicit, high-quality usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive, and the description adds meaningful behavioral details beyond that: counts only live records, excludes soft-deleted records, returns results largest-first, includes store-wide totals, and respects store_scope scoping. These are exactly the kinds of behavioral traits an agent needs to interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every clause adds value: scope, companion relationship, soft-delete behavior, ordering, totals, and a concrete use case. Nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only stats tool with one parameter and no output schema, the description covers return contents, ordering, scoping, and a practical use case. The only notable gap is the unexplained app_id parameter, but overall the tool is well specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description carries the burden of explaining the single app_id parameter, but it never mentions it. The parameter is named app_id and required, yet the description only talks about store_scope and collections, leaving the agent to infer how app_id relates to the call. It is not misleading, but it provides no parameter guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: it returns per-collection live-record counts, explicitly framed as the numeric companion to store_collections. This makes its purpose unambiguous and distinguishes it from the sibling list tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: it is the numeric counterpart to store_collections and is useful for spotting polluted or runaway collections before purging. It implies when to use it but does not explicitly state when not to use it or name alternatives beyond store_collections.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Clearly states read-only behavior, self-scoping (never other identities), mode-dependent auth requirements, and the ungated failure/edge behavior. Explicitly explains that the resolved tool list means 'group expansion minus deny_tools'. Aligns with the readOnlyHint annotation; no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the identity result summary, then scope, then gating, then edge case. Dense but organized; each sentence adds a distinct fact. The parenthetical expansions ('group expansion minus any deny_tools', 'a valid per-call credential') are useful but could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the reported fields, mode-based scope, permission-gating nuance, and edge case (missing manifest). Given there's no output schema, the description is largely sufficient; only the concrete response format (JSON/text) is left implicit, which is a minor gap for a diagnostic tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema gives zero description for app_id (default ''), but the description covers its meaning in both modes: OAuth-derived in serve mode, and an owned/app-bound identifier requiring valid per-call credential in local enforcement. This compensates for the 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with 'Report who you are and what you may do' and enumerates precisely the fields returned: app_id, role, permission groups, resolved tool list, store_scope, and human-only status. No ambiguity about what this tool does or its self-scoped nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when it's appropriate: identity/entitlement discovery, and distinguishes execution modes (serve-mode OAuth binding vs. local enforcement with credential proof). Explains the read-only, self-scoped usage and the ungated edge case for missing manifests. Lacks a concrete invocation example but the use-cases are otherwise well conveyed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds meaningful behavioral context beyond that: it specifies that environment-variable values are never returned (only names), that unratified servers are excluded, and that ratification is a prerequisite for connecting. These details inform the agent about the tool's safety and scope 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the core listing purpose and field details, then adds the key exclusion and a pointer to the relevant sibling. Each sentence earns its place, and the structure is scannable and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly covers the output contents, exclusions, and the relationship to federation_discover, which is strong given the tool's simplicity and the annotations covering safety. The one significant gap is the lack of any guidance on the required app_id parameter, which an agent must know to call the tool. This prevents a perfect score but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required parameter app_id, so the description must compensate. It does not mention app_id at all, leaving ambiguity about what the identifier refers to (e.g., which federation or app context). The schema only provides a vague title ('App Id'), so the agent lacks essential information to correctly set this parameter. The description adds no semantic value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List'), a precise resource ('operator-ratified downstream MCP server'), and details the exact fields returned (id, name, launch command/args, env var names, ratifier, date). It also explicitly states what it never includes, distinguishing it from federation_discover and other listing tools. This gives an agent a clear, unambiguous understanding of the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts itself with federation_discover by stating that unratified servers are never included and that connecting requires ratification first, with a direct pointer to the alternative. This gives the agent a clear rule for when to use this tool versus the sibling, leaving no room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (destructiveHint: true, readOnlyHint: false) already flag this as a mutating operation. The description adds significant nuance beyond annotations by specifying exactly what is mutated and how: 'fork record is kept,' 'entries are tallied as archived,' and the reason is recorded. The explicit disambiguation 'it does not erase' directly manages agent expectations about destructive operations. The 'Irreversible' warning reinforces the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, 51 words total. The description is extremely tight: it names the action, clarifies the lifecycle semantics, and adds a warning — all without a single filler word. The most critical behavioral caveat ('it does not erase') is parenthesized and emphasized without being buried. This is exactly the kind of front-loaded, information-dense structure that helps an agent parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, irreversible op, the description covers the core context well: what it does, what persists, and what happens to related dataset entries. It misses a few edge-case details an agent might need, such as: what happens if the fork is already closed? What if there are no entries to archive? And it doesn't mention error cases or idempotency. Still, given the guidance provided and the lack of an output schema requirement, it covers the main decision points for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only place to clarify parameter semantics. The description does explain that `reason` 'records why' the fork was abandoned — a meaningful semantic that explains its purpose. However, it provides no additional info on app_id or fork_id beyond their names, and there is no note on how to obtain or validate these identifiers (e.g., via fork_list or fork_status). The meaning is partially inferable from context, which earns a baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description leads with a specific verb and resource: 'Close an open fork as DELETED'. It clearly separates this from a hard delete by noting 'this closes, it does not erase' and gives the operational context ('the work was abandoned'), distinguishing it from sibling tools like fork_merge. The first clause alone disambiguates the entire purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells you when to use it: when 'the work was abandoned,' and what to expect as a side effect: 'its atom/kb change-log entries are tallied as archived.' It mentions fork_merge but only to draw an analogy about irreversibility, not to give explicit routing guidance (e.g., 'use fork_merge if you want to keep changes'). The context is clear, but it stops short of explicitly contrasting scenarios with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say the operation is not read-only and not destructive. The description adds important behavior: entries can never be edited or deleted, the entry is hash-chained onto the previous one, and the return shape is {id, project, event_type}. This goes 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with zero filler. The key behavior and return format are stated immediately, and the warning about append-only is directly actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description correctly includes the return shape. The core mechanics and irreversibility are covered, but app_id semantics and potential error/confirmation behavior are absent. Slightly incomplete for a 4-required-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must carry parameter meaning. It explains that project, event_type, and content compose the event, but it never mentions app_id, what values are valid, or how content should be structured beyond being an object. Partial compensation, with a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description states the specific verb 'Append' and the resource 'shared FRANK governance ledger', with a concrete payload shape. It clearly distinguishes this write tool from sibling read/verify tools like frank_read and frank_verify by emphasizing append-only semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: append-only ledger, so agents should write settled facts and not drafts. It doesn't explicitly name alternatives or spell out when-not-to-use, but the instruction is sufficient for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, and the description reinforces this by saying 'Read-only.' It adds valuable behavioral context beyond annotations: newest-first ordering, optional project filtering, per-entry prev_hash/hash links, and the limit range 1–500. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, ordering and filter, hash-link behavior with a routing pointer, limit constraint, and read-only confirmation. The description is front-loaded with the core action and remains scannable without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with annotations covering safety, the description is largely complete: it sets return expectations by mentioning per-entry hash links and newest-first ordering, and gives the limit constraint. The main gap is the unexplained required `app_id`, which prevents full self-contained completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains two of the three parameters: `project` enables optional filtering and `limit` must be 1–500. However, the required `app_id` parameter is entirely unexplained in both the schema and description, leaving an important semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Read recent entries from the FRANK governance ledger' — the fleet's hash-chained, Postgres-backed audit chain. It also differentiates from siblings by mentioning that frank_verify should be used for integrity checks, making the purpose crisp and non-confusable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes the agent to frank_verify when checking chain integrity rather than inspecting hashes manually. It implies this is for reading, not writing, but does not explicitly say 'use frank_append for writes,' so it has clear context without full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint and non-destructive behavior, but the description adds meaningful behavior: non-blocking execution, an explicit dependency on grove_read, and the filtering behavior that only channels with new messages appear. These are all beyond what annotations and schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: a one-sentence purpose, one prerequisite line, an Args section with an example, and a concise return explanation. Every line earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description properly defines the exact return shape and filtering behavior, making the tool callable. The only gap is the unexplained optional app_id parameter, which is acceptable since it has a default and is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
cursors is well explained with a concrete example mapping channel names to since_id values. However, schema description coverage is 0% and app_id is not mentioned in the description, leaving optional parameter semantics entirely to the schema default. The core parameter is handled well, but not all params are compensated for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: checking multiple channels at once for new messages. It clearly distinguishes itself from sibling grove_watch, which is the single-channel variant, and the non-blocking note further sets its behavior apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use it — batch-checking multiple channels — and explicitly states the prerequisite 'Requires grove_read.' It does not explicitly name grove_watch as the single-channel alternative or list exclusions, which keeps this from being a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses specific behavioral traits: it 'blocks private, loopback and other non-public destinations' with name resolution, re-checks every redirect hop (not just the first), and returns the redirect chain in `redirects`. It also notes the 'sandwich defense' when wrap=True and the required permissions. These go well beyond the annotations (readOnly, openWorld, non-destructive), which are minimal, and provide valuable operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence conveys important information: purpose, alternative, security behavior, redirect handling, discovery advice, and requirements. It is front-loaded with the main action and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, security restrictions, redirect behavior, required permissions, and a hint about return content (text with sandwich defense, redirects). It does not explain error handling or behavior when max_bytes is exceeded, but given the lack of an output schema, the description is fairly complete. A small gap remains regarding app_id and max_bytes semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain all parameters. It explains `wrap` (sandwich defense) and implies `url` ('Fetch a URL'), but it does not explain `app_id` or `max_bytes`. Given zero schema coverage, the description fails to compensate for two of the four parameters, leaving the agent to guess their purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'URL', and explicitly distinguishes it from 'native WebFetch' and from 'willow_web_search' (which is for discovering URLs). This gives an agent a precise understanding of what the tool does and how it differs from closely related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use willow_web_search to discover URLs first', providing a direct when-to-use instruction. It also states 'not native WebFetch', pointing to an alternative. This is clear guidance on when to call this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is rich in behavioral context beyond the sparse annotations. It discloses that nothing is deleted (states-not-deletions), the event body/notes/location are read to derive the fact then dropped (receipt-not-recording), and omitted `events` results in `transport_unwired` rather than fabricated data. It also clarifies that the calendar is never written back. The annotations only set readOnlyHint=false, destructiveHint=false, which agrees with this description—no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence carries essential operational and behavioral information. It is front-loaded with the primary purpose, then expands into state semantics, data handling, and edge cases. The structure moves logically from what the tool does to how parameters behave to what it won't do—no filler or redundancy. Despite its length, it is appropriately detailed for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must explain what the tool returns. It mentions `transport_unwired` for the unwired pull case, but it does not describe the normal success return (e.g., a confirmation, a list of created commitments, or an acknowledgment). It also leaves `app_id` undefined. For a tool that persists data, the absence of a return contract is a notable gap, and the parameter description is incomplete (~50% coverage).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only types and defaults; description coverage is 0%. The description compensates by fully explaining the `events` parameter: a list of {uid, title, start, end?, attendees?, body?, cancelled?} with ISO-8601 start/end, and the semantics of omitting it. However, `app_id` (required) is not explained at all. While `app_id` may be self-evident from context, the lack of any description for a required parameter is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb-resource pair: 'Ingest calendar events into the operator's commitment ledger and persist the result.' It goes on to specify the persistence target (SOIL collection `willow/commitments`), the state machine (ACTIVE/WITHDRAWN), and the invariant that nothing is deleted. This makes the tool's purpose unambiguous and clearly distinguishes it from read-only or deletion-oriented siblings like `commitment_list` or `store_delete`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use and when-not-to-use guidance: it explains that omitting `events` triggers a pull from the live calendar source but warns this transport is a home-box step and will return `transport_unwired` instead of inventing data. It also explicitly states that the tool never writes the calendar back and that cancel/reschedule proposals go through the SAFE gate, which is not exposed over MCP. While it doesn't name alternative tools explicitly, it sets clear boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly=false, openWorld=false, destructive=false. The description explains a write operation that refuses atoms without citations, stores relationships as edges, and has special handling for corrections and subject_id (guardian-consent seam). It adds substantial context beyond annotations about refusal behavior, edge persistence, and the high bar of person_inference claims. No contradictions. Slight deduction because it could be more explicit about immutability or side effects on linked atoms (e.g., 'supersedes' makes old ones non-current), but that's mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately detailed, with paragraph breaks separating the core atom definition, edge semantics, and subject_id seam. The requiredness of rationale/evidence is front-loaded after the metaphor. Although long (over 200 words), it's structured and every block adds necessary context. No fluff—the 'story of this willow' metaphor is a nice touch but doesn't obscure meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 params, 0% schema coverage, and no output schema, the description does a strong job covering the non-obvious parameters and behavioral rules. It addresses edge direction, refusal, scope confinement, and consent seam—highly non-trivial aspects. It doesn't explain return values or errors, but with no output schema that's not expected. It also doesn't mention how to form the evidence references (PR/commit/file/session) but lists valid types inline. Answering 'what happens on failure' could be added, but overall it's quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description carries full burden. It explains rationale (WHY required), evidence (at least one citation required), and all three edge parameters (supersedes, derived_from, motivated_by) with specific meanings and directionality. subject_id is described in detail as the guardian-consent seam. Other params like id, title, app_id, origin, authority, tags are self-explanatory from names but description doesn't elaborate on origin/authority tags—this is a minor shortfall since they might need disambiguation. However, given the complexity, the description covers the critical semantic parameters well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool records a provenance atom containing WHY and evidence, and explains what the atom answers (origin, reason, prior state). It uses specific verbs and resources (record, provenance atom, lineage_edges) and distinguishes itself from sibling lineage tools (lineage_link, lineage_why, lineage_list) by defining its role as creating atoms with required rationale/evidence, versus linking or querying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does 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 record the story of an entity, answering where/why/before) and conditions: rationale and evidence are required, direction in edges is queried not stored twice, corrections re-record same id, confined to store_scope. It also gives examples of edge types (supersedes, derived_from, motivated_by) and clarifies semantics for each. However, it doesn't explicitly name sibling tools as alternatives, but the guidance is clear enough to select this over lineage_link/lineage_why/lineage_list—though it doesn't directly state 'use lineage_link for x instead'. Minor gap, but the when/why context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses the exact return shape, including metadata fields (_id/_created/_updated/_deviation/_action), the not_found behavior for absent or soft-deleted records, and the store_scope confinement. This goes well beyond the basic readOnlyHint and gives an agent a reliable model of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core behavior, and includes only high-value details: return format, error behavior, read-only nature, and scope. No word is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately covers return values, metadata, and error cases. With three required parameters and no schema descriptions, the description provides enough semantic context for an agent to invoke the tool correctly. It is complete for a simple single-record read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It does clarify that record_id is the exact ID, collection is a SOIL collection, and app_id relates to store_scope, but it does not fully explain each parameter's format or origin. The compensation is partial, not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Read one record'), a specific resource ('a SOIL collection'), and a specific lookup mode ('by its exact ID'). This clearly distinguishes store_get from sibling tools like store_search or store_list, which cover broader retrieval patterns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended usage context clear: use it when you have an exact record ID and need a single record, not a search or listing. It does not explicitly name alternatives or exclusion conditions, but the 'exact ID' phrasing and read-only scope provide strong contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and destructiveHint annotations, it explains the exact tokenization behavior, AND logic, substring matching, pagination via cursor, and the empty-query result. This provides substantial behavioral clarity an agent needs to reason about the call and 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured. It front-loads the core purpose, then explains matching semantics, pagination, edge-case behavior, and safety in four efficient sentences with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description still specifies the return shape and pagination contract. Complex behaviors such as token matching and cursor round-tripping are fully disclosed, and required context like collection scope is explained. The agent has enough information to invoke the tool and interpret the response correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the weight for parameter semantics. It thoroughly explains query semantics and cursor pagination, but it does not explain app_id, collection, or limit beyond what their names suggest. This is strong compensation but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: full-text search on exactly one SOIL collection. It distinguishes itself from broad/global search tools by emphasizing 'one' collection, which differentiates it from the sibling store_search_all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use it for full-text search within a single collection, and notes it is read-only and confined to store_scope. However, it does not explicitly mention alternative tools like store_search_all or store_get, nor 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.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by explicitly disclosing overwrite behavior, expiration semantics, per-identity scoping, and the SOIL storage backend. This provides genuine behavioral transparency. It does not contradict the annotations: idempotentHint=true aligns with 'Overwrites an existing key', and readOnlyHint=false aligns with the mutation action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, each earning its place. The core action is front-loaded, then the critical overwrite and expiry behaviors, then scoping and backend details. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description does not explain return values, but for a simple save operation this is a minor gap. It adequately covers storage backend, scoping, expiry, and overwrite behavior. It could mention how to retrieve the saved state, but context_get is a sibling and reasonably obvious.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the explanatory burden. It adds semantics for `key` (the storage key), `ttl_seconds` ('0 = never'), and `app_id` (scoping context). `value` is only implied as 'working state', which is adequate but could be more explicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Save ephemeral working state under `key`'. It also distinguishes this tool from sibling storage tools by noting 'Per-identity — scoped to your app_id' and 'Backed by the SOIL store', making its role among context_* and store_* siblings clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly communicates the use case: saving ephemeral, per-identity working state with optional expiry. The note 'no Postgres is required' provides useful placement guidance. However, it does not explicitly name alternatives like context_get or context_expire, nor state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known safe. The description surpasses the annotation burden by disclosing: it reveals only the caller's own config (privacy boundary), it never touches fleet rows or vault secrets (so no exfiltration risk despite appearing as a diagnostic), it asserts severity rather than assuming it (naming the fleet via env vars makes shared surfaces 'named problems', naming none results in 'not_asserted' and changes nothing), and it returns a verdict with named problems and fixes. This is rich behavioral context beyond the annotations — the severity-assertion nuance in particular prevents an agent from misreading the tool's effect on other systems. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph (plus a second paragraph on severity) — it front-loads the core verdict and the list of checked surfaces, which is the highest-value content. Every sentence earns its place, there's no fluff, and the key differentiators (ungated, own-config-only) are placed prominently. It's not maximally concise (the second paragraph is a nuance that could arguably be trimmed), but it is efficiently structured and information-dense without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a multi-surface diagnostic) and the absence of an output schema to document the return value, the description carries the full burden. It covers what it checks (the elastic list), what it returns (verdict with named problems + fixes), its gating behavior (ungated), its privacy boundary (own config only), and the severity-assertion variant behavior. There is no output schema and no requirement to explain return values, but the description does explain the verdict shape — which is exactly what an agent needs to interpret the result. The only thin area is the app_id parameter semantics over the default, but the overall coverage is strong for a tool of this scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% — the schema only has app_id (string, optional, default ''). The description adds meaning by explaining how identity bindings and app_id's manifest fit into the check ('your app_id's manifest + resolved permissions' and 'identity bindings'). It doesn't explicitly explain the semantics of 'app_id' as a filter or override, but the optional nature (default '') and the phrase 'your app_id' convey that this is the identity being diagnosed. The description compensates well for the 0% coverage by telling the agent what the app_id relates to, though it could be sharper about whether app_id can be empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a precise diagnostic verb ('self-check'), the resource (the willow-mcp install), and then enumerates exact system surfaces it inspects (SOIL store, Postgres, schema mapping, manifest, identity bindings, queue, egress lease, fleet wiring). This is far more specific than the tool name 'diagnostic_summary' alone. It also carefully disambiguates: it reveals only the caller's own config, never fleet rows or vault secrets, which distinguishes it from fleet-level status tools like 'fleet_status' or 'grove_fleet_status'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the tool is 'ungated on purpose: it must answer even when your manifest or database is misconfigured' — that's a strong when-to-use statement (run it when you suspect broken wiring). The final paragraph adds depth about fleet severance assertion, explaining how to control behavior via env vars and what happens when you name none ('not_asserted'). What is missing is an explicit 'when NOT to use this in favor of sibling X' — instead it relies on being the natural diagnostic tool among siblings, and there's no direct sibling (like env_check or fleet_health) that it routes away from. Still, the guidance for when to use it is above-average.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses all side effects: it verifies and then appends a citation. It explicitly states that for dispatch verbs it does NOT write a citation and returns cited_before_act=False with a note. It explains refusal behavior (returns reason if missing/expired/out of scope). This far exceeds what annotations provide (annotations only indicate non-read-only, non-destructive) and adds crucial nuance about the double-charging issue.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy and contains a dense technical note about double-charging. While the main purpose is front-loaded in the first sentence, the #333 note is a large block of text that could be structured more clearly (e.g., bullet points). It is not overly verbose for the complexity, but it is not concise; a structured breakdown would improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main functionality, the special handling for dispatch verbs, and failure behavior. It hints at the return structure (cited_before_act, note) but does not fully specify the output format or all possible error types. For a tool with no output schema, this is a reasonable level of detail; it provides enough to call the tool correctly, though a return format specification would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the roles of envelope_id, verb, call_args, project, and session (they are used for verification and citation recording). However, app_id is not explained at all, and call_args is only vaguely described as 'given call_args' without structure. While most parameters are given meaning, the gap on app_id prevents a higher score; a 4 is appropriate given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it checks an authority envelope before acting, verifies the envelope covers the verb and arguments, and appends a citation to the FRANK ledger. It also introduces the advisory-only distinction for certain verbs, which separates it from generic append tools like frank_append. The verb+resource is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use the tool: 'BEFORE acting under it.' It clearly explains the exceptional case for VERB_LEVEL_ENFORCED_VERBS (dispatch) where the tool becomes advisory-only and cites are handled by dispatch_send, preventing double-charging. This gives strong guidance on when to rely on it and when not to, including practical use for preflight checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say destructiveHint=true, but the description adds crucial nuance: it is a soft-delete/archive (deleted=1), retains purged gaps, leaves promoted gaps alone, returns a specific payload, and requires a distinct permission due to fleet-shared scope. This goes well beyond the structured hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense and every sentence earns its place: purpose, compared alternative, edge behavior, retention semantics, required confirmation, return shape, and permission warning. It is structured front-loaded with the most important decision-relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive, bulk, permission-gated tool with no output schema, the description is remarkably complete: it covers return shape, retention, exclusions, confirmation, and share-scope. The only notable gap is lack of clarity around app_id and what failure modes look like, but those are minor compared to the overall coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does explain the confirm parameter ('Pass confirm=<topic> to proceed') and implies topic is an exact match, but the role of app_id is never clarified. Given that the note says 'purges every app's gaps', the necessity and meaning of app_id is ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Soft-delete every gap under an exact topic in ONE call', giving a specific verb, resource, and scope. It also explicitly differentiates itself from gap_delete by mentioning bulk cleanup and the per-call rate limit, and clarifies that promoted gaps are left intact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly positions this as the bulk-cleanup alternative to gap_delete's per-call rate limit, mentions the confirm guardrail, and warns about fleet-shared scope and the special gap_purge permission. An agent can clearly determine when this tool is intended and what constraints apply.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) with no destructive or open-world flags. The description adds crucial behavioral context: it is a 'GOVERNANCE WRITE' that seals a 'signed, ledgered' pair, records the caller's app_id as verifier, and 'mints invocation power'—all of which are side effects richer than the annotations alone. It does not contradict any annotation and meaningfully explains the security implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a solid paragraph and covers a lot of ground, but the heavy use of stylized metaphor ('oracle,' 'mints invocation power') may reduce clarity. While every phrase carries some informational weight, the register is needlessly baroque for what is otherwise a security-sensitive operation. It could be more direct without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a governance write with security implications, the description covers the essential context: what it does, when to use it (and who should use it), the permission group, and a key behavioral effect (recording verifier identity). It does not describe the return value, but since there is no output schema and the operation's side effects are the focus, this is a minor gap rather than a critical omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description bears the full weight of explaining parameters. It links `surface` to 'natural-language', `tool` to 'willow verb', and `app_id` to the verifier role, which maps cleanly onto the three required parameters. It could go further with formats or examples, but the meaning is adequately conveyed given the simple string types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific verb and resource: "Teach the oracle: sanction that natural-language `surface` maps to willow verb `tool`." It is clearly distinguished from the related sibling nestor_tool_route, which is referenced as serving the sealed pairs, and from the implied queued-route counter-part, making the tool's role unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it: to seal a verified pair, and that it is 'meant for human/attested seats only,' with a specific permission group required. It also frames the tool as 'counter-verb to a queued route,' indirectly identifying when not to use it. Referencing nestor_tool_route provides a clear alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral detail beyond the annotations: it explains the soft-delete semantics (retained for audit/recovery), the return value contract (deleted: true|false), and the scoping constraint (store_scope). This is exactly what an agent needs to understand side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary action, and every sentence adds value. It covers the purpose, behavior, return value, and a constraint without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity mudand the annotations indicating destructiveHint, the description is nearly complete. It lacks explicit mention of error cases (e.g., permission errors) or concurrency, but for a straightforward delete operation, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It correctly references the record_id parameter and the store_scope, but does not elaborate on app_id or collection. However, the parameter names are self-explanatory, and the description provides enough context for the agent to use the tool correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool soft-deletes one record by ID, distinguishing it from hard deletion and from purge operations. It also mentions the effect on get/list/search, which is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes that hard removal is deliberately outside the tool surface, clarifying when NOT to use this tool. It also implies that for permanent deletion, operators should handle it, providing clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite the annotations providing three hints (non-readOnly, non-openWorld, non-destructive), the description adds substantial behavioral context: the exact error contract for unknown IDs, the return value shape, the mutation of updated_at, retention of audit metadata, and scope confinement. The description 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The entire contract is four sentences you could fit in the front half of one textual phrase: purpose, key constraint with error, deviation semantics, return value, and scope. Every sentence contributes new information and the formatting uses internal sentence length well to carry the precise semantics of the nested error case. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mild-mutating store tool, the description covers the essential ground: mutation semantics, error semantics, return value, and scope. Given there is no output schema and 0% schema coverage, the description does nearly all the lifting and does so well. It could add clarity about partial-vs-full record replacement semantics and what 'confined to your store_scope' means in practice for cross-scope agents, but this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the burden falls on the description. It explicitly explains the `deviation` parameter ('declares pattern-departure exactly as in store_put') and gives a clear model for `record` via 'Replace existing record's data'. However, app_id, collection, and record_id semantics are only implicitly captured through the main action sentence, and the nested `record` structure gets little detailed treatment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Replace an existing record's data in-place') with the precise scope of behavior: same ID, updated_at bumped, audit metadata retained. It explicitly contrasts with the create path ('use store_put to create'), distinguishing it from its closest sibling without any ambiguity. This is about as clear as it gets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent exactly when to use this tool and when not to: 'Never creates: an unknown ID returns {error: not_found} (use store_put to create)' — an explicit when-not-to plus the named alternative. It also injects the operational constraint 'Confined to your store_scope'. This is explicit exclude-and-redirect guidance with no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses ordering (oldest first), output truncation (80 chars), pagination behavior (next_cursor), and a dependency (requires the fleet Postgres). This is valuable operational detail not present in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it starts with the core action and scope, then pagination, then usage guidance. No wasted words; all sentences carry operational value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers most critical aspects: what it returns (pending, next_cursor), pagination, a sibling alternative, and a dependency. However, the omission of the required 'app_id' semantics leaves a gap that could lead to misuse. No output schema exists, so the description should be more explicit about parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'agent' default and the cursor usage for pagination. However, it does not explain the required 'app_id' parameter (its role is unclear) nor the 'limit' parameter beyond its default. Since schema descriptions are absent (0% coverage), the description only partially compensates for this gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List tasks still waiting in the Kart queue') with a resource (Kart queue) and a scope (for one worker agent). It clearly differentiates from task_status by noting that it answers 'what is queued to run' and directing to task_status for full detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly indicates when to use this tool (to see queued tasks) and when to use the alternative (task_status for one task's full detail). It also mentions a prerequisite (requires the fleet Postgres), which helps the agent decide if it can use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description discloses the return value for both success and failure (expired: true/false) and states the scope limitation (cannot expire another app's context). This gives clear expectations for side effects and access control.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the primary action (delete). It efficiently communicates purpose, return behavior, and scope without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple destructive nature, the description covers all essential aspects: what it does, when to use it, return values, and permissions. It is sufficient for an agent to invoke the tool correctly without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only parameter names and types, but the description adds meaning by explaining that 'app_id' is the scope and 'key' identifies the context. It clarifies the relationship between the two parameters, partially compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a saved context immediately, ahead of any TTL. It distinguishes itself from context_get (read) and context_save (write) by explicitly focusing on deletion/expiration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use it (to delete a context before its natural expiration) and sets a constraint (scoped to your app_id). It does not explicitly list alternatives, but the phrase 'ahead of any TTL' and the existence of context_save/context_get provide sufficient context for use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations: it enumerates returned fields (meta including from/to app, role, phase, priority; full assignment.md body), documents both error modes (not_found, not_party_to_dispatch), and clarifies the permission model (membership in from_app/to_app/reply_to/orchestrator) with a reference to a bugfix issue. This is transparent and consistent with the readOnlyHint annotation; 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the core purpose first ('Read one dispatch packet by ID...'), then adds detail on content, read-only property, and error behavior. No fluff or redundancy; every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low schema coverage and no output schema, the description fully compensates: it describes the returned fields (meta with from/to app, role, phase, priority, plus assignment.md body), both error cases with exact error strings, and the permission model, even citing the issue context. There is nothing an agent needs to know to call this correctly that is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate for both app_id and dispatch_id. It does this implicitly: 'app_id' is contextualized via the permission description (from_app, to_app, reply_to, orchestrator) and 'dispatch_id' is the identifier for the packet to readaisl. The error codes also clarify parameter semantics. However, the description doesn't explicitly define each parameter or give format/type expectations beyond 'string', so it's strong but not perfect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly explains the tool reads a dispatch by ID and returns its metadata and body, positioning it as the read-before-accept step ('how a specialist sees its brief'), which implies when to use it relative to dispatch_accept. It does not explicitly name alternatives to avoid, but the context and the error case (not a party to the dispatch) effectively define its intended scope. Loses one point for not naming when-not-to-use versus other read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (all hints false), so the description carries the full burden. It discloses the unlocking side-effect, the preview dry-run behavior, the return of a sample row, the overrides mechanism, and the pitfall of name-matching columns holding wrong data. This goes far beyond annotations and is extremely transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the core purpose, then covers overrides and preview with clear structure. It is efficient with no fluff, but it is lengthy due to the rich detail. It earns a high score for focus, though a slight reorganization could improve scannability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a consequential side-effect and a potentially confusing mapping scenario, the description covers everything an agent needs: purpose, workflow, parameter semantics, side-effects, and a concrete example of failure it guards against. There is no output schema, but the description sufficiently describes the sample output. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It does: 'overrides' is explained with concrete examples (e.g., {"source": "origin_ref"} and {"tags": null} for unmapped), and 'preview' behavior is fully specified with default and effect. 'app_id' and 'table' are self-evident from names. The description compensates fully for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('confirm') and resource ('table's schema mapping'), immediately clarifies the consequence (unlocking write tools), and names concrete affected tools. It also distinguishes itself from knowledge_write by explaining the gating. This is specific and distinguishable from any sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: when to use preview (dry-run) vs confirm (default), and explicitly advises reviewing the sample first. It also notes the act is more consequential than a single write, implying caution. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) indicate a state-changing but non-destructive operation. The description discloses that binding a session logs the tier on subsequent calls (`bind_observed`) and may enforce per-call signatures with `WILLOW_MCP_ENFORCE_BINDING`. It also details that secret registration/rotation is operator/CLI-only. This adds significant behavioral context beyond the annotations, covering side effects, dependencies, and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: the first sentence states purpose and core requirements, the second explains consequences and environment dependencies, the third clarifies operator-only secret management. Each sentence earns its place, and the most critical information is front-loaded. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of this complexity (HMAC signing, trust ceilings, enforcement mode), the description covers all essential aspects: purpose, prerequisites, return values (session_id, agent_id, trust_level, tier or error), side effects on subsequent calls, and external dependencies. The lack of an output schema is compensated by explicit return descriptions. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides meaningful semantics for both parameters. For `header`, it specifies a 13-field HMAC-signed object with `agent_id` matching `app_id`, and explains the trust_level capping. `app_id` is implicitly understood as the identifier used in the header. Given 0% schema description coverage, this is a substantial addition, though it does not enumerate every field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Open a cryptographically-bound session (check-in).' It specifies the resource (session), the action (open/bind), and the key condition (cryptographically-bound). It differentiates itself from sibling session tools by emphasizing the required HMAC-signed header and trust-level capping, making it distinct from session_enter or session_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool: when a cryptographically-bound session is needed, with explicit prerequisites (13-field header, agent_id equals app_id, operator-registered secret). It explains the verification and ceiling mechanism, but does not explicitly name alternative tools or state when NOT to use it. This is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds rich behavioral context beyond the readOnlyHint and destructiveHint annotations. It details pagination behavior (returning {items, next_cursor}, cursor null on last page), ordering (oldest first), and scope confinement ('confined to your store_scope'). This goes well beyond the annotations, which only indicate it's read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but information-dense. It leads with the core purpose, then covers pagination mechanics, parameter details, and alternative routing in a logical flow. No extraneous sentences; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list operation, 4 params, no output schema), the description covers all essential aspects: what it returns, how pagination works, how to use params, and which alternatives exist. There's no ambiguity about invocation or expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for the parameters. It does mention 'limit caps page size (default 50)' and explains the cursor usage, which gives meaning to two parameters. However, it doesn't elaborate on app_id or collection semantics beyond the schema, leaving them as implied. The baseline for low coverage is higher, but the description covers major parameters adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Return live records in one SOIL collection, oldest first, each with metadata.' It explicitly mentions the resource (collection), the operation (list), and key characteristics (live, oldest first, metadata), which distinguishes it from siblings like store_search (filtered results) and store_collections (discovery). No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use store_search for filtered results, store_collections to discover collection names,' providing direct alternatives. It also explains when to use pagination ('pass the returned next_cursor') and how limit works, giving clear context for when to call this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Exceptional, going far beyond the binary destructiveHint=true annotation. It discloses the mechanism ('records are retained (deleted=1) and stay recoverable'), the user-visible effect (records 'fall out of get/list/search'), and — crucially — the non-effects ('store.db is never removed', 'hard removal is an operator/filesystem act, deliberately outside the tool surface'). The confirm guard protocol and store_scope boundary are exactly the operational details an agent needs to safely invoke a bulk destructive call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Five dense sentences, front-loaded with the most important fact, each covering a distinct concern: what it does, how the soft-delete behaves, what it deliberately does not do, the safety guard, and the scope boundary. Zero filler — every clause climbs over the previous one's information gain.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive bulk operation with no output schema and no schema descriptions, this covers all the operational ground: recovery semantics, effects on queries, the confirmation protocol, non-destruction of the db file, and scope confinement. Nothing an agent needs to invoke or recognize the danger of this tool is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden — and largely compensates. It explains the non-obvious confirm parameter precisely ('pass confirm=<collection name> to proceed') and repeatedly clarifies the collection parameter's scope (whole collection at once, per-store_scope). app_id is never mentioned, so the compensation is strong but not complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb, resource, and scope: 'Soft-delete EVERY record in a collection at once.' It positions itself against a named sibling ('a bulk store_delete'), making the bulk-vs-single distinction unambiguous. The 'EVERY...at once' cardinality and explicit tie to the store's soft-delete model fully disambiguate it from every other store_* tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Names a concrete use case ('clearing out a whole collection (e.g. leftover test/scratch data)') and frames itself explicitly as the bulk variant of store_delete. What is missing is an explicit when-not-to-use routing such as 'for a single record, use store_delete instead' — the sibling differentiation is strongly implied but never spelled out as a decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-destructive; the description adds valuable behavioral context: collection auto-creation, overwrite on re-put, auto-generated IDs, deviation thresholds with resulting actions, return shape, and manifest scope. This exceeds the annotation baseline and is consistent with them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description front-loads the core action and then packs essential behavioral details into a compact, well-structured paragraph. Every clause adds necessary information with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description provides the return shape, side effects, parameter semantics, and scope restrictions. An agent has everything needed to invoke store_put correctly, including edge behavior around overwriting and deviation thresholds.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does for the most nuanced parameters: record_id (pin vs auto-generate) and deviation (with exact thresholds and meanings). app_id and record are less detailed, but their purpose is reasonably inferable from names and schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Write a JSON record') and resource ('named SOIL collection'), and the 'created on first write' detail clearly distinguishes it from sibling read/update/delete tools. The write semantics are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: use this to write records, pass record_id to overwrite, omit to auto-generate. It does not explicitly name store_update as an alternative, but the write-oriented semantics and overwrite rule make the correct selection obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though readOnlyHint=true is already in annotations, the description adds substantial behavioral context: whitespace-splitting, AND logic across tokens, the `limit` cap on returns, and the `domain` narrowing behavior. These details (especially the AND semantics) go well beyond what the annotations provide and meaningfully inform the caller about expected behavior. The description is consistent with 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description uses three sentences with no fluff: first stating the primary purpose, then behavioral details, and finally routing to the alternative. Each sentence earns its place and the most critical information (what and how) is front-loaded. The mention of 'fleet' and example domain values add necessary context without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool without an output schema or nested objects, the description covers the key aspects: what is searched (fleet Postgres knowledge base), how matching works (AND logic), the role of each parameter it mentions, and which sibling to use instead. The main gap is the undocumented `app_id` parameter and the complete absence of any note about the return format of the search results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden and does explain `domain` (narrows to one domain) and `limit` (returns up to that many). However, `app_id` is a required field that gets no mention at all, which is a gap since the agent must provide it. The query parameter is only implied by 'by content' rather than explicitly described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Search the fleet Postgres knowledge base by content') and distinguishes itself from sibling kb_at by explicitly directing users to 'use kb_at to fetch a known atom by ID'. It clearly identifies what makes this search different from simple ID lookup. This is not a restatement of the tool name but a genuine functional explanation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit alternative (kb_at for fetching by ID) and implies when this tool is appropriate (when searching by content rather than known ID). The 'Read-only; use kb_at to fetch a known atom by ID' sentence explicitly routes the agent based on use case. This gives clear guidance on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare destructiveHint=true, and the description enriches this by explaining the behavioral consequence: an override 'feeds the correction counter and, at threshold, opens a rule-delta flag.' This tells the agent this isn't just a file move; it's a learning signal. The 'MOVE' emphasis correctly flags the destructive/irreversible nature, adding value beyond the raw annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place. The first sentence gives the core operation and its parameter; the second explains the collision-detection semantic that an agent must know. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three simple parameters (two IDs and an optional override), the description fully covers what an agent needs: what it does, when to use the override, and what side effects occur. The lack of an output schema is fine since it's a pure action tool with no specified return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full burden. The description explains `override_dest`'s purpose and what happens when used, going beyond the schema's bare declaration. It implies what `app_id` and `item_id` are (identifiers of the staged item) by referring to 'a staged item' as the tool's resource.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('File') and resource ('a staged item'), and clearly explains it moves the file to its predicted track's destination or to the override path. It distinguishes itself from the sibling `nest_intake_skip` by framing this as the 'intake' action, but more importantly it explains the override mechanism in a way that makes the tool's role in the pipeline clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly explains when to use the `override_dest` parameter ('if you're correcting the classifier'), which tells the agent when this tool takes on a corrective role. It doesn't explicitly name an alternative tool, but the context implies this is the 'file now' action versus skipping or other intake operations. It could be slightly stronger by naming a specific sibling to compare against.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that subject_id is opaque and never written to the KB, dry_run is safe to inspect, and committed promotions are logged to a disclosure chain. This adds significant behavioral context beyond the annotations, which are sparse (only readOnlyHint, openWorldHint, destructiveHint).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately lengthy but each sentence adds value, explaining the data source, dry_run behavior, subject_id purpose, and logging. It could be slightly more concise by integrating the subject_id explanation more tightly, but it is well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully compensates for the lack of an output schema and low schema coverage. It covers the tool's behavior, parameters, edge cases (non-owner dumps, dry_run), and security considerations. For a tool with 4 parameters and no output schema, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must carry all parameter semantics. It explains skips_read resolves lifecycle issues, forest entangles when the read lands, and last_epoch is required to perform certain housekeeping. However, app_id and db_path are not explicitly described, which is a minor gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool promotes a Nest's structure into the knowledge base, specifying the source (bridge.build_bridge), what is promoted (structure-only atoms), and what is excluded (fragment content, filenames, person names). This distinguishes it from other tools like gap_promote and kb_promote by focusing on nest structure promotion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use dry_run=True vs False, and explains the subject_id parameter's purpose for non-owner life-dumps. It also names the underlying write tool (knowledge_ingest) and implies alternatives like kb_promote by specifying this is for nest structure only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description reveals the exact state mutation, the recording of session_id, and refusal conditions with error tokens wrong_recipient and invalid_transition. This gives the agent a clear behavioral model of what will and won't happen when the tool is called.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, each earning its place: the core action, the failure modes, and the surrounding workflow. The most decision-relevant information is front-loaded, and there is no redundant restating of the tool name or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an accept-operation with no output schema, the description covers the state change, error conditions, prerequisites, and next step. An agent has enough information to invoke it correctly and to recover from expected refusals.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It clarifies dispatch_id as the packet being accepted, app_id as the recipient that must match, and session_id as the value recorded against the packet. This is useful, though it stops short of explicitly mapping each parameter by name to its purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Accept a dispatch packet addressed to you' and precisely defines the effect: 'flips its status pending → working and records your session_id against it.' It is clearly distinguishable from sibling tools like dispatch_read, dispatch_list, and dispatch_send.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit workflow guidance: 'Read the brief with dispatch_read first; close out with handoff_write_v4 when the work is done.' It also states the prerequisite condition—use it only for packets addressed to you—and names the closing sibling, so an agent knows when and with what to pair this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint, openWorldHint, and destructiveHint, all of which the description aligns with. The description adds substantial behavioral detail: the `ok`/`hits` protocol, source status fields, `max_results` vs `total`, the per-collection `limit_per_source` behavior, and required runtime credentials. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every section earns its place: purpose, sibling distinction, response semantics, parameter caveats, and prerequisites. It is front-loaded with the most decision-relevant information and uses paragraph breaks to keep distinct concerns readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description compensates by describing the key result fields (`ok`, `hits`, `sources_queried`, `failed`, `skipped`, `timed_out`, `total`) and their meanings. It also covers required environments, the alternative tool, and parameter subtleties, making it complete for an agent to call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% field descriptions, so the description must carry the parameter documentation burden. It does well for `sources`, `max_results`, and `limit_per_source`, explaining cap semantics and fan-out behavior. However, `app_id` and `query` remain underexplained, and `query` is evident while `app_id` is not contextualized.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ~60 named institutional and academic collections' with concrete examples. It explicitly distinguishes itself from the sibling tool with 'use `willow_web_search` for the open web,' so an agent can disambiguate immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Use this when a claim needs backing; use `willow_web_search` for the open web.' It also explains when to narrow scope via `sources` and notes the required permissions, leaving little ambiguity about when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/willow-memory/willow-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server