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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.