abyss-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.5.9
Disambiguation4/5
Most tools have clearly distinct purposes with detailed usage descriptions. However, the presence of deprecated alias tools (e.g., recall_decision_reason, review_pending_connections) adds some confusion and may cause incorrect selection.
Naming Consistency4/5
The majority of tools follow a consistent verb_noun pattern (e.g., list_projects, create_wiki_page). A few tools like 'whoami' and deprecated aliases break the pattern, but overall naming is predictable.
Tool Count2/5
With 55 tools, the surface is very large and likely overwhelming for agents. Many tools handle niche operations (e.g., sync, governance) that could potentially be merged or simplified.
Completeness4/5
The tool set covers authentication, project management, wiki, search, sync, proposals, checkpoints, agent access, and governance. Minor gaps exist (e.g., no delete_wiki_page), but the core workflows are well-covered.
Average 4.5/5 across 55 of 55 tools scored. Lowest: 3.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant context beyond annotations: agent-safe, idempotency behavior, human approval required later, failure handling steps (login_required, project_not_selected, etc.). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bolded sections (Use when, Do not use when, Effect, Then, On failure). Slightly long but every sentence adds value; front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage conditions, idempotency, auth, project selection, human approval, failure handling. Output schema exists so return values not needed. Operations array is not detailed but that is acceptable given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 11%, yet the description does not explain individual parameters beyond idempotencyKey usage. The schema is detailed but lacks descriptions; description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'persist' and resource 'Page/Object operations as a digest-bound ChangeProposal'. Distinguishes from siblings by noting it cannot apply/reject/choose conflict winner, but does not explicitly name a narrower alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when:' and 'Do not use when:' sections provide clear conditions for invocation. Mentions alternatives (narrower tool) and user intent rejection. Also lists prerequisites (authentication, project selection).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description contradicts annotations: annotations set readOnlyHint=false, indicating not read-only, but the description calls it a 'read or staging action'. This inconsistency undermines transparency despite other behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is quite long but each sentence adds value, with the key use case front-loaded. Slightly verbose, but efficient given the amount of information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and annotations are present, the description thoroughly covers the login flow, failure scenarios, required subsequent steps, and operational constraints, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters (0 params, 100% coverage), so baseline is 4. The description does not need to add parameter info; it appropriately focuses on process and context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Start Abyss browser device login', specifying the verb (start) and resource (login). It distinguishes from siblings like complete_login and auth_status by indicating the sequential flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use, with 'Use when:' and 'Do not use when' conditions. Also provides clear next steps (complete_login, auth_status, list_projects, select_project) and failure handling, offering comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and non-destructive write. The description adds key behavior: 'Effect: draft', server-computed digest, idempotencyKey replay semantics ('never bypasses authorization'), and human approval at a later stage. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear section headers (Use when, Do not use when, Requires, Effect, Then, On failure) and front-loads the critical purpose. It is somewhat long, but every sentence adds necessary context; the organization earns a high score for clarity despite length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (11 parameters, rich nested objects, output schema present), the description covers purpose, usage conditions, behavioral traits, error handling, and post-invocation steps. It omits detailed parameter semantics but includes key constraints (no credentials, no full conversation). The presence of an output schema partially compensates, but low schema coverage limits completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 36%, the description carries responsibility for explaining parameters. Instead, it provides only high-level terms ('observation bounds', 'safe source spans', 'candidate changes') without clarifying individual fields like metadata, sessionId, evidenceIds, or nested structures like conversationProvenance. The schema's own descriptions are sparse, and the tool label does not compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a 'V1 checkpoint draft' from the visible conversation, using specific verbs and resources. It provides scope ('observation bounds, safe source spans...') and contrasts with 'narrower tool' usage, though sibling tools like commit_checkpoint are not named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly includes 'Use when' and 'Do not use when' sections with concrete conditions, plus 'Requires', 'Human approval', 'Then' guidance, and a full 'On failure' error-handling table. This leaves no ambiguity about when and how to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds beyond annotations by stating the effect is read-only (no sync cursor change) and provides extensive error-specific guidance, enhancing transparency without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections ('Use when', 'Do not use when', 'Requires', etc.) and front-loads the core purpose. However, it is verbose with extensive detail on failure modes and post-actions, which could be condensed to improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking explicit return value documentation (though output schema exists), the description adequately sets expectations by listing the types of history returned (delivery, receipt, etc.) and covering error handling. It is largely complete for a read operation with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only projectId has a description). The description does not detail what each parameter means, only using terms like 'connection-scoped' without clarifying scopeType or scopeId semantics. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states a specific verb ('Read') and a well-defined resource ('connection-scoped delivery, receipt, consumption, preview, and deferral history'), and distinguishes itself from sibling tools like get_project_sync_status and record_project_sync_decision by emphasizing it does not change the sync cursor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, lists prerequisites (authenticated API authority, selected project), and includes detailed failure handling instructions, offering comprehensive guidance on when and how 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent mutation. Description adds extensive behavioral context: canonical mutation, idempotency key replay, authorization checks, expected-version handling, human approval not required, failure modes with actions, and post-action steps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Use when, Requires, Effect, Human approval, Then, On failure). Front-loaded with core action. Slightly verbose but justified by complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, 2 required, high schema coverage, and existing output schema, the description adds necessary workflow context, failure handling, and post-action guidance. Fully complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 92%, so the schema already documents most parameters. The description adds context about idempotency key usage but does not significantly expand on parameter meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Record that the selected project reused a context package' with specific target types. It names the verb and resource, but does not differentiate from sibling tools like record_context_consumption.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context, including conditions like 'project scope unresolved' and 'user declined'. Mentions that a narrower tool may be better but does not list specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: states read effect, authentication and project requirements, human approval not needed, and detailed failure handling. Annotations already cover readOnly and destructive hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear headings but somewhat lengthy; each section is justified for the deprecated nature. No redundant content despite length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage: usage context, requirements, effect, human approval, post-action steps, and failure modes. Output schema exists but is not needed due to detailed 'Then' section.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and descriptions already cover behavior (defaults, rejection). The tool description does not add new parameter information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly identifies the tool as a deprecated compatibility alias for 'recall intent current_thread', distinguishing it from siblings like 'recall' and 'resume'. It explicitly states not to use for new workflows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' conditions, including alternatives and specific scenarios to avoid (e.g., narrower tool match, unresolved project scope).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds 'Effect: read' and 'Human approval: not required for this read or staging action', which aligns with annotations. It also details failure handling (login_required, project_not_selected, etc.). This adds useful behavioral context beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections ('Use when', 'Do not use when', 'Requires', etc.), making it easy to parse. It is front-loaded with the most critical usage guidance. However, it is somewhat verbose, repeating conditions like 'Requires' and 'Effect' that could be more terse. Still, it earns its space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has an output schema, the description need not explain return values. It covers purpose, usage conditions, effect, human approval, and failure modes. However, it does not explain what 'PageVersion backlinks' are or what 'typed destination' means, which might be context the agent needs. Overall, it is fairly complete for a read tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only projectId has a description). The description does not elaborate on any parameter meanings; it only vaguely mentions 'typed destination' which relates to targetType but adds no specifics. Given the low coverage, the description should compensate but does not, leaving the agent to infer parameter semantics from schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads 'current or historical PageVersion backlinks for a typed destination in the selected project.' The verb 'read' and resource 'PageVersion backlinks' are specific, and the scope is delimited to a typed destination and selected project. This distinguishes it from sibling tools like get_wiki_page or explain_why_linked.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly starts with 'Use when:' and 'Do not use when:', providing direct guidance on when to invoke this tool. It also lists requirements (authenticated API authority, selected project) and conditions for not using (narrower tool matches, unresolved scope, declined action). This is comprehensive and explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the effect is 'read' and human approval is not required. It also details failure scenarios (login_required, project_not_selected, etc.) and appropriate responses, exceeding what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose, but it is lengthy and includes many conditional statements (e.g., 'On failure: ...') that could be condensed. Some repetition (e.g., 'Requires:') adds clutter. Could be more concise without sacrificing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, enums, output schema), the description covers read behavior, failure modes, and post-action steps. However, it lacks parameter-level detail and does not describe the output schema. Output schema exists but is not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25%, but the description does not elaborate on individual parameters. It mentions 'connection/session cursor' hinting at connectionId and scopeType, but does not explain values or constraints beyond the schema. More parameter guidance is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb 'Read' and specific resources: 'selected Project contextVersion, monotonic connection/session cursor, pending proposal count, and sync state.' It distinguishes this tool from siblings like get_project_sync_activity by focusing on the current sync status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when' and 'Do not use when' with concrete conditions (e.g., 'narrower tool better matches the intent', 'project scope is unresolved'). It also provides follow-up guidance: 'review pending proposals/drafts before any canonical apply.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds extensive behavioral detail beyond annotations: 'Effect: read', 'Human approval: not required', post-action steps, and error handling scenarios (e.g., login_required, project_not_selected). This provides comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections but is verbose (multiple lines). While clear, it could be more concise without losing key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (optional parameters, error handling, governance context), the description covers usage, conditions, effect, post-action, and error recovery. The presence of an output schema reduces the need to explain return values, but the description is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description does not need to repeat parameter details. The description adds minor context (e.g., projectId defaults) but no new semantics beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists checkpoint audit events for a selected project, with a specific use case: inspecting propose, commit, and discard history before governance/export work. It distinguishes from siblings by focusing on audit events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' sections, providing context for when to use this tool versus alternatives. It mentions 'a narrower tool better matches the intent' but does not name specific sibling tools, slightly reducing specificity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations. It confirms the effect as 'read', states that human approval is not required, and provides detailed error handling and follow-up instructions (e.g., 'On failure: login_required → login; ...'). Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as true/true/false, and the description aligns with and extends these with actionable guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections ('Use when', 'Do not use when', 'Requires', etc.) and is front-loaded with the purpose. However, it is verbose, containing detailed error handling and follow-up instructions that could be more concisely presented. It could be trimmed by half without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the parameter semantics gap, the description provides comprehensive context: purpose, usage conditions, prerequisites, effect, approval requirements, error handling, and post-use actions. An output schema exists, so return value details are not required. For a tool with two parameters and moderate complexity, the description covers all necessary aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only projectId has a description; proposalId does not). The description does not add new semantic information about the parameters beyond what is already in the schema. It mentions the projectId default behavior, but that is already in the schema's description. For proposalId, no additional context is provided. Given the low coverage, the description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core action: 'Fetch a proposal and return a Web review handoff URL.' It uses a specific verb ('fetch' and 'return') and resource ('proposal', 'Web review handoff URL'). The description also distinguishes the tool from siblings by noting that human review/apply remains outside the agent-safe MCP surface, and provides explicit conditions for when not to use it (e.g., 'a narrower tool better matches the intent').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' sections, providing clear context for tool invocation. It lists prerequisites ('authenticated API authority and an API-authorized selected Project'). It mentions alternatives indirectly ('a narrower tool better matches the intent') but does not name specific sibling tools, which would have made it a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint; the description adds valuable behavioral context like effect 'read', error handling scenarios, and the fact that projection watermarks are returned separately. Minor omission: no mention of pagination or limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured into clear sections, front-loads the core purpose, and each sentence adds value. Though somewhat verbose, it remains focused and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description covers purpose, guidelines, requirements, error handling, and follow-up actions. The only gap is parameter documentation, but overall it provides a solid understanding of the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (only projectId has a description). The description does not elaborate on the meaning or usage of parameters like limit, includeObjects, or query, leaving the agent without sufficient detail to use them correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs exact/lexical search across authorized wiki pages and continuity object revisions, explicitly distinguishing it from narrower tools like get_wiki_page or get_continuity_object.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' conditions, along with requirements (authenticated API authority, selected project), offering clear guidance on when to invoke 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, and destructiveHint; the description adds that the effect is 'read' and details failure handling and human approval not required, providing valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, but it is somewhat verbose with detailed failure handling and generic statements that could be trimmed without losing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with an output schema, the description covers purpose, usage, conditions, and failure modes adequately, though it lacks specifics about output format (mitigated by output schema).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add additional information about the projectId parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list' and the resource 'agent principals' in the context of a selected project, distinguishing it from siblings like grant_agent_project_access and update_agent_project_access.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear guidance on when to use this tool versus alternatives, and specify requirements like project management permission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it is a canonical mutation without idempotency key, requires human approval, and lists failure handling behaviors (login_required, permission_denied, etc.). Adds context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections for when to use, not to use, effects, failure handling. However, it is somewhat verbose and could be more concise without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage context, failure modes, and human approval, but lacks parameter documentation. With 9 parameters and 0% schema coverage, the description should provide more parameter-level guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description does not explain individual parameters like email, score, consent, message, category, confirmed, preference, or client. The action enum is described in purpose, but other parameters lack guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool offers a survey, submits feedback, prepares email, manages prompt preference, and subscribes to newsletter. It distinguishes from siblings by listing specific actions not covered by other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (after 3 successful calls or user praise/frustration/bug/feature request) and when not to use (interrupting primary task, without explicit consent, narrower tool available, project scope unresolved, declined action). Provides clear guidelines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description states 'Effect: read' and 'Human approval: not required.' Provides detailed error handling mapping. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with bullet points and labeled sections, making it easy to scan. However, it is somewhat verbose; could be more concise without losing critical info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no required ones, and an output schema exists, the description covers usage, prerequisites, effects, and error handling. Parameter documentation is lacking, but overall completeness is good.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (only projectId documented). Description does not add meaning for the other 6 parameters (q, type, limit, cursor, status, currentPageId). Fails to compensate for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: 'List permission-safe Project block candidates without raw source or conversation bodies.' It distinguishes the tool by specifying what is excluded and the context (permission-safe). This is specific and differentiates 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.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' conditions, including narrowing to intent, project scope, and user consent. Also lists prerequisites (authenticated API authority, selected project) and next steps. Comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses effect as 'read', no human approval needed, and covers failure modes (login_required, permission_denied, etc.). Annotations already indicate read-only and idempotent, but description adds valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections (Use when, Requires, Effect, etc.). Slightly lengthy but each part adds value. Could be more concise by removing redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage, prerequisites, failure scenarios, and post-list actions (select_project, review pending proposals). Output schema exists, so description does not need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description does not add parameter-level details beyond schema, which is acceptable given high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists user's Abyss projects and instructs to call select_project afterward. Differentiates from sibling tools like create_project and select_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' sections, and lists requirements. Does not name specific narrower tools, but implies they exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds effect 'read', failure details, and post-action steps, which provides good context beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections, front-loaded with key purpose. Slightly verbose but each sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage boundaries, effect, required auth, failure modes, and post-action steps. Given zero required params and presence of output schema, the description is fully adequate for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described. The description repeats the parameter info without adding new semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's a read-only compatibility alias for recall intent decision_reason and explicitly prefers the sibling tool 'recall' for new clients, distinguishing it effectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when', 'Do not use when' conditions, required authentication, effect, human approval requirements, and failure handling, offering comprehensive guidance for selection and invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important behavior beyond annotations: it's a canonical mutation with no client idempotency key, advising not to retry automatically. Also clarifies human approval is not required and describes failure modes. This adds significant context not available from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, but somewhat verbose due to detailed failure enumeration. Could be more concise without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and annotations, the description provides comprehensive guidance on usage, failure handling, and behavioral expectations. It covers when to use, when not, and what to do on various failures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only projectId has a description). The tool description does not elaborate on the meaning of executionId, contextPackageId, impressionIds, or actualPromptHash, leaving the agent with minimal understanding of parameter purposes beyond the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Record that a delivered ContextPackage was actually used by an AIExecution'—a specific verb+resource. It distinguishes from sibling tool 'confirm_context_delivery' by noting that delivery and consumption are separate facts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when:' and 'Do not use when:' conditions, including when to avoid using (narrower tool, unresolved scope, user declined). Also includes failure handling instructions, guiding correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral details beyond annotations: 'This read does not create a package or advance a cursor,' 'Effect: read,' error handling steps. No contradiction with annotations (readOnlyHint=true, destructiveHint=false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (use when, do not use, requires, effect, then, on failure). It is comprehensive but slightly verbose; a bit more brevity could improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, output schema present, annotations present), the description is thorough. It covers purpose, usage, behavior, error handling, and post-call actions ('follow typed result state; review pending proposals/drafts'). No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% with no descriptions for fromVersion and toVersion. The description mentions 'by contextVersion' but does not explain the parameters. It fails to compensate for the low schema coverage, leaving agents uncertain about parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Preview ordered ProjectChangeSets by contextVersion.' It specifies the resource (ProjectChangeSets) and distinguishes from siblings by noting it does not create a package or advance a cursor, and suggests not using when a narrower tool matches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use ('Preview ordered ProjectChangeSets by contextVersion') and when-not-to-use ('a narrower tool better matches the intent, the project scope is unresolved, or the user has declined the action'). Also lists prerequisites: authenticated API authority and API-authorized selected project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the mutation nature (no readOnlyHint), lack of idempotency, authorization delegation to API, and no human approval needed, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, but somewhat verbose; sections like 'Human approval' could be more concise given annotations already cover this.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers failure modes and workflow placement well, but lacks description of return value structure and parameter details, given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 13% schema description coverage, the description does not explain the meaning of critical parameters like taskId or inputSyncReceiptIds, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Start the durable AIExecution that will consume an already delivered ContextPackage' and positions it between confirm_context_delivery and record_context_consumption, clearly differentiating it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when' and 'Do not use when' clauses, retry warnings, and a structured 'On failure' section covering common errors, providing comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint true and destructiveHint false. The description adds significant context: it is a 'canonical mutation', explains idempotency key reuse ('reuse the same idempotencyKey'), replay behavior ('returns the first canonical result ID and version'), and safety checks. It also states human approval is not required and provides error handling logic for various failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Do not use when, Requires, Effect, Human approval, Then, On failure). Every sentence adds value, though the length is substantial. It could be slightly more concise, but it is efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, 2 enums, output schema exists), the description covers purpose, usage, behavioral effects, idempotency, error handling, and post-conditions. Parameter semantics are the main gap. The presence of an output schema reduces the need to explain return values. Overall, it is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 8% (only projectId documented). The description mentions key concepts like idempotencyKey, expectedCursorVersion, fromVersion, toVersion, and status, but does not provide detailed semantics for each of the 13 parameters. For instance, transportAcknowledgementHash is not explained. The description partially compensates by contextualizing versioning and idempotency, but lacks per-parameter clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Record authenticated transport acknowledgement and advance the cursor only for a valid delivered package.' It uses a specific verb ('record') and resource ('transport acknowledgement'), and distinguishes itself from siblings like record_context_consumption by focusing on delivery confirmation and cursor advancement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when' and 'Do not use when' conditions, including alternatives like 'a narrower tool better matches the intent.' It also lists prerequisites: 'authenticated API authority and an API-authorized selected Project.' Error handling instructions further clarify when to use which recovery action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond annotations: it's a 'canonical mutation', explains idempotency key usage ('reuse the same idempotencyKey... replay returns the first canonical result'), requires human approval, and details error handling (login_required, stale_version, etc.). This adds significant context to the idempotentHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections (Use when, Do not use when, Requires, Effect, Human approval, Then, On failure). It front-loads the most critical usage guidance. Minor redundancy could be trimmed, but overall it is efficient for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (16 parameters, nested objects, output schema exists), the description covers usage constraints, error handling, idempotency, and follow-up steps. However, it lacks detailed parameter guidance for the 'kind' enum and other properties, which would be needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 6%, so description should compensate. However, it does not explain individual parameters beyond noting required ones (pageId, kind, expectedPageVersion, idempotencyKey) in context. The 'kind' enum is not elaborated, and many parameters lack description. Some value is added via the compound command context, but it's insufficient for 16 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Use the API compound command to atomically save PageVersion, object revision, references, ChangeSet and outbox.' It uses a specific verb ('execute block command' implied) and resource, and distinguishes from siblings by framing it as a compound command for atomic updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections are provided, including conditions like 'a narrower tool better matches the intent, the project scope is unresolved, or the user has declined the action.' Prerequisites ('Requires') and alternative guidance are also included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, destructiveHint=false. The description adds 'Effect: read' and 'Human approval not required,' plus detailed error cases, extending behavioral understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with key usage guidelines, structured with clear sections. It is moderately lengthy but each sentence adds value; could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and rich annotations/output schema, the description covers usage, prerequisites, error handling, and effect. It does not detail output schema (not required) but is sufficiently complete for effective agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds minimal extra parameter-level context, e.g., projectId defaults, but does not elaborate on intent enum values. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for 'Human-account read-only recall' and lists specific intents (decision_reason, changed_view, etc.). It distinguishes from narrower tools by advising against use when a better match exists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when' and 'Do not use when' sections, specifies prerequisites (active project, credentials), and provides error handling guidance, offering comprehensive usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context beyond annotations: specifies it does not accept actorId, requires authenticated API authority, effect is read, human approval not required, and details error handling (login_required, project_not_selected, permission_denied, stale_version, projection_pending) and subsequent steps. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with labeled sections ('Use when', 'Do not use when', etc.) and front-loads key information. However, it is somewhat verbose with details like 'review pending proposals/drafts before any canonical apply' which could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, an output schema, and rich annotations, the description covers usage context, authentication, effect, error handling, and post-action steps. It provides complete guidance for the AI to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, and schema coverage is 100%. The description adds that it does not accept actorId, which is not a parameter in the schema, clarifying what the tool does not take. This extra context justifies a score above baseline 3 for 0-param tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb 'show' and resource 'team onboarding status and recommended next step'. It also specifies 'human-account tool' and that it does not accept actorId. However, it does not explicitly distinguish from sibling tools, though no sibling appears to directly overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' clauses, including conditions about narrower tools, unresolved project scope, or user declination. This clearly guides the AI on when to select this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors beyond annotations: it is a read or staging action, never auto-saves, requires no human approval for this step, and only passes to checkpoint draft. Also explains failure modes and follow-up actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded usage conditions. Some redundancy (e.g., repeating 'no auto-save' in multiple forms) but overall concise for the amount of guidance provided.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description covers all necessary context: when to use, prerequisites, safety profile, failure handling, and post-invocation steps. Missing nothing essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so parameter meanings are already clear. The tool description adds no additional semantic detail beyond the schema, meeting the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to ask the user if a judgment from the current conversation should be remembered, and it never auto-saves—only creates a checkpoint draft. It distinguishes itself from sibling tools like commit_checkpoint by emphasizing the ask-first behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' conditions, including requirements (authenticated API authority) and failure handling instructions. This gives clear guidance on when to invoke 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying 'Effect: read,' human approval not required, and detailed failure handling (e.g., 'On failure: login_required → login; project_not_selected → list_projects/select_project; ...'). This contextualizes behavior beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Use when, Do not use when, Requires, Effect, etc.). It is front-loaded with the key purpose. However, it is somewhat verbose with failure handling details, which could be condensed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, full annotation coverage, and the presence of an output schema, the description is complete. It covers purpose, prerequisites, failure modes, and procedural next steps, leaving no significant gaps for correct tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and schema coverage is 100%. Per guidelines, baseline is 4. The description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Check the current Abyss MCP login status.' It distinguishes itself from siblings like login, logout, and whoami by focusing on status checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides use and misuse conditions: 'Use when: Check the current Abyss MCP login status.' and 'Do not use when: a narrower tool better matches the intent, the project scope is unresolved, or the user has declined the action.' Also states the requirement for authenticated API authority.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already show readOnlyHint=true and destructiveHint=false, and the description adds 'Effect: read' which aligns. It goes further by detailing failure modes and required authority, providing valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with bullet points and front-loads the purpose, but it is somewhat verbose, especially in the failure handling section. It could be slightly more concise while retaining essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers purpose, usage, prerequisites, failure modes, and post-action steps, making it complete for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% (one param described). The description does not explicitly detail each parameter beyond their names, but it clarifies the role of projectId (optional, defaults to selected project) and reinforces the use of fromVersion/toVersion as version numbers via the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Compare two immutable PageVersions as a stable typed block diff,' specifying the action, resources, and output. It distinguishes from sibling tools by highlighting the typed diff nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' conditions are provided, including when to avoid using the tool (narrower tool matches, unresolved project scope, user declined). It also lists prerequisites like authenticated API authority and selected project.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich behavioral details beyond annotations: canonical mutation, idempotency key behavior, human approval requirement, and failure mode actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well structured with front-loaded purpose, but slightly lengthy due to comprehensive failure handling. Still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, effect, idempotency, human approval, next steps, and failure recovery. Output schema exists, so no gap on return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description adds no parameter details beyond what schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool discards a draft checkpoint after user confirmation, distinguishing it from siblings like commit_checkpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use and when not, referring to narrower tools and user intent. Also covers failure handling and preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds context: 'Effect: read', 'Human approval: not required', and detailed error handling. It also notes the tool is deprecated, providing additional behavioral insight beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Use when, Do not use when, Requires, etc.) and front-loads essential information. It is slightly verbose, but every sentence adds value for a deprecated tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description does not need to explain return values. It covers purpose, usage, error handling, and required auth completely. The deprecated status and alternatives are clearly communicated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters adequately. The description does not add meaningful meaning beyond what the schema provides, achieving the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a read-only compatibility tool that explains why a saved thought or connection exists. It distinguishes itself from siblings by explicitly naming preferred alternatives (get_continuity_object, get_page_backlinks) and noting it is deprecated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'Use when' and 'Do not use when' conditions, including when a narrower tool matches intent, project scope is unresolved, or user declined action. It also suggests alternative tools, giving clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. Description adds 'Effect: read' and 'Human approval: not required for this read or staging action', plus detailed on-failure behaviors that clarify expected side effects and next steps. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with sections for use cases, requirements, effects, approval, and error handling. Each sentence adds value, though some redundancy exists (e.g., repeating 'read' in multiple forms). Overall efficient for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description focuses on preconditions, effects, and error handling, which are fully covered. It addresses authentication, project selection, human approval, and failure scenarios, making it complete for a read tool without needing to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only projectId has a description). itemId lacks description, and the tool description does not explain what itemId refers to or how to obtain it. While the context is clear from the overall description, parameter semantics are not fully detailed beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'read' and the specific resources: 'built-in Decision, Principle, Assumption, Open Question, or Next Action identity plus immutable revision history in the selected project.' This specificity distinguishes it from sibling tools like get_wiki_page or get_continuity_operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when:' and 'Do not use when:' conditions, including guidance to look for a narrower tool if applicable. Also details when human approval is not required and provides structured error handling steps with recommended follow-ups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds 'Effect: read' and 'Human approval: not required for this read or staging action,' plus detailed failure resolution steps. Annotations already indicate read-only, idempotent, non-destructive; description enriches context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections. While somewhat verbose, each section adds value and aids comprehension. Not overly concise but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (1 optional parameter, output schema exists), the description fully covers purpose, usage, requirements, and failure modes. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single optional parameter with 100% schema description coverage. Description does not add extra meaning beyond schema, which is already thorough. Baseline score of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool reads selected Project durable outcomes, corrections, reviewer attribution, and audit activity. Distinguishes from siblings by advising not to use when a narrower tool matches intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when:' and 'Do not use when:' sections specify conditions. Also outlines requirements (authenticated API authority, API-authorized selected Project) and failure handling, providing complete guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds behavioral details: effect is read, human approval not required, and specific failure handling steps (e.g., login_required → login). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the main purpose and uses a structured format with headings. While it is somewhat lengthy due to comprehensive failure handling, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description is complete: it covers purpose, usage, behavior, failure modes, and post-action steps without redundancy. No significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and fully documents the projectId parameter with default behavior and error conditions. The description adds no additional semantic value beyond what the schema already provides, meeting baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads the deterministic current weekly review and returns its Web review handoff URL. It uses a specific verb and resource, distinguishing it from sibling tools like review_pending or get_project_sync_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when' and 'Do not use when' conditions, including alternatives when a narrower tool matches intent or when project scope is unresolved. It also outlines prerequisites and failure handling, giving comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds detailed behavioral context: effect is read, required authentication, human approval not needed, and explicit failure handling instructions. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Use when, Do not use when, Requires, etc.), but it is somewhat verbose and includes some redundancy (e.g., 'Effect: read' is already evident). Still, it is organized and front-loaded with key guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (versioning, multiple failure modes, dependency on project selection), the description is comprehensive. It covers authentication, human approval, error recovery, and interaction with proposals/drafts. Output schema exists, so return values need no elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, with only projectId having a description. The description mentions reading current or historical versions, implying the role of the 'version' parameter, but does not explicitly define pageId or version semantics beyond the schema. Partial compensation but insufficient detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool reads the current or a historical PageVersion, including specific behavior for root Brief reads. It clearly distinguishes from sibling tools like list_wiki_pages and create_wiki_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context for when to invoke this tool, including indications of alternative tools and conditions that preclude use (e.g., unresolved project scope, user declined).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (all false). Description adds critical behavioral details: canonical mutation, no idempotency key, human approval required, and retry prohibition. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and front-loaded usage guidance. Slightly verbose but every sentence adds value. Could be tightened slightly without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (4 params, output schema, many siblings), the description covers purpose, usage, effects, human approval, follow-up, and failure modes. No gaps for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with existing parameter descriptions. The description does not add new parameter-level meaning beyond examples already in schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it grants or reactivates a project-scoped agent principal, with specific verb and resource. It distinguishes from siblings like list_agent_access and update_agent_project_access by focusing on grant/reactivate action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context and alternatives. Also specifies requirements (authenticated API, selected Project) and failure handling strategies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, destructiveHint=false) are complemented by description stating 'Effect: read' and 'Human approval: not required for this read or staging action'. The description also details failure modes (login_required, project_not_selected, etc.) and follow-up actions, providing rich behavioral context beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with clear sections ('Use when', 'Do not use when', 'Requires', etc.), making it scannable. Every sentence adds value, but conciseness could be improved by reducing redundancy (e.g., 'read or staging action' vs. annotations).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, output schema exists, and many siblings, the description covers purpose, usage, effect, error handling, and post-action guidance ('Then: follow typed result state; review pending proposals/drafts'). It is complete and addresses common scenarios. The output schema covers return values, so no need to describe them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add parameter-specific semantics beyond the schema. However, the 'On failure' section indirectly relates to parameter usage (e.g., projectId validation). No extra credit for parameter details, but no deduction either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists reusable context packages in the selected Abyss project. It uses a specific verb ('List') and resource ('context packages'), and distinguishes itself from siblings like 'get_context_package' (retrieve one) and 'reuse_context_package' (action). The purpose is unambiguous and well-scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use ('Use this before get_context_package or reuse_context_package when continuing team work') and when not to use ('a narrower tool better matches the intent, the project scope is unresolved, or the user has declined the action'). This is comprehensive and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations: 'Package creation never advances the sync cursor', 'Effect: canonical mutation', idempotency key behavior, human approval not required, and detailed failure handling. No contradictions with annotations (idempotentHint=true, destructiveHint=false).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections ('Use when', 'Do not use when', 'Requires', 'Effect', 'Human approval', 'Then', 'On failure'). Every sentence provides necessary information without redundancy, appropriate for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, 6 required, output schema exists), the description covers usage conditions, behavioral effects, failure modes, and idempotency details. It provides sufficient information for an AI agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 18%, meaning most parameters have no schema description. The main description does not directly explain individual parameters like 'connectionId', 'scopeType', 'taskId', etc. While the description provides overall context, it fails to add meaning to each parameter beyond what little the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Use when: Create a task-bounded ContextPackage with an included/excluded/warning manifest', which provides a specific verb and resource. It also includes explicit exclusions ('Do not use when...'), clearly distinguishing the tool from siblings like 'review_project_delta' or 'propose_wiki_changes'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use ('Use when') and when not to use ('Do not use when') with specific conditions. It also lists prerequisites: 'Requires: authenticated API authority and an API-authorized selected Project'. This provides comprehensive guidance beyond typical descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behavioral traits: canonical mutation, idempotency key reuse policy (same key for retry, new key for changed intent), replay behavior, no human approval needed, and detailed failure mappings. This goes well beyond the annotations (idempotentHint=true, readOnlyHint=false, destructiveHint=false) without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and front-loaded purpose. Some verbosity in details, but every section earns its place. Could be slightly more concise but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters (7 required) and an output schema, the description covers usage, behavior, error handling, and postconditions (e.g., follow typed result, review proposals). Output schema exists so return values need not be explained. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 13%; description provides context for 'action' (preview, skip, snooze) and idempotencyKey reuse, but does not explicitly explain other parameters like scopeType, scopeId, connectionId, or throughVersion. Partial compensation but insufficient for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states the action (record a version-bound preview, one-time skip, or 24-hour snooze decision) and what it does not do (never claims delivery or consumption), clearly distinguishing it from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' conditions, requirements (authenticated API authority, selected Project), and a 'Then' section for post-action steps, offering comprehensive guidance on when to use versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the effect ('canonical mutation'), idempotency constraints ('no client idempotency key; do not retry'), human approval (not required for read/staging), and detailed error paths ('On failure: login_required → login;...'). Annotations are sparse but consistent; the description adds essential behavioral context beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear headings ('Use when', 'Then', 'On failure', etc.), making it easy to scan. However, it is somewhat verbose, containing repetitive phrases like 'project-scoped' and 'API-authorized'. Could be tightened without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 params, 0 required, has output schema, many siblings), the description is remarkably complete: it covers prerequisites, errors, post-action steps, and references the output schema. Little is left to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 45%, leaving many parameters undocumented in the schema. The description does not add parameter-level semantics beyond the schema; it focuses on usage and error handling. Without parameter details, tool invocation may be unclear for some parameters. A moderate score reflects minimal added value for parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a 'project-scoped resume context package' for continuing the AI chat, distinguishing it from sibling tools like recall or handoff. The verb 'Create' and resource 'resume context package' are specific. It implies a distinct purpose among many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear guidance on appropriate use cases and exclusions. Additionally, it lists prerequisites ('authenticated API authority', 'selected Project') and postconditions ('Then: follow typed result state').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by stating required authentication and project selection, that it is a read effect, and that no human approval is needed. Detailed failure handling is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, front-loading key info. Slightly verbose due to exhaustive failure handling, but every section adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, requirements, behavior, and error handling thoroughly. Output schema exists, so return values are not needed. Annotations complement the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 does not add further detail about parameters beyond what the input schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a read-only compatibility alias for reviewing pending suggestions/connections, and explicitly distinguishes it from siblings like review_pending and list_change_proposals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'Use when' and 'Do not use when' conditions, suggests preferred alternatives, and advises against selecting this alias for new workflows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses destructive nature (consistent with destructiveHint true), non-idempotency, no retry policy, and permission requirements. Adds significant context beyond annotations, such as 'canonical mutation' and 'no client idempotency key'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections and front-loaded purpose. Slightly verbose but all sentences add value; could be trimmed slightly without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers usage context, prerequisites, effects, failure modes, and follow-up steps. With output schema present, this provides complete guidance for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with good descriptions. Description adds no further parameter-level detail beyond what schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'update a team workspace retention policy' with specific verb and resource. Distinguishes from sibling tool 'get_retention_policy' and others via 'Human-admin tool' qualifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, including human approval requirement, permission constraints, and failure handling. Gives clear context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description adds effect 'read,' human approval note, and detailed failure handling (e.g., login_required -> login), enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with labeled sections, front-loaded key action, and every sentence adds value. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists and annotations cover safety, the description is complete: covers purpose, guidelines, behavior, and failure cases. No missing crucial context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. Description adds minor context (e.g., source of contextPackageId) but doesn't significantly extend schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one project-scoped context package by id.' It specifies the action (read), resource (context package), and scope, distinguishing it from sibling tools like list_context_packages or reuse_context_package.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Has explicit 'Use when' and 'Do not use when' sections with conditions and alternatives. Provides requirements and notes on human approval, offering comprehensive guidance for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=true and idempotent=true. Description adds 'Effect: read', 'Human approval: not required', and detailed failure scenarios (login_required, project_not_selected, permission_denied, stale_version, projection_pending) with prescribed actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is structured and contains valuable information, but it is somewhat verbose with multiple sections. Could be more concise while maintaining clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 optional param, no nested objects, output schema exists), the description covers purpose, usage, effects, failure modes, and follow-up actions completely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter with description. Tool description adds context: optional with default from select_project, and rejection behavior if omitted without a selected project. This goes beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'durable proposals awaiting human review in the selected Project'. It provides specific scope but does not explicitly differentiate from sibling tools like 'open_proposal_review' beyond generic 'narrower tool' guidance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections with specific conditions: narrower tool, unresolved project scope, declined action. Also states prerequisites (authenticated API authority, selected Project).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the read-only, idempotent, non-destructive nature consistent with annotations. It details effects, human approval needs, and provides explicit failure mode handling (e.g., login_required, project_not_selected). No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Use when, Do not use when, Requires, Effect, Human approval, Then, On failure). Every sentence adds value, and the structure aids quick comprehension despite length. Front-loaded with critical guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and comprehensive annotations, the description covers all necessary aspects: purpose, usage boundaries, behavioral effects, failure modes, and post-action steps. It is complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, projectId, is fully described in the schema (100% coverage). The description repeats the schema information and adds the note about authorization but does not provide additional semantic nuance beyond the schema. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the selected Project Wiki root Brief and bounded Page hierarchy. It distinguishes from sibling tools like get_wiki_page by focusing on the hierarchy. The special note about project names not being authorization evidence adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide clear context. It specifies when to use (list hierarchy) and when not (if a narrower tool matches or project scope unresolved). It also lists requirements like authenticated authority and selected project, and gives failure handling instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide limited info (non-read-only, non-destructive, non-idempotent). The description adds critical context: 'canonical mutation', 'no client idempotency key', 'do not retry automatically'. It also describes failure modes without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, but it is lengthy. Every sentence adds value, though some details (e.g., failure cases) could be more compact. Front-loading the main purpose is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 params, nested objects, output schema exists), the description covers usage context, failure modes, behavioral notes, and some parameter guidance. It does not detail return values (output schema exists) but is otherwise thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 43% (low). The description explains the externalConversation parameter and its fields in detail, compensating for part of the gap. However, it does not describe other parameters like scopeId, scopeType, or connectionId, which remain undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Select an Abyss project and open an API-backed continuity session.' This is a specific verb+resource, and the 'Do not use when' section distinguishes it from narrower tools or when the project scope is unresolved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when:' and 'Do not use when:' sections provide clear guidance. It also lists requirements and failure handling, e.g., 'Requires: authenticated API authority' and 'On failure: login_required → login'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds crucial context: 'canonical mutation', idempotency behavior ('reuse the same idempotencyKey', 'replay returns the first canonical result ID and version'), and human approval requirement. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear 'Use when', 'Do not use when', 'Requires', 'Effect', 'Human approval', 'Then', 'On failure' sections. It is front-loaded and every sentence adds value, though slightly lengthy for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (7 params, nested objects, output schema exists), the description covers approval flow, idempotency, failure modes, prerequisites, and follow-up actions. It is comprehensive without needing to detail return values since output schema is provided.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 57% schema coverage, the description adds value by explaining idempotencyKey reuse policy and binding approvalEvidence to server draft digest. While some parameters still lack detailed explanation, the description compensates well for the gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: 'commit the exact reviewed draft after explicit user approval of the checkpoint commit.' It distinguishes itself from siblings like 'checkpoint' and 'discard_checkpoint' by focusing on the commit action after human review.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Do not use when: a narrower tool better matches the intent, the project scope is unresolved, or the user has declined the action.' It also provides guidance on idempotencyKey reuse and human approval requirements, giving clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description goes beyond annotations by noting this is a canonical mutation with no idempotency key (do not auto-retry), human approval not required, and detailed failure paths. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with clear sections and no redundancy, though slightly longer than strictly necessary; still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description covers purpose, usage, effects, and failure handling completely. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so schema coverage is 100%. Baseline for 0 params is 4; description does not need to add parameter info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool completes Abyss browser device login after user approval. It distinguishes itself from siblings like 'login' and 'auth_status' by specifying the exact step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' conditions are provided, along with alternatives and failure-handling instructions, giving comprehensive guidance for when to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that it is a canonical mutation without client-side idempotency, warns against automatic retry, requires human approval, and details failure handling paths. Annotations already indicate non-idempotent and non-read-only; description adds critical context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Structured with clear sections (Use when, Do not use when, etc.), front-loading critical info. Slightly long but justified by complexity; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all aspects: two scopes, idempotency, human approval, failure modes, follow-up actions, and error handling. Output schema exists for return values. No gaps for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear required fields. Description adds context: requiring teamWorkspaceId for team scope and how to obtain it, plus enforcement of permissions. This adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool creates a personal or team project, using specific verbs and resources. It distinguishes from siblings like 'select_project' (post-creation) and 'list_projects' (no creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'Use when' and 'Do not use when' sections provide comprehensive guidance, including prerequisites (e.g., get teamWorkspaceId via team_onboarding_status) and follow-up (call select_project). It also advises against use when scope is unresolved or user declined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it's a canonical mutation, idempotency behavior, human approval requirement, and error handling for various failures. Adds value beyond annotations which already indicate idempotent and non-readOnly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections; front-loaded with 'Use when'. Slightly verbose in places but every sentence provides value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, behavioral traits, parameter semantics, error handling, follow-up steps. Output schema handles return values, making description complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 60% of params. Description adds important context for idempotencyKey (reuse vs new key) and default for projectId. Does not detail title or other params beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it creates a child Page under the selected Project Brief or another Page, distinguishing it from propose_wiki_changes and other siblings. Verb and resource are clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when:' and 'Do not use when:' sections with conditions like narrower tool match, unresolved project scope, user declined. Also states alternative for agent credentials.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds details beyond annotations: requires authenticated API authority, effect is read, no human approval needed, and failure behavior mapping, which supplements the readOnlyHint and idempotentHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured with sections but slightly verbose with multiple lines of failure cases; generally front-loaded and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given presence of output schema, description adequately covers prerequisites, failure handling, and effect, making it complete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers parameter fully with 100% description coverage. Description adds context that teamWorkspaceId comes from team_onboarding_status, adding value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'read a team workspace retention policy' and clearly differentiates from siblings like update_retention_policy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Includes explicit 'Use when' and 'Do not use when' sections, with examples and conditions for not using, providing clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false, and the description adds that the effect is read, raw data is excluded, and details failure handling (e.g., login_required, stale_version). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with clear sections (Use when, Do not use when, etc.) and front-loaded with key information. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low parameter count, presence of output schema, and rich annotations, the description covers purpose, usage, behavior, error handling, and follow-up steps comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one optional parameter. The description adds context on default behavior (project selection) and rejection scenario, enhancing understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports an aggregate-only markdown IR appendix for the selected project. It uses specific verb 'export' and identifies the resource, though it does not explicitly differentiate from sibling tools beyond the context of being a governance tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when' and 'Do not use when' conditions, lists requirements, and specifies human approval needs. This gives clear guidance on when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behavioral traits beyond annotations, such as 'canonical mutation', lack of idempotency key, and detailed error handling instructions. Annotations indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description adds context on when to use and the effect on state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, though somewhat verbose. Every sentence adds value, but could be slightly more concise without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers all necessary aspects: purpose, usage, requirements, error handling, and behavioral traits. An output schema exists, so return values are not needed in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 4 parameters are documented in the schema with descriptions, and the description adds value by explaining defaults (e.g., 'Defaults to the project chosen with select_project') and conditions for rejection. This goes beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a project-scoped handoff context package for the next AI conversation.' This provides a specific verb and resource, and it distinguishes the tool from siblings like 'list_context_packages' or 'get_context_package'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'Use when:' and 'Do not use when:' sections, outlining prerequisites, required authentication, and error handling steps. It also specifies when not to use the tool, such as when a narrower tool matches or the user declines.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint: true, idempotentHint: false), the description adds crucial behavioral details: 'Effect: canonical mutation. This mutation has no client idempotency key in the current contract; do not retry it automatically after an unknown outcome.' It also outlines failure handling steps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections but is slightly verbose. It front-loads the core purpose effectively, though some parts (e.g., 'Then: follow typed result state') could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, an existing output schema, and detailed coverage of usage, failure handling, and safety, the description is fully complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% coverage, so the description naturally adds no parameter information. Baseline 4 applies as no further elaboration is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Revoke the current Abyss MCP credential and remove the local credential file.' This is a specific verb+resource pair that clearly distinguishes it from sibling tools like login, auth_status, and whoami.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Use when:', 'Do not use when:', and 'Requires:' sections that provide explicit guidance on appropriate usage contexts and prerequisites, making it highly informative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description details idempotency (no idempotency key, do not retry), human approval requirement, error recovery steps (login_required, project_not_selected, etc.), and required post-actions (review proposals/drafts). This adds significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Use when, Do not use when, Requires, Effect, etc.) and front-loaded key information. While slightly lengthy, every sentence contributes value, so it earns a 4 rather than a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all necessary aspects: usage context, parameter behavior, error handling, and follow-up actions. Given the presence of an output schema, the description is fully complete for an AI agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the description adds extra context like using status='removed' to disable access without deleting audit history and clarifying default behaviors for status and projectId. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a project-scoped agent principal's role or status, using the verb 'update' and specifying the resource type. It differentiates from the sibling 'grant_agent_project_access' by focusing on existing access modification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides 'Use when' and 'Do not use when' conditions, including prerequisites like authenticated authority and selected project. It also mentions alternative scopes and user consent, guiding appropriate tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds further context: 'Effect: read', human approval not required, post-call steps (follow typed result state, review proposals), and detailed failure handling. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is relatively long (95 words) but well-structured with explicit sections (Use when, Do not use when, Requires, etc.). It is front-loaded with the core purpose. Minor verbosity reduces conciseness, but overall acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, the description covers all necessary aspects: purpose, usage boundaries, prerequisites, effects, post-call actions, and failure modes. An output schema exists, so return values are not needed in description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100%. Baseline is 4 as per rules. Description adds no param info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'authenticated Abyss principal classification and team onboarding summary', which is a specific verb and resource. It distinguishes itself from sibling tools like 'auth_status' and 'team_onboarding_status' by specifying the combination of principal classification and onboarding.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit sections for 'Use when' and 'Do not use when' provide clear guidance on appropriate contexts. Also specifies requirements ('authenticated API authority'), effects, and even failure handling patterns, leaving no ambiguity about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, non-destructive), the description adds 'Effect: read', 'Human approval not required', and detailed failure recovery steps (login_required, project_not_selected, etc.), providing richer 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with labeled sections (Use when, Do not use when, Requires, Effect, etc.) and front-loaded with the core purpose. Every sentence is necessary and contributes to clarity without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, existence of output schema, many sibling tools), the description covers purpose, usage conditions, prerequisites, effects, failure modes, and follow-up actions. The presence of output schema means return values are handled externally, so the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage (only projectId described in schema), the description compensates by explaining format (Markdown vs JSON) and the meaning of pageId and subtree through the main use line. This adds value beyond the schema, though not all parameters are explicitly detailed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Export' and the resources (Project Wiki, Page, subtree) and formats (Markdown, JSON). It distinguishes from sibling tools like get_wiki_page or list_wiki_pages by specifying the export functionality and the option to export hierarchy or manifest.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides 'Use when' and 'Do not use when' conditions, including when a narrower tool is better. It also lists prerequisites (authenticated authority, selected project) and failure handling, guiding the agent effectively.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=false, indicating a safe read operation. The description adds value by confirming 'Effect: read', stating human approval is not required, and detailing on-failure behaviors (login_required, project_not_selected, permission_denied, etc.), providing behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using clear section headings ('Use when:', 'Do not use when:', etc.). Every sentence adds value, and the core purpose is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters with full schema coverage, existing annotations, and an output schema, the description is complete. It covers usage context, prerequisites, failure scenarios, and next steps, leaving no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context by clarifying that projectId defaults to the selected project and that pagination parameters are optional. This additional meaning justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists draft checkpoints for a selected project before they are committed or discarded. It uses a specific verb ('list') and resource ('draft checkpoints'), distinguishing it from sibling tools like commit_checkpoint and discard_checkpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use ('List draft checkpoints for the selected project') and when-not-to-use instructions ('a narrower tool better matches the intent, the project scope is unresolved, or the user has declined the action'). It also lists requirements (authenticated API authority, selected project) and human approval info, giving clear guidance on when to invoke 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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![abyss-mcp MCP server](https://glama.ai/mcp/servers/my-abyss-project/abyss-mcp/badges/card.svg)](https://glama.ai/mcp/servers/my-abyss-project/abyss-mcp)

Score Badge

Copy to your README.md:

[![abyss-mcp MCP server](https://glama.ai/mcp/servers/my-abyss-project/abyss-mcp/badges/score.svg)](https://glama.ai/mcp/servers/my-abyss-project/abyss-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/my-abyss-project/abyss-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server