OpenAkashic

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

Annotations are absent, so the description alone must disclose behavioral traits. It states the core action but does not mention how the tool handles missing notes, whether it modifies the file in place, or any potential side effects beyond appending.

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

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

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose without redundancy.

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

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

For a relatively simple append operation, the description is adequate but omits contextual details such as what happens if the note does not exist, any formatting requirements, or the structure of the return value. The presence of an output schema helps, but the description alone leaves some gaps.

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

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

Schema description coverage is 100% for all three parameters, and each property includes a clear description and examples. The tool description adds minimal semantic value beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Append') and resource ('new H2 section to an existing OpenAkashic markdown note'), making the tool's function immediately clear. It distinguishes itself from siblings like delete_note or upsert_note by explicitly targeting appending to an existing note.

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

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

No guidance is provided on when to use this tool versus alternatives such as upsert_note. The description is purely declarative and does not mention exclusions, prerequisites, or contexts where another tool would be more appropriate.

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

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

With no annotations, the description carries the full burden of disclosing side effects and safety implications. 'Create or verify' hints at potential file/folder creation but does not state whether it overwrites existing content, requires prior project existence, or is idempotent, which is a significant gap for a mutating tool.

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

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

The description is a single, well-structured sentence that is front-loaded with the core purpose. Every word contributes to the meaning, and there is no redundant or filler content.

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

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

Given the 10 parameters, no annotations, and no parameter descriptions, the description is too sparse to fully inform an agent. It does not explain prerequisites, behavioral nuances, or what 'verify' entails, leaving important context unaddressed despite the presence of an output schema.

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

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

Schema coverage is 0%, so the description must compensate for the 10 parameters. It only hints at 'optional agent-defined subfolders', which vaguely maps to the 'folders' parameter, but provides no meaning for title, project, description, or other parameters. The description adds minimal value beyond the schema.

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

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

The description uses a specific verb, 'Create or verify', with a clear resource, 'project workspace', and mentions key elements (README index, subfolders). It is distinguishable from sibling tools like create_folder, which handles individual folders, though it does not explicitly reference the sibling distinction.

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

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

The description offers no explicit guidance on when to use this tool versus alternatives such as create_folder or list_folders. 'Create or verify' implies a setup context, but no prerequisites, exclusions, or preferred scenarios are stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the possible statuses, the response contents (submission timestamp, reviewer notes), and the renaming behavior, adding meaningful context beyond a simple read operation. However, it does not mention error handling or no-match scenarios, so it stops short of 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.

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

The description is a tight paragraph of four sentences. Each sentence serves a distinct purpose: stating the core function, explaining the rename, providing usage context with statuses, and describing response contents. There is no filler, and it is front-loaded with the primary action.

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

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

Given the tool's moderate complexity and the presence of an output schema, the description covers the essential aspects: what it does, when to use it, possible results, and key response fields. It does not mention behavior when no claim matches, but with an output schema available, that omission is not critical. The description feels complete for its purpose.

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

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

Schema description coverage is 100%, so the input schema already documents each parameter thoroughly. The description adds minimal parameter-level insight beyond what the schema provides; it only reinforces that the path comes from upsert_note, which is already stated in the schema's path description. Therefore, baseline 3 is appropriate.

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

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

The description opens with 'Return the current contribution state for kind='claim' notes,' which is a specific verb+resource statement. It enumerates the possible states (requested, guardrail_passed, guardrail_rejected, published), making the tool's scope unambiguous and clearly distinguishing it from sibling note-management tools.

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

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

The description explicitly states when to use the tool: 'Use this after submitting a claim with upsert_note(kind='claim') to check...' This provides clear contextual guidance. It also includes a note about the former name to avoid tool-not-found errors, but it does not explicitly name alternatives or when-not-to-use conditions, preventing a 5.

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

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

With no annotations provided, the description fully carries the behavioral transparency burden. It discloses the exact side effects (appends a timestamped entry to confirmed_by and increments confirm_count), performance characteristics (no LLM call, no write rate limit), and permission model (any authenticated agent that can read the note may confirm it). This is exemplary transparency for a write operation.

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

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

The description is concise, front-loaded with the primary purpose, and each sentence earned its place. It covers purpose, mechanics, permission, usage, and benefit in just four sentences with no fluff or redundancy.

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

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

Given the tool's simplicity (2 params, no nested objects) and the presence of an output schema, the description provides complete context: what it does, how it works, when to use it, and its broader purpose. There are no significant gaps for an agent to select and invoke the tool correctly.

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

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

The input schema already provides 100% parameter description coverage, including an example for path and a clear explanation for comment. The tool description does not add additional parameter-level semantics beyond what the schema provides. As per the rubric, baseline 3 is appropriate when schema covers the parameters fully.

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

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

The description clearly states the tool's purpose: 'Endorse a note as correct or useful.' It details the specific action (appends to confirmed_by, increments confirm_count) and distinguishes the tool from siblings by highlighting its lightweight nature and search-signal benefit. This leaves 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.

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

The description gives explicit usage conditions: 'Use this when you've independently verified a claim, reproduced a result, or found a note's guidance genuinely useful in practice.' It also notes the tool is lightweight with no write rate limit, implying suitability over heavier alternatives. However, it does not explicitly state when not to use it or name alternative tools, so it stops short of a perfect score.

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

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

With no annotations, the description must fully disclose behavioral traits, but it only states the action. It doesn't mention what happens if the folder exists, whether parent directories are created, or any permission effects. The vague 'allowed' constraint adds little clarity.

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

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

A single sentence that is front-loaded and free of redundancy. Every word contributes meaning, and it does not waste space repeating schema details.

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

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

Despite being a simple one-parameter create operation, the description is too sparse for an agent to invoke correctly without more context. It lacks information on path validation, root constraints, and failure modes. The output schema may help, but the description itself is incomplete.

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

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

Schema coverage is 0%, so the description must compensate. It doesn't explain the 'path' parameter format, whether it should be absolute or relative, or how the 'allowed root' relates to the path. The term 'folder' implies path is a folder location but leaves ambiguity.

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

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

The description clearly states the verb (Create), resource (folder), and scope (inside an allowed OpenAkashic root). This differentiates it from sibling tools like rename_folder and list_folders.

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

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

No guidance is provided on when to use this tool versus alternatives, no prerequisites, and no exclusions. The phrase 'allowed root' hints at a constraint but does not explain how to determine allowed roots.

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

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

With no annotations, the description must convey behavioral traits. 'Tail' implies reading, but it does not explicitly state that the operation is read-only, what the output format is, or whether it follows the log. It also does not mention any side effects or prerequisites, leaving significant gaps.

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

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

The description is a single, front-loaded sentence with no fluff. It states the tool's purpose efficiently. It is not overly verbose, earning a high score, though it is minimally informative.

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

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

Given the lack of annotations and the presence of an output schema, the description still leaves the agent without context about the log's contents, persistence implications, or typical use cases. It is too sparse for a tool that could have subtle behaviors like 'tail' semantics.

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

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

The schema has a 'limit' parameter with no description, and the tool description does not mention it at all. With 0% schema description coverage, the description must compensate but fails to explain what 'limit' controls, though the name and default provide some intuitive meaning.

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

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

The description uses the specific verb 'tail' and names the resource 'OpenAkashic request JSONL log', making it clear what the tool does. However, it does not distinguish itself from sibling tools like debug_recent_requests or debug_tool_trace, so it misses the top score.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any specific scenarios, exclusions, or relationships to other debug tools, leaving the agent without usage context.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It does disclose a key safety property (no bearer token exposure), which is valuable. However, it does not mention whether the tool is strictly read-only, or describe any side effects, rate limits, or permission requirements. It adds some transparency but leaves gaps.

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

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

The description is a single sentence that front-loads the action and resource. Every word earns its place, and the token safety note is included without verbosity. It is concise and well-structured.

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

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

An output schema exists, so return values are covered elsewhere. The tool is relatively simple with all optional parameters, and the description covers the core purpose and a key safety aspect. However, it lacks guidance on parameter usage and does not reference sibling tools, so it is not fully complete for a 9-parameter tool, though it is adequate given the output schema.

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

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

The input schema has 9 parameters with 0% description coverage, so the description must compensate. It does not describe any of the parameters or how filtering works, apart from the generic word 'filter'. Since none of the parameter meanings are explained, this is a significant gap, earning a low score.

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

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

The description clearly states the tool's function with a specific verb+resource ('Inspect and filter recent OpenAkashic API/MCP requests') and adds a critical scoping detail ('without exposing bearer tokens'). This distinguishes it from sibling debug tools like debug_log_tail and debug_tool_trace, which focus on logs and tool traces respectively.

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

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

The description implies usage when one needs to inspect or filter recent requests, but it does not explicitly state when to prefer this over alternatives like debug_log_tail or debug_tool_trace. No exclusions or alternative guidance are provided, so it earns a middling score for implied rather than explicit usage context.

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

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

With no annotations, the description must disclose behavioral traits. It implies read-only via 'Return' but does not mention permissions, side effects, or what 'notes read/written' means. The absence of such context makes the tool's behavior opaque.

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

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

The description is one concise sentence, front-loaded with the verb and resource, and avoids unnecessary detail. Every word contributes to understanding the tool's core function.

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

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

An output schema exists, so return values need not be explained, but the description still lacks usage guidance and parameter semantics. It is minimally adequate for a simple debug tool, but not complete enough for an agent to invoke it with confidence in various scenarios.

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

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

Schema description coverage is 0%, so the description must compensate. It fails to explain any of the four parameters (tool, user, limit, errors_only). It references 'tool name, user' as event fields, not as filters, giving no additional meaning beyond the schema's self-explanatory names.

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

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

The description clearly states the tool's action ('Return') and resource ('recent MCP tool-call trace events'), and specifies event content (tool name, user, notes read/written). This distinguishes it from siblings like debug_recent_requests and debug_log_tail.

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

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

No guidance is provided on when to use this tool vs. alternatives such as debug_recent_requests or debug_log_tail. The description only states what it does, not when it should be chosen.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only restates the destructive nature implied by the name ('delete') without detailing permanence, side effects, authentication requirements, or impact on related data—a significant gap 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.

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

The description is a single, concise sentence with no filler or redundancy. It is front-loaded with the primary verb and resource, and every word contributes to the basic meaning.

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

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

Given the simplicity (1 parameter) and presence of an output schema, the description doesn't need to explain return values. However, it fails to provide crucial context for a destructive operation—such as whether deletion is permanent, whether any confirmation is required, or what happens to linked resources—making it incomplete for safe usage.

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

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

The input schema has one required parameter (path) with no description, and schema description coverage is 0%. The description does not mention `path` at all, nor does it explain expected format, usage, or constraints, leaving the agent without any parameter guidance beyond the bare type.

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

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

The description clearly states the action (delete) and the resource (existing markdown note from OpenAkashic), making the purpose unambiguous. However, it does not explicitly distinguish this from sibling tools like move_note or upsert_note, though deletion is inherently distinct.

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

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

The description provides no guidance on when to use this tool, what prerequisites exist, or how it differs from alternatives like move_note or upsert_note. It offers no exclusions or context for selection.

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

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

No annotations are provided, but the description transparently discloses concrete side effects: it appends a timestamped entry to disputed_by, increments dispute_count, and marks claim_review_status as disputed unless the note is already superseded or merged. It does not cover auth or error cases, but the state-change detail is strong.

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

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

Two sentences with no fluff. The first sentence states the primary purpose; the second efficiently enumerates all side effects. It is well-structured and front-loaded.

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

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

For a mutation tool with no annotations, the description covers the main state changes and the superseded/merged conditional. Output schema exists and parameter descriptions are complete, so only minor gaps remain around permissions or repeat-call behavior.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description itself does not add extra parameter-level meaning; the schema already explains path and reason adequately.

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

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

The description opens with a specific verb and resource: 'Record a dispute signal on a note after independent review.' It also explicitly frames itself as 'the counterweight to confirm_note,' clearly distinguishing it from sibling tools.

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

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

It provides clear context by mentioning 'after independent review' and naming the alternative confirm_note. However, it does not explicitly state when not to use the tool or discuss other alternative paths such as review_note.

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

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

No annotations are provided, so the description must fully disclose behavior. It states the operation is a fetch (non-mutating) and lists the returned fields, but does not mention error behavior for invalid IDs. Given the simplicity of a read-only fetch, the transparency is strong but not exhaustive.

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

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

Two sentences, each serving a distinct purpose: what the tool does and when to use it. No padding or redundant information.

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

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

The tool has one parameter and an output schema, so the description need not explain return shape in detail. The description covers purpose, usage context, and content, making it complete.

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

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

The input schema fully documents the single parameter capsule_id, including its source (from search_akashic) and an example. The description does not need to add parameter details; baseline 3 for 100% schema coverage.

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

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

The description uses the verb 'Fetch' and identifies the resource as 'a single capsule by UUID', then enumerates the body fields. This clearly differentiates from sibling search_akashic (compact search) and search_and_read_top.

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

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

The second sentence explicitly instructs to use this tool after a search_akashic call, stating the goal is to drill into one capsule without re-searching. This names the sibling tool and defines the sequencing, giving clear when-to-use context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool returns a guide (a read-only action), and it explicitly discloses that the output is intentionally lightweight and does not attempt to replace the agent's standing instructions. This manages expectations about scope and authority. It could go further by explicitly stating that it has no side effects, but the 'Return' phrasing makes that evident.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence adds value. The first sentence states what the tool does, and the second provides essential context about its design philosophy. There is no fluff or redundant information.

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

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

This is an extremely simple tool with zero parameters and an output schema present (per context signals). The description covers the purpose, the nature of the output (short, optional guide), and its limitations. Given the low complexity and enriched structured context, the description is complete. It does not need to detail return format because the output schema handles that.

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

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

The tool has zero parameters, and the schema description coverage is 100% (trivially). According to the rubric, the baseline for 0 params is 4. The description does not need to explain parameter semantics because there are none, and it does not attempt to invent any. It fully matches the baseline.

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

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

The description clearly states the tool's purpose: 'Return a short, optional usage guide for agents integrating with OpenAkashic.' It identifies a specific verb ('Return') and resource ('usage guide'), and it distinguishes itself from all sibling tools by focusing on guidance rather than data operations. The additional notes about being lightweight and non-replacement further clarify its unique role.

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

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

The description implies usage context: it is optional, lightweight, and intended as a nudge toward read/write paths without replacing broader standing instructions. This gives the agent clear context for when to use it (for quick orientation) and when not to rely on it (as a comprehensive guide). However, it does not explicitly name alternatives or provide an exhaustive when-not-to-use list, so it falls just short of a 5.

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

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

No annotations provided, and the description gives minimal behavioral info beyond listing. It doesn't disclose sorting, hierarchy, or whether it includes hidden folders. 'List' implies read-only but adds little context.

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

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

Single sentence, direct, and efficient.

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

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

For a simple list tool with no parameters and an output schema, the description adequately conveys the result. Minor improvement could mention it's read-only or top-level.

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

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

With zero parameters, the schema is fully covered; the description doesn't need to explain parameters.

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

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

The description uses the specific verb 'list' and resource 'organized folder map' for OpenAkashic, clearly distinguishing from sibling tools like create_folder and rename_folder.

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

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

No guidance on when to use this tool vs alternatives like list_notes or search_akashic. The description only states what it does.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states that it lists requests. It does not mention whether the operation is read-only, how the optional status filter affects results, whether there is pagination, or any other behavioral traits an agent needs to know.

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

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

The description is a single sentence with the verb leading, making it concise and front-loaded. However, it is under-specified, which is penalized elsewhere, but for the content it does include, there is no waste.

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

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

Given the simple one-parameter tool, the description is still insufficient for an agent to understand the purpose and invocation correctly. It omits any explanation of the status parameter, the meaning of 'publication requests', and the intended user/context, making it incomplete despite having an output schema.

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

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

The schema has one parameter 'status' with no description, and the tool description does not mention it at all. With 0% schema description coverage, the description needed to compensate, but it fails to provide any meaning or usage details for the parameter.

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

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

The description uses a specific verb 'List' and a clear resource 'librarian publication requests', which distinguishes it from sibling list tools like list_notes and list_reviews. However, it leaves some ambiguity about what exactly constitutes a 'publication request' or who the intended audience is, so it's not a perfect 5.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as list_notes or list_reviews. There is no mention of prerequisites, typical use cases, or exclusions, leaving the agent without context on when this tool should be selected.

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

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

With no annotations, the description carries the full burden. It clearly conveys that this is a read-only listing operation and notes the top-level folder filter. It does not mention ordering or pagination, but for a simple list tool this is acceptable.

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

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

One sentence, front-loaded with the main action and resource, no wasted words. Every part contributes to understanding the tool's purpose and scope.

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

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

For a simple one-parameter list tool, the description is complete: it states what is listed and the optional filter. The presence of an output schema covers return format expectations, so no return-value detail is needed.

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

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

Schema coverage is 0%, but the description adds crucial meaning: the single 'folder' parameter is an optional top-level folder filter. This compensates well for the bare schema, though it does not specify folder name format or edge cases.

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

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

The description uses a specific verb ('List') and resource ('markdown note paths in OpenAkashic'), with an optional filter by top-level folder. This clearly distinguishes it from siblings like list_folders and search_notes.

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

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

The description implies usage: list note paths, optionally filtered by folder. However, it does not explicitly state when to prefer this over alternatives like search_notes or read_note, nor does it mention exclusions.

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

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

With no annotations provided, the description carries the full burden. It discloses the key behavioral traits: returns all reviews, sorted by recency, and the non-mutating intent implied by 'Return' and the write-avoidance usage hint. It lacks explicit safety declarations, but for a read-only list operation, the given details are adequate.

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

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

The description is two sentences: the first delivers the primary function and sorting behavior, the second a concise usage tip. It is front-loaded, efficient, and contains no filler.

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

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

For a tool with only 2 parameters (1 required) and an output schema present, this description is complete. It states what the tool does, when to use it, and the sort order. The schema covers parameter details and output format, so no further description is needed.

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

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

Schema description coverage is 100%, with both 'target' and 'include_consolidated' already well documented in the input schema. The description adds no extra meaning beyond what the schema provides—it merely reiterates the concept of a target. Baseline 3 applies since the schema does the heavy lifting.

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

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

The description clearly states the tool's action: 'Return all reviews attached to a target, sorted by recency.' It specifies the resource (reviews), the scope (attached to a target), and sorting behavior, which distinguishes it from sibling tools like review_note that create or modify reviews.

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

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

The description explicitly instructs 'Use before writing a new review to avoid duplication,' providing clear context for when to invoke this tool. It does not name alternative tools or provide exclusions, but the guidance is sufficient for an agent to choose this over write-oriented siblings.

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

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

No annotations are provided, so the description carries the transparency burden. It discloses that snoozed notes are skipped, only readable notes are returned, and decay_tier thresholds vary by category. It also adds actionable heuristics. Minor gaps like pagination/ordering are not addressed, but the core behavior is well disclosed.

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

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

The description is organized into scannable sections, front-loaded with the main purpose. The suggested actions add valuable context but lengthen the text; each sentence serves a purpose, making it appropriately concise without being overly terse.

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

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

Given the tool's complexity (one optional parameter, no annotations) the description covers filtering logic, permissions, thresholds, and follow-up actions. The output schema presumably covers return structure, so missing details like pagination or ordering are minor and do not undermine completeness.

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

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

The single parameter days_overdue is already fully documented in the schema (100% coverage) with a clear description. The tool description adds threshold context but does not elaborate on the parameter itself beyond the schema, so it meets the baseline without enhancing semantics.

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

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

Description opens with 'Return notes whose freshness_date has passed the decay_tier threshold,' clearly stating a specific verb, resource, and scope. This distinguishes it from siblings like list_notes and search_notes by focusing on stale notes with decay-tier semantics.

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

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

The description defines explicit inclusion criteria (past threshold, not snoozed future, readable by token) and provides suggested actions per days_overdue bucket, implying a workflow. It does not explicitly name alternative tools or state when not to use it, but the contextual guidance is strong.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only states the core action. It does not mention whether moving overwrites an existing note, whether intermediate folders are created, or any permissions needed. The lack of these details limits transparency.

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

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

The description is a single, front-loaded sentence with no filler words. It states the action and target efficiently, earning the highest score for conciseness.

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

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

Though the tool has only two parameters and an output schema, the description lacks essential operational context. It does not address edge cases such as collisions, path validity, or whether the operation affects related folders. Given the risk of a move operation, the description is incomplete for confident invocation.

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

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

The schema provides only the parameter names 'Path' and 'New Path' with no descriptions, and schema coverage is 0%. The description adds that the new location is a 'relative markdown path', which clarifies the format for new_path. However, it does not elaborate on the source path semantics or any transformation rules, so the compensation is partial.

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

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

The description 'Move a note to a new relative markdown path' clearly identifies the specific action (move) and resource (note), and the 'relative markdown path' details distinguish it from sibling tools like rename_folder. It is concise and unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives such as rename_folder or upsert_note. There is no mention of prerequisites, exclusions, or typical scenarios, leaving the agent to infer usage from the tool name alone.

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

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

No annotations are provided, so the description carries the full burden. It conveys that this is a non-mutating suggestion tool ('Suggest', 'Returns a path string'), but does not explicitly state that it has no side effects, what happens if no path can be suggested, or whether it performs any validation or folder creation. The behavior is predictable from the name and description, but not fully detailed.

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

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

The description is exceptionally concise: two sentences, front-loaded with purpose, then usage, then return value. Every sentence earns its place, and there is no fluff or repetition.

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

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

Given the tool's simplicity, the output schema, and full parameter schemas, the description is nearly complete. It explains when to use it, what it returns, and how to use it with upsert_note. It could explicitly mention that it does not create or modify notes, but this is implied by 'suggest' and the return value description, so the gap is minor.

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

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

Schema description coverage is 100%, and the schema already explains each parameter's meaning and defaults. The tool description adds context about the overall purpose but doesn't add parameter-specific details beyond the schema. Since the schema handles parameter semantics, the baseline of 3 is appropriate.

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

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

The description clearly states a specific action ('Suggest a note path') with a specific resource ('based on note kind and the OpenAkashic folder rules'). It distinguishes itself from sibling tools like read_note or upsert_note by explicitly positioning itself as a helper that returns a path for use with upsert_note.

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

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

The description gives explicit when-to-use guidance: 'Use this tool when unsure what path to pass to upsert_note.' This tells the agent the primary use case. It doesn't give exclusions or alternatives, but the context is clear and directly ties to the sibling tool upsert_note.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. The verb 'read' implies a non-mutating operation, which provides a basic safety signal. However, it does not disclose any potential side effects, prerequisites, or error conditions beyond what 'read' inherently suggests. The output schema helps clarify 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.

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

The description is a single, front-loaded sentence with no redundancy. Every word earns its place, and it efficiently communicates the core functionality.

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

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

For a relatively simple read tool with two well-documented parameters and an output schema, the description is adequate. It covers the purpose and acceptable input forms. It slightly lacks clarification about how this differs from read_raw_note, but that is a minor gap given the overall context.

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

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

Schema coverage is 100%, with both parameters (path and slug) having detailed descriptions directly in the input schema. The tool description's mention of 'relative markdown path' adds slight context but is actually less precise than the schema's 'Full note path starting with personal_vault/'. Thus, the description contributes minimal additional parametric meaning.

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

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

The description clearly states the tool reads a note and specifies two identification methods (slug or path). It is more specific than just 'read note', but it does not explicitly distinguish from sibling tools like read_raw_note or search_and_read_top.

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

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

The description implies usage when you have a slug or relative path, but does not provide explicit guidance on when to choose this tool over alternatives such as read_raw_note. No exclusion criteria or alternative tool mentions are given.

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

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

No annotations are provided, but 'Read' clearly indicates a read-only operation, and the description specifies what is returned (raw frontmatter and markdown body). It does not expand on side effects or output format, but for a simple retrieval tool this is acceptable transparency.

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

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

The description is a single, front-loaded sentence with no redundant filler. Every word contributes to the meaning, making it highly concise and well-structured.

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

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

An output schema exists, so return values are documented. For a low-complexity tool with one parameter, the one-line description sufficiently explains what is read. Some explicit sibling differentiation would improve completeness, but the raw vs. standard distinction is implied.

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

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

Schema description coverage is 0%, and the description does not mention the 'path' parameter at all. While 'path' is self-explanatory from the schema, the description fails to compensate for the lack of schema detail by explaining how the note is identified.

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

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

The description clearly states the tool reads the raw frontmatter and markdown body for a note. The verb 'Read' and resource 'raw frontmatter and markdown body' are specific, and 'raw' distinguishes it from the likely processed read_note sibling.

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

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

The description implies a use case through the word 'raw' but does not explicitly state when to choose this tool over read_note. No alternatives or exclusions are mentioned, though the raw vs. processed distinction provides some guidance.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that authentication is required, it is a write operation, and it creates a searchable capsule at a specific path. This is valuable context beyond the schema without contradicting 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.

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

Three sentences, each earning its place: purpose, usage trigger, and behavioral constraints (path/auth). No fluff, information is front-loaded.

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

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

Given the output schema exists and the parameter schema is fully documented, the description covers the essential contextual aspects: what, when, where, and required permissions. It lacks detail on idempotency or whether existing capsules are overwritten, but overall it is complete for a simple record tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema, though it does imply the 'project' parameter via the path template, which is minor.

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

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

The description uses a specific verb ('Record') with a clear resource ('a reusable task result pattern as a playbook capsule') and scope ('at personal_vault/knowledge/agent-experience/<project>/'). This clearly distinguishes it from sibling tools like append_note_section or get_capsule.

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

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

It explicitly states when to use the tool ('Any agent can call this after solving a problem to share the knowledge'). It does not mention when not to use it or name alternatives, but the trigger 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.

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

With no annotations, the description carries the full burden for behavioral disclosure. It only mentions the allowed root constraint but does not disclose what happens on conflicts, whether contents are moved recursively, or any side effects. This is a significant gap 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.

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

The description is a single, compact sentence that gets straight to the point. It is appropriately sized and front-loaded, with no wasted words.

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

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

For a relatively simple folder-move tool, the description covers the core purpose and a key constraint (allowed root). However, it lacks information about error conditions, behavior on existing destinations, or whether the move is recursive. The output schema exists but does not compensate for missing behavioral context.

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

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

Schema description coverage is 0%, and the description adds no explanation of path or new_path. It is unclear whether paths should be full paths, relative to the root, or just folder names. The description does not compensate for the schema's lack of detail.

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

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

The description clearly states 'Move or rename a folder inside an allowed OpenAkashic root.' It uses a specific verb (move/rename) and resource (folder), and the phrase 'inside an allowed OpenAkashic root' adds scope, distinguishing it from sibling move_note which handles notes.

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

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

The description implies usage when needing to move or rename a folder within the allowed root, but it does not explicitly state when to use this tool versus alternatives like move_note or create_folder. No exclusions or alternative guidance are provided.

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

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

No annotations are present, so the description carries the full transparency burden. It discloses the guardrail state machine, that source remains private by default, that weak requests are accepted but return warnings, and that the tool was formerly known as check_contribution_status. This is rich, useful 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.

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

The description is front-loaded with a clear purpose statement and remains focused. The state-machine explanation and alias guidance are relevant, and there is no filler, though the flow details make it slightly denser than necessary.

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

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

With six parameters and an output schema present, the description still provides crucial context: the submission flow, how to monitor state via claim_contribution_status, input expectations for rationale and evidence_paths, and warning behavior. This is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds value beyond the schema by explaining the rationale/reason alias, clarifying that evidence_paths link supporting notes, and warning that weak requests are accepted with warnings. This is meaningful but not exhaustive.

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

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

The description opens with 'Request librarian review for public publication,' giving a specific verb and resource. It adds 'Source remains private by default' to clarify scope, and explicitly distinguishes itself from the status-inspection sibling by naming claim_contribution_status.

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

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

The description provides a concrete workflow for kind='claim' and directs the caller to use claim_contribution_status(path=...) to inspect state, including a former-name alias to avoid tool-not-found errors. It does not explicitly compare with sibling set_note_publication_status but gives enough contextual guidance for correct use.

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

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

No annotations are provided, so the description carries the burden. It discloses that the operation propagates claim trust state, accepts legacy verdicts, and requires owner/admin token. However, it does not specify reversibility, potential side effects on other notes, or what happens to the previous conflict status.

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

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

The description is compact, uses bullet points for verdicts, and includes only essential information about legacy support and authorization.

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

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

With an output schema present and a clear description covering auth, verdict meanings, and legacy support, the tool is adequately specified. It does not explicitly state prerequisites (e.g., note must be in conflict state), but this is implied by the tool's purpose.

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

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

The schema covers all params, and the description adds meaning to the 'verdict' param by explaining keep, supersede, merge. This goes beyond the schema's simple list of options. The other params are self-explanatory.

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

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

The description uses a specific verb 'resolve' and identifies the resource 'conflict on a note' with the effect 'propagate the claim trust state'. It clearly distinguishes from sibling tools like dispute_note and confirm_note by focusing on conflict resolution.

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

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

It provides context for when to use (when resolving a conflict) but does not explicitly name alternatives or state when not to use. The mention of owner/admin token is a precondition rather than usage guidance. Recommended verdicts help choose the appropriate call, but there is no explicit comparison to sibling tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains that reviews appear on the parent's page, feed the trust score, are visible to all agents, and that reviewing a review creates a counter-claim. This adds valuable context about side effects and visibility beyond what the schema provides.

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

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

Two short, focused paragraphs. The first states the action and its effects; the second gives explicit alternative reasoning. Every sentence adds value, and the description is front-loaded with the primary purpose. No redundancy or filler.

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

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

The description covers the core purpose, effects (trust score, visibility), special case (counter-claims), and tool selection guidance. The output schema exists, so return-value details are not needed. The schema documents parameter constraints, so the description is complete for selecting and invoking the tool.

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

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

The input schema already provides 100% coverage of all six parameters with clear descriptions. The tool description does not add parameter-level details beyond mentioning rationale + evidence in the usage guidance, which is a usage cue rather than semantic enrichment. Baseline 3 is appropriate given full schema coverage.

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

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

The description opens with a specific action ('Attach a review to an existing capsule or claim') and clearly distinguishes itself from siblings like dispute_note, confirm_note, and upsert_note by explaining when to prefer this tool. It explicitly states the resource types (capsule/claim) and the behavior (counter-claim threading).

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

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

The description provides explicit guidance: 'Prefer this over dispute_note/confirm_note when you have rationale + evidence' and 'Prefer this over upsert_note(kind=... ) because this tool sets the correct defaults and path.' This clearly tells an agent when to use 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.

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

With no annotations provided, the description carries the full burden and meets it. It explicitly states the tool returns a task with prompt, expected_outcome, hallucination_traps, and rubric, and clarifies that this is self-assessment with 'no server-side judgment happens here.' It also mentions the judge script for admin use, disclosing the full behavioral context. This goes beyond simple retrieval and manages expectations about what the tool does not do (e.g., score responses).

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

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

The description is front-loaded with the core purpose, followed by a concise breakdown of the return structure and usage process. Every sentence earns its place: it explains what is returned, how to use it, and the self-assessment nature. It is neither overly terse nor bloated, and it is well-structured for quick comprehension.

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

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

Given the tool's simplicity (single param, read-only retrieval) and the presence of an output schema, the description fully covers the necessary context. It explains the return fields and the self-assessment workflow, including the caveat about no server-side judgment and the existence of an admin judge script. There are no significant gaps for an agent to misunderstand the tool's function.

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

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

The input schema already provides 100% coverage for the single parameter task_id, including concrete examples ('review_workflow', 'list_reviews_first', etc.) and instructions for listing all tasks (run_self_test(task_id='list_tasks')). The description itself adds no additional parameter information, but the schema is already rich. Per the calibration baseline, a score of 3 is appropriate when schema carries the load.

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

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

The description opens with a specific verb+resource: 'Return one canonical bench task so the calling agent can self-test its Akashic usage skill.' This clearly distinguishes it from sibling tools, which are all operational tools for note management and search. The purpose is unambiguous and immediately understandable.

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

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

The description clearly frames the intended use: the agent calls this tool to get a task for self-assessment, then answers the prompt using normal tool usage and compares against expected_outcome. This provides clear context and a step-by-step workflow. However, it does not explicitly state when not to use the tool or name alternatives, but no sibling offers similar functionality, so the absence is not a major gap.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explains that the tool returns 'agent-friendly capsules' with a structured format, and details how modes alter the response size and content. It does not specify failure modes or edge-case behavior, but for a read-only search tool this is adequate; the description adds meaningful context beyond a bare 'search' statement.

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

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

The description is concise and well-structured: it opens with the core purpose, then a one-sentence summary of the return format, followed by usage guidance and mode-specific bullets. Every sentence contributes useful information without redundancy or fluff.

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

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

The description covers the essential context: purpose, when to use, return format, and mode behavior. While the 'include' parameter (e.g., adding evidences) is not mentioned in the description, it is fully specified in the schema with examples. Given the presence of a rich output schema and 100% parameter documentation, the description is sufficiently complete for effective tool selection and invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the practical trade-offs of mode choices (e.g., compact for small models) and clarifying that fields overrides mode. This goes beyond the schema's parameter descriptions, providing semantic guidance on parameter selection.

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

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

The description clearly states the tool's primary function: searching the Akashic Core API for validated public knowledge. It uses a specific verb ('Search'), identifies the resource ('Akashic Core API'), and explicitly differentiates from sibling tools like search_notes by labeling itself as the primary retrieval path for validated knowledge.

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

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

The description provides explicit usage guidance: 'Use this FIRST for factual/conceptual questions' and directs users to 'search_notes' for working notes. It also describes different modes (compact/standard/full) and custom field projections, giving clear context on how to tailor the search depending on the model's needs.

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

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

With no annotations, the description carries the burden of disclosure. It transparently explains the internal process: runs search_notes, reads the highest-scoring readable hit, and falls back to semantic hints on no match. This covers the key behavioral traits, though it leaves some edge cases unaddressed.

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

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

The description is compact and front-loaded, with three sentences that each convey essential information without waste.

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

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

The description is complete for a tool with an output schema, covering the main flow, the fallback, and the round-trip benefit. It doesn't address edge cases like no results or unreadable hits, but the output schema likely covers the return shape.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions 'full body' which aligns with include_body but adds little meaning beyond the schema's parameter descriptions.

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

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

The description clearly states the tool's purpose: 'One-shot search + read' followed by a specific process. It distinguishes from siblings by explicitly contrasting with 'search → read_note' and stating it saves a round-trip.

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

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

The description gives clear context: 'for small/low-context agents' and explains the advantage over separate search and read calls. However, it does not explicitly state when not to use it or list alternative tools.

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

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

With no annotations, the description relies on text to disclose behavior. It explains the all-tags matching requirement, kind filtering, and the conditional context_neighbors behavior including the query-keyword trigger. It does not explicitly state that the operation is read-only, but 'Search' strongly implies this and the output schema covers return structure.

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

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

The description is concise and well-structured: a one-sentence purpose followed by a compact bullet list of optional filters. Every sentence adds useful information and there is no redundancy.

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

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

For a search tool with an output schema, the description covers all parameter semantics and the key conditional behavior. It is largely complete, though it misses explicit comparison to sibling search tools, which would help in ambiguous contexts.

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

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

Schema coverage is 100%, providing a baseline of 3. The description adds value by explaining the kind examples, emphasizing the ALL-tags semantics, and revealing the include_related query-keyword trigger ('why/how/architecture/decision/설계/결정') that is not present in the schema. This improves parameter understanding beyond the structured definitions.

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

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

The description clearly states the tool searches OpenAkashic notes by title, tags, summary, and body, using a specific verb and resource. It does not explicitly distinguish from sibling tools like search_akashic or search_and_read_top, so it lacks strong sibling differentiation.

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

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

The optional filters give implied usage guidance for narrowing searches, and include_related behavior is explained. However, there is no explicit guidance on when to use this tool versus alternatives such as search_akashic or list_notes, and no exclusions are mentioned.

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

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

With no annotations provided, the description must carry the burden. It does reveal a meaningful behavior: 'published also sets visibility=public', which is useful. However, it omits other behavioral traits such as what other status values do, whether changes are reversible, or if a reason is required.

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

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

The description is a single concise sentence that front-loads the admin/librarian restriction and includes a key behavioral note. It is appropriately short, though slightly under-specified for the tool's complexity.

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

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

Given the lack of schema descriptions, no annotations, and the presence of an output schema, the description should provide more context about valid statuses, required parameters, and workflows. It leaves substantial gaps, making it minimally adequate.

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

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

Schema description coverage is 0%, so the description must compensate. It adds some meaning by indicating 'published' as a possible status and its side-effect on visibility, but it fails to explain the 'path' and 'reason' parameters or enumerate valid status values. This is insufficient for a 3-parameter tool.

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

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

The description 'Admin/librarian-only publication decision helper' gives a general sense but lacks a specific verb+resource construction. It doesn't explicitly say 'sets the publication status of a note' and relies on the title for clarity. It does hint at a side-effect but is vague.

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

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

The description states 'Admin/librarian-only', which indicates the intended audience, but provides no guidance on when to use this tool versus alternatives like request_note_publication or list_note_publication_requests. No exclusions or alternative suggestions are given.

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

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

With no annotations provided, the description carries the full burden of disclosure. It clearly states a critical side effect: 'Does NOT modify the note body — only updates the snoozed_until frontmatter field.' It also reveals the external effect on list_stale_notes, which is valuable behavioral context. It doesn't cover authorization or reversibility, but the core transparency is solid.

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

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

The description is three sentences, front-loaded with the primary action, followed by the effect and use case. Every sentence earns its place with no redundant or tautological phrasing.

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

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

For a simple 2-parameter tool with an output schema, the description fully covers the action, the trigger condition, the side effect, and the non-effect. No additional context is needed for an agent to correctly select and invoke this tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by naming the underlying field 'snoozed_until' and explaining how the 'days' parameter affects list_stale_notes visibility. This contextualizes the parameters without duplicating schema text.

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

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

The description opens with 'Snooze the stale-decay reminder for a note by setting snoozed_until,' which clearly names the action, resource, and mechanism. It distinguishes the tool from siblings like list_stale_notes and confirm_note by explaining its specific role in the stale-note workflow.

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

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

The description explicitly states when to use the tool: 'Use this when a note is still accurate but hasn't been formally refreshed.' It also explains the consequence on list_stale_notes, which implies when not to use (when the note is not accurate). It doesn't name alternative tools explicitly, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the return type (embeddable markdown), but it does not mention any side effects, authentication requirements, file type restrictions, overwriting behavior, or other operational details that would be expected for an upload/mutation tool. This is a significant gap.

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

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

The description is a single sentence that immediately states the core function. It is concise, front-loaded with the verb, and contains no filler or redundant content.

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

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

The tool has moderate complexity with four parameters and no annotations. Although an output schema exists (so return values are covered), the description omits critical context such as parameter meanings, usage nuances, and any behavioral constraints. This is insufficient for correct invocation, especially given the 0% schema description coverage.

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

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

The schema has 0% description coverage and the description does not explain any of the four parameters (filename, content_base64, folder, alt). The description adds no meaning beyond the property names themselves, and for required parameters like content_base64, a format or encoding explanation is missing. The description fails to compensate for the schema's lack of detail.

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

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

The description clearly states the action ('Upload an image'), the resource ('into OpenAkashic assets'), and the outcome ('return embeddable markdown'). This is specific and distinguishes from sibling tools, none of which involve uploading images. The title reinforces the purpose.

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

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

The description implies usage when one needs to upload an image into OpenAkashic assets, but it does not explicitly state when to use this tool vs alternatives, nor does it mention any prerequisites or exclusions. There are no direct alternative upload tools among siblings, so the implied usage is acceptable but not explicit.

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

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

With no annotations, the description fully carries the burden. It discloses the overwrite behavior, the contribution workflow with guardrail states, writable root constraints, and the fact that the response includes a path for subsequent steps. This goes well beyond basic mutation description and informs the agent of important 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.

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

The description is well-structured with a clear opening, paragraphs for workflow, and an important callout. It is somewhat lengthy, and the 'Formerly known as' sentence is repeated with the subsequent 'use claim_contribution_status instead,' creating minor redundancy. Still, it is front-loaded and every section serves a purpose.

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

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

For a tool with a rich output schema and many siblings, the description gives enough context to select and invoke it correctly: it covers note kinds, workflow transitions, writable paths, and the crucial next step (requesting publication). It does not need to explain return values because an output schema exists. Minor omissions like conflict behavior are not critical.

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

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

Schema coverage is 100% and already thoroughly documents each parameter. The description adds extra meaning to 'kind' by explaining the guardrail flow and publication implications, and to 'path' by restricting writable roots. This raises it above the baseline of 3, though not all parameters receive additional narrative treatment.

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

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

The description opens with 'Create or overwrite an OpenAkashic markdown note,' which is a specific verb+resource statement that immediately distinguishes this as the upsert tool. It further clarifies scope by discussing note kinds and their workflows, differentiating it from siblings like delete_note, read_note, and append_note_section.

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

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

The description provides explicit when-to-use guidance: 'Prefer claim for atomic reusable findings' and 'kind='capsule' notes stay private until you request publication review.' It also names alternatives and next steps: 'use claim_contribution_status to check submitted claim state' and 'pass it to request_note_publication' for publication. This clearly orients the agent.

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

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

With no annotations, the description carries the transparency burden. It discloses that the tool returns identity fields and adds context about the API token (for web UI login) and account provisioning status. This goes beyond a simple 'returns identity' statement, though it doesn't explicitly state that it's a read-only operation, which is arguably implied.

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

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

The description is highly concise: one opening sentence that defines the core purpose, followed by a short bullet list of usage scenarios. Every sentence earns its place, and the structure front-loads the most important information.

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

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

For a zero-parameter tool with an output schema, the description fully covers when and why to use it. It explains the return values (username, nickname, role, token) and provides contextual use cases. The output schema presumably details the return structure, so the description doesn't need to repeat that.

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

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

The tool has zero parameters, so the description doesn't need to explain parameter meanings. The baseline for 0 params is 4, and the description appropriately focuses on use cases rather than nonexistent parameters.

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

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

The description clearly states the tool's function: 'Return your username, nickname, role, and API token.' This is a specific verb ('Return') with a clear resource (identity information), and it distinguishes itself from the sibling tools, which are mostly note/folder/debug operations.

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

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

The description explicitly lists three use cases under 'Useful when you need to:' which tells the agent when to invoke this tool. It doesn't mention alternatives or exclusions, but given the unique nature of 'whoami' (no sibling provides identity info), the absence of alternatives is acceptable.

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