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

Describes persistence behavior beyond annotations: features are persisted, user stories and criteria are not. Mentions return value (sessionId) and polling. 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?

Single concise paragraph with front-loaded main action. Every sentence adds value. Could be slightly more structured with bullet points for clarity, but overall 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?

No output schema, but description explicitly states returns sessionId. Covers the full workflow: scan, poll, then create user stories/criteria. Sufficient for agent to understand purpose and follow-up steps.

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 4 parameters with descriptions for 2 (50%). Description adds context for localPath ('local codebase') and projectId, but does not elaborate on depth or taskTitle beyond their defaults. Adequate but not excellent.

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 scans a local codebase and submits to VibeMap for reverse engineering, specifying that FEATURES persist but user stories and criteria do not. Distinguishes from siblings by naming specific tools for follow-up actions.

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 instructs to poll status after feature generation and then use vibemap_create_user_story and vibemap_create_acceptance_criterion. Provides clear workflow guidance but does not explicitly state when not to use this tool.

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

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

Annotations are neutral (no contradicting hints). Description adds the status transition detail but does not disclose potential side effects, reversibility, or impact on linked data. Adequate but not rich.

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

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

Two concise sentences, first sentence states the action, second provides usage context. No superfluous text.

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 status-transition tool with no output schema, the description covers the primary purpose and usage scenario. However, it lacks details on prerequisites (e.g., criterion must exist, current status check) and behavior on invalid inputs.

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 33% (only 'reason' has description). The tool description does not add any parameter-level detail beyond the schema, failing 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 ('Mark a criterion as blocked') and specifies the state transition ('any-active-status → blocked'). Differentiates from sibling 'vibemap_unblock_criterion'.

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 the tool: 'when external dependency, ambiguity, or environmental issue prevents progress.' Does not mention when not to use or alternatives, but context suggests sibling handles the reverse.

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?

Describes atomic claim with state transition and race condition (409). No annotations contradictions; adds value beyond annotations by detailing behavior.

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

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

Two short, front-loaded sentences with no wasted words. 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?

For a simple tool with one parameter and no output schema, the description covers the essential behavior, race condition, and state transition 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 coverage is 100% with one parameter described as 'Acceptance criterion UUID'. Description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states the action (atomically claim), resource (acceptance criterion), purpose (for implementation), and effect (transition ready → in_progress). Distinguishes from sibling tools like update or create.

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?

Implies when to use (claiming a criterion for implementation) and mentions race condition (409). Lacks explicit when-not-to-use or alternatives, but context is clear.

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

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

Annotations indicate a write operation (readOnlyHint=false) and non-idempotent behavior. The description adds that it creates in BDD format and can be called multiple times, but does not detail side effects, return value, or prerequisites beyond the schema. The added context is useful but not exhaustive.

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

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

The description is three sentences with no fluff. It front-loads the core purpose and provides additional usage guidance concisely.

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 7 parameters and no output schema, the description explains usage and parameter mapping but does not mention the return value (e.g., the created criterion's ID) or prerequisites (e.g., story existence). This leaves some gaps for an agent to infer.

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 71% schema description coverage, the description adds value by linking the BDD format to the givenCondition, whenAction, and thenOutcome parameters, and mapping scenarioCategory to happy path, error cases, and edge cases. This goes beyond the schema's basic descriptions.

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

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

The description explicitly states it creates an acceptance criterion for a user story in BDD format (Given/When/Then), which is a specific verb and resource. This clearly distinguishes it from sibling tools like list, update, or delete.

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 advises using the tool to flesh out 'done' before or during implementation, and explicitly mentions it can be called multiple times for happy path, error cases, and edge cases. However, it does not explicitly state when not to use it or point to alternatives, though the sibling list provides 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 indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description consistently says 'Create' but adds no extra behavioral context (e.g., whether duplicate names are allowed, required permissions, return value). With annotations already present, the description adds minimal transparency beyond stating the action.

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

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

Two sentences, front-loaded with the verb and resource. The first sentence declares the core action, and the second adds targeted usage context. No superfluous words or repetition.

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

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

The tool has 8 parameters, no output schema, and a meaningful sibling set. The description only states creation and a narrow use case, omitting details about the feature entity, relationships to other VibeMap constructs, or how parameters affect behavior. The description is insufficient for an agent to use the tool confidently without additional knowledge.

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

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

The schema has 0% description coverage for parameters, and the description does not explain any parameter meaning, defaults, or required fields. Despite 8 parameters including enums and a required projectId and name, the description offers no guidance, forcing the agent to infer from names 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 new feature in a VibeMap project' with a specific verb and resource. It distinguishes from sibling tools like list_features and update_feature by providing context: 'Use this when reverse-engineering a codebase to register discovered capabilities.'

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

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

The description gives a specific use case ('when reverse-engineering a codebase to register discovered capabilities'), which helps the agent decide when to invoke this tool. While it doesn't explicitly state when not to use it or list alternatives, the context is clear and largely sufficient among the siblings.

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

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

Annotations provide no hints (readOnlyHint=false, etc.), so the description carries the burden. It does not mention any behavioral traits like idempotency, side effects, or conflict handling. For a creation tool, it's adequate but lacks detail.

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

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

Two sentences, front-loaded with the primary purpose. Each sentence adds information (action, usage context, next step) with no redundancy.

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

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

The description covers creation and the next step. It mentions returning a project ID implicitly. Without an output schema, the return format is not detailed, but the tool is simple enough that this is acceptable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by saying 'The more detail, the better the AI analysis' for the description parameter, which helps the agent understand its importance.

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 new VibeMap project' with a specific verb and resource. It also distinguishes from siblings by noting the workflow: after creation, call vibemap_analyze_codebase.

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 'Use this when starting from an existing codebase' and gives the next step ('then call vibemap_analyze_codebase with the returned project ID'). While it doesn't state when not to use, the guidance is clear and actionable.

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

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

Annotations indicate a write operation (readOnlyHint=false) but not destructive. The description adds that it creates a story 'inside a VibeMap feature,' providing some context. However, it does not disclose potential side effects, required permissions, error conditions, or rate limits. With annotations only providing basic info, this is adequate but not rich.

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

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

The description is two sentences long, direct, and somewhat front-loaded. Every word adds value. It could be slightly more structured (e.g., listing required inputs), but it avoids fluff and is 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 8 parameters, 3 required, no output schema, and low schema coverage, the description is too brief. It does not explain the purpose of user stories in VibeMap, how they relate to features, what the tool returns (likely an ID), or any constraints. More completeness is needed for an agent to use it correctly.

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

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

Schema description coverage is low (38%). The description adds meaning for userRole, iWantTo, and soThat by naming them as 'role, action, and expected outcome.' But it omits explanation of required parameters like featureId, title, description, and optional ones like priority and estimatedEffort. The description does not compensate sufficiently 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?

The description clearly states 'Create a new user story' which is a specific verb and resource. It mentions 'user role, action, and expected outcome' which map to userRole, iWantTo, and soThat parameters. However, it does not differentiate from sibling tools like vibemap_update_user_story, but the verb 'create' is unambiguous.

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

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

The description provides basic instructions ('Provide the user role, action, and expected outcome') but no explicit guidance on when to use this tool versus alternatives like vibemap_update_user_story or vibemap_list_user_stories. No 'when not to use' or prerequisite conditions are mentioned.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by detailing what is stripped (Kanban metadata, PM narrative) and what is included, providing behavioral context beyond the annotations.

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

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

Three sentences with clear front-loading: first sentence states action and result, second adds detail, third gives usage guidance. No unnecessary words; every sentence earns its place.

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

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

Given the single parameter with full schema coverage and no output schema, the description provides the key purpose, differentiation, and usage guidance. It could describe the return format but is sufficient for the intended use case.

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 a single parameter (projectId) described as 'The VibeMap project ID'. The tool description does not add any additional meaning or constraints beyond the schema's description, so baseline 3 applies.

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

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

The description clearly states the tool retrieves a 'code-shaped atomic blueprint' with specific elements (relationships, synthesized interactions, entity state machines) and explicitly distinguishes it from the sibling tool vibemap_get_project_context.

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 advises to prefer this tool over vibemap_get_project_context when generating code, and explains it omits PM narrative/process metadata for better signal-per-token, giving clear when-to-use guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable context: it reveals the content of the response (draft|confirmed status, nodes/edges, sync anchor, drift report) and hints at curation preservation. 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?

Two sentences, front-loaded with purpose and details. No wasted words; 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?

For a simple read tool with one parameter and no output schema, the description covers purpose, content, and usage context. Missing are error handling or prerequisites, but the low complexity makes it adequate.

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

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

The schema has one parameter (projectId) with 0% description coverage. The description does not elaborate on projectId's meaning or format. Although the parameter is simple, the lack of compensation for low schema coverage results in inadequate guidance.

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

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

The description clearly states 'Fetch the project's current code map' and specifies included elements (status, nodes/edges, sync anchor, drift report). It distinguishes the tool by resource type ('code map') from siblings like get_project_context or get_atomic_blueprint, but does not explicitly differentiate.

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: 'Use before re-submitting to preserve the user's hidden-node curation.' This gives clear context for when to use the tool, but does not mention when not to use or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds the fact that it polls status (idempotent read), but does not elaborate on polling frequency, retry behavior, or potential return values. With annotations covering the core safety traits, the description adds modest value.

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

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

Two sentences, each essential: the first defines the purpose, the second specifies the input source. No wasted words, information is front-loaded.

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

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

The description is minimally complete for a simple polling tool with good annotations and schema. However, it lacks details on the response format (possible statuses, error conditions). Given the simplicity and the presence of readOnlyHint, a score of 3 is appropriate; it works but could be more thorough.

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% (one parameter fully described). The description adds value by specifying that the sessionId comes from vibemap_analyze_codebase, which is not in the schema. This is helpful context 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 explicitly states it polls status of a VibeMap AI generation task (reverse engineering or spec generation), using a sessionId. This is a specific verb+resource, and it differentiates from sibling tools which do other operations like listing, creating, or scanning.

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

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

The description clearly indicates when to use: after vibemap_analyze_codebase returns a sessionId. It provides a direct relation to the initiating tool, offering clear context. It does not explicitly mention when not to use or alternatives, but there are no alternative polling tools among siblings, so the guidance is sufficient.

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, so the description's mention of 'real-time' adds some context but does not significantly expand on behavioral traits beyond what annotations provide. It lacks details on caching, rate limits, or response size.

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

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

Two concise sentences, front-loading the core functionality. No extraneous words; 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?

For a read-only query tool with no output schema, the description explains the output structure (grouped by status columns, features with stories nested). It is complete for its moderate complexity, though it could mention if there are limits on the number of results or ordering.

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 coverage at 50% (only includeCriteria has a description in schema), the description does not add meaning beyond what the schema provides for projectId. The description's mention of 'features with their stories nested' hints at what includeCriteria affects, but this is not explicit. 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?

Description clearly states 'Get a real-time kanban board view of a project grouped by status columns. Shows features with their stories nested underneath.' This uses a specific verb ('Get') and resource ('kanban board view'), and the mention of 'status columns' and 'nested' differentiates it from other list/get tools among siblings.

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

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

The description says 'Ideal for an IDE agent to understand what's planned, in progress, and done,' which provides clear context for when to use the tool. However, it does not explicitly state when not to use it or name alternatives like vibemap_list_features or vibemap_get_project_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 confirm read-only and non-destructive behavior. The description adds valuable context: it returns the highest-priority ready criterion or null, and implies priority ordering. This goes beyond the annotations.

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

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

Two sentences, no fluff. The key information (purpose, behavior, return value) is front-loaded and concise. Every word earns its place.

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

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

For a simple retrieval tool with one parameter and clear output (criterion or null), the description is complete. It doesn't need an output schema or extra detail.

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 'Project UUID' description. The description confirms that projectId is the project identifier but adds no additional 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 it retrieves the highest-priority ready acceptance criterion for a project, with a clear verb (Get), resource (acceptance criterion), and scope (for a given project, only ready status). This distinguishes it from sibling tools like 'vibemap_list_acceptance_criteria' (lists all) and 'vibemap_claim_criterion' (claims a specific one).

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 this tool: to find the next criterion to work on. It implies that if no criterion is ready, it returns null, which is a clear usage cue. It could improve by noting sibling tools but already provides good 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 indicate readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds value by specifying that the tool returns both the page's own source_code and each section's source_code, which is not in annotations. 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?

Two sentences: first clearly states action and purpose, second elaborates on return content and use case. No redundant or unnecessary text.

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?

Without an output schema, the description adequately explains what is returned (source_code of page and sections). The tool has only two required parameters, both well-documented in schema, so no additional context is needed.

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

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

Schema coverage is 100% with clear descriptions for both required parameters (pageId, projectId). The description adds minimal extra meaning beyond the schema, but matches the baseline for high schema coverage.

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

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

The description uses a specific verb ('Retrieve') and resource ('VibeMap page's generated source code'), stating the outcome ('pull it straight into a repo'). It distinguishes from sibling tools by focusing on exporting source code, which is not mentioned elsewhere.

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 'Use this to export a generated page into your codebase instead of copy-pasting', providing clear usage context. It does not explicitly list when not to use or name alternatives, but the purpose is sufficiently differentiated from siblings.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description carries less burden. It adds that the tool retrieves context and lists included components, which is consistent. No behavioral surprises are omitted for a read-only retrieval tool.

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

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

The description is two sentences with no unnecessary words. The first sentence defines the action and content, the second provides context for use. This is front-loaded and efficiently communicates the tool's 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?

The description informs what the tool returns (project context with listed components) but does not address the output format or structure, which is absent from the output schema. It also fails to explain the boolean parameters' role in filtering. For a tool with 6 parameters, more detail is needed for complete understanding.

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?

Only one of six parameters (projectId) has a schema description; the five boolean parameters lack description. The description mentions they 'include' components but does not explain their effect on the response. With 17% schema coverage, the description fails to compensate, leaving agents uncertain about parameter usage.

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

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

The description uses specific verb 'Retrieve' and resource 'full context of a VibeMap project', listing included components (features, user stories, personas, pages, database schema). This clearly distinguishes it from sibling list tools that focus on sub-resources. The usage guidance 'Use this before building a feature' reinforces the tool's role.

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

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

The description explicitly states when to use the tool: 'before building a feature to understand all the specs.' It implies that for specific details, one should use the corresponding list tools, though it doesn't name alternatives. This provides clear context for selection.

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

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

Annotations already declare readOnlyHint and destructiveHint. Description adds return format detail (BDD, status), but lacks info on rate limits, auth, or edge cases. Adequate but minimal extra.

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

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

Two sentences, front-loaded with action and resource, efficient with no filler.

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

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

Despite no output schema, description is too sparse given 6 parameters and no param docs. Fails to explain pagination or filtering behavior, which is essential for correct 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?

Schema coverage is 0%; description only hints at storyId/featureId/projectId through 'for a story, feature, or project'. No explanation of limit, offset, or status enum. Leaves most parameters undocumented.

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 lists acceptance criteria for story/feature/project, with return format (BDD Given/When/Then with status). Differentiates from sibling create/update 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?

No explicit guidance on when to use this tool vs alternatives. Sibling names imply read vs write, but description offers no context on selection criteria.

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

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

The description goes beyond the annotations (readOnlyHint, destructiveHint) by detailing the exact contents of the response: table-level rules per persona/role with CRUD flags and structured predicates, page-level rules with predicates, and an advisory reconciliation summary. This fully discloses the tool's output behavior.

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

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

The description is informative but somewhat lengthy. It front-loads the core action and then provides details in a structured manner. While every sentence adds value, it could be slightly more concise 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 the tool's complexity (listing two types of access rules plus a reconciliation summary) and the absence of an output schema, the description thoroughly explains what the user can expect. It also provides context on why this tool is needed over its sibling, making it complete for safe 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?

With 100% schema description coverage for the single parameter 'projectId', the description does not add extra semantic details beyond 'The VibeMap project ID'. The baseline score of 3 is appropriate as the schema already provides sufficient 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 it lists a VibeMap project's access-control rules, detailing table-level and page-level rules with specific permissions and predicates. It distinguishes itself from the sibling 'vibemap_get_atomic_blueprint' by noting that this tool provides table-level access control missing from the blueprint.

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 tells when to use the tool: 'to generate correct RLS policies and route/UI authorization' and contrasts it with the atomic blueprint which 'only carries page-level conditions'. This provides clear guidance on its purpose relative to 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 declare readOnlyHint=true and destructiveHint=false, which is consistent. The description adds that every write is wrapped in a changeset and explains the effect of includeOps parameter. It also discloses the ordering (most recent first) and the per-changeset op count, providing useful behavioral context beyond the annotations.

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

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

Two sentences: first introduces the core function and key feature, second adds usage context and optional parameter. Every sentence is informative and well-structured, front-loading the essential 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?

The description thoroughly covers the tool's purpose, usage scenarios, parameter details (including defaults and ranges), and what the output contains (changesets with op count, optionally with inline ops). For a read-only list tool with three parameters and no output schema, this is complete and sufficient for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning: limit specifies range and default, projectId identifies project, and includeOps explains what inlining operations does. This goes beyond the schema's brief descriptions, adding value for the agent.

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 lists changesets for a VibeMap project, ordered most recent first, with a per-changeset operation count. The verb 'list' and resource 'changesets' are specific, and it is distinct from sibling tools like vibemap_list_projects or vibemap_list_features.

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

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

The description provides explicit usage scenarios: seeing changesets from own edits, auditing changes, or reviewing edit history. While it doesn't name alternatives, the context is clear and helpful for an agent to decide when to invoke this tool.

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

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

Annotations already indicate the tool is read-only and non-destructive. The description adds that results are paginated and supports filtering, which provides additional useful context but does not go into deeper behavioral details like sorting or rate limits.

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

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

Two sentences with efficient placement of the core purpose first and supporting details second. No unnecessary words; 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?

Despite having 7 parameters and no output schema, the description only covers filtering and pagination. It does not describe the structure of returned data (e.g., which fields are included), which is a gap for comprehensive understanding. Adequate but not fully 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 0%, so the description bears full responsibility. It explains filtering by status, priority, category, and search, and mentions pagination (limit/offset). While it doesn't describe each parameter in detail, it adds meaning beyond the raw schema, especially for the enum-based filters.

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 'List features for a VibeMap project,' using a specific verb and resource. It distinguishes from sibling list tools (e.g., vibemap_list_projects, vibemap_list_user_stories) by explicitly targeting 'features'.

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

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

It provides clear context on when to use the tool, mentioning filtering capabilities and pagination. However, it does not explicitly state when not to use it or compare to alternatives, though the uniqueness of the purpose makes exclusions less critical.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, which the description does not contradict. The description adds ordering behavior ('newest first') and the purpose of the `since` parameter, but it does not disclose other behavioral traits like pagination behavior beyond the limit parameter, rate limits, or the event structure.

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

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

The description consists of two sentences, each providing essential information without redundancy. The first sentence states the primary function and ordering, and the second sentence gives a key usage guideline. Every word earns its place, making it highly efficient.

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

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

For a simple list tool with no output schema and 3 parameters, the description adequately covers the primary purpose, ordering, and a key parameter use case. It is sufficient for an agent to understand and invoke the tool correctly, though additional details about event structure or pagination would enhance 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 description coverage is 67% (2 of 3 parameters have descriptions). The description adds value by explaining that `since` is for reconnect-backfill, which goes beyond the schema's 'ISO timestamp; only events strictly after this are returned.' However, the `projectId` parameter lacks any description in both schema and tool description, leaving its semantics unclear.

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 kanban transition events for a project, newest first. The verb 'list' and resource 'kanban transition events' are specific, making the purpose unambiguous. However, it does not explicitly differentiate from sibling tools like vibemap_get_kanban_board, which might provide similar data in a different format.

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

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

The description provides a usage hint for the `since` parameter ('for reconnect-backfill'), which guides when to use it. However, it lacks guidance on when to prefer this tool over alternatives such as vibemap_list_changesets or vibemap_get_kanban_board, leaving the agent to infer the appropriate 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 declare readOnlyHint=true and destructiveHint=false, which the description aligns with. The description adds no further behavioral context beyond stating the return values, which is adequate but not exceptional.

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

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

The description is two concise sentences: the first states the action and scope, the second lists returned fields. No unnecessary words, highly 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 the tool has no parameters and annotations cover safety, the description fully informs the agent what the tool does and what it returns. 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?

The input schema has zero parameters, and schema description coverage is 100%. With no parameters to describe, the baseline is 4, and the description does not need to add parameter specifics. It appropriately focuses on purpose and output.

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 'all VibeMap projects for the authenticated user', and specifies the returned fields (IDs, names, descriptions, status). This distinguishes it from sibling tools that list other entities like features or user stories.

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

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

The description implies this is the tool to use for listing projects. While it does not explicitly state when not to use it or alternatives, the context is clear given the tool's simple list function and no sibling tool duplicates this purpose.

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 that results are paginated and contain full story detail, providing useful behavioral context beyond annotations.

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

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

Two sentences, to the point. Could be more structured but no verbosity.

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 and no output schema, the description covers the key behaviors (paginated, full detail, filtering) but omits sorting order or maximum limit. Adequately complete for a list tool.

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

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

Schema description coverage is low (29%). The description mentions filtering by status and priority, adding meaning for those two enums, but does not explain limit, offset, or search parameters. Partial compensation.

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 user stories for a project or feature, with filtering and pagination. It distinguishes from siblings like create/update by focusing on reading.

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

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

The description implies use for listing user stories but does not explicitly state when to use this tool vs alternatives (e.g., using vibemap_list_features first). No when-not-to-use guidance.

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

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

Annotations already indicate non-destructive mutation (readOnlyHint false, destructiveHint false). The description adds that it appends without changing status, but omits details like side effects, prerequisites, or reversibility. The added value is moderate.

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

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

Two concise sentences with no redundancy. First states core function, second provides usage context. Every word 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?

For a two-parameter tool without output schema, the description covers purpose and effect but lacks parameter explanation and behavioral nuance (e.g., prerequisites, response). It is minimally adequate.

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

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

Schema coverage is 50% (only 'summary' has a description). The description does not clarify 'criterionId', which remains undocumented. The agent must infer its meaning, which is insufficient compensation for the schema 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 verb 'append' and resource 'criterion timeline', and explicitly distinguishes it from status-changing tools by noting it does not change status. This differentiates it from siblings like vibemap_update_kanban_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 implies use for surfacing intermediate work without status change, but does not explicitly state when to use vs. alternatives or provide exclusions. No direct comparison to sibling tools is given.

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

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

The description adds useful behavioral context beyond annotations: it specifies required token type and agent restrictions. Annotations are all false, so no contradiction. However, it does not mention whether the transition is reversible or what happens on failure, leaving some gaps.

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

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

The description is two sentences, concise and front-loaded with the core purpose, then adds the critical usage note. Every sentence earns its place with no redundancy.

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

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

Given the tool has 4 parameters, no output schema, and annotations that are all false, the description covers the main action and auth constraints but omits parameter semantics and return value. It is adequate but incomplete for confident 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?

With 0% schema description coverage, the description must explain parameters. It only implicitly mentions 'criterionId' and 'outcome' but does not describe 'notes' or 'testRunUrl'. This fails to add meaning beyond the schema structure.

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 resolves a criterion in review and transitions from 'in_review' to 'passed' or 'failed'. It provides a specific verb ('resolve') and resource ('criterion in review'), distinguishing it from siblings like 'submit_for_review' or 'claim_criterion'.

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 notes that agents cannot self-resolve their own work and requires a CI-scoped token or session user. This provides clear when-not-to-use guidance and prerequisites, effectively differentiating usage from other tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds value by specifying the output format (tree view + statistics) without contradicting annotations.

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

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

Two sentences, front-loaded with purpose and output, no redundant information—every word earns its place.

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

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

The description mentions the output format (tree view, file statistics) in the absence of an output schema, providing sufficient context for a scanning tool, though more structural detail could help.

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 descriptions for both parameters; the description adds no additional meaning beyond what the schema provides, meeting the baseline.

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

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

The description clearly states the tool scans a local directory and returns a formatted tree view and file statistics, distinguishing it from sibling tools like vibemap_analyze_codebase by focusing on directory structure exploration.

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

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

The description gives explicit context ('before syncing to VibeMap') and implies a preparatory use case, though it does not explicitly exclude alternative scenarios or mention when not to use it.

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

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

Annotations indicate a write operation (readOnlyHint=false) but non-destructive. The description adds critical behavioral info: re-submitting replaces the map and resets to draft, max 500 nodes, and aggregation rules.

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?

Front-loaded with purpose; well-structured but slightly long. Every sentence adds value though it could be condensed.

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?

Missing expected output/response behavior (e.g., success indication). No output schema. For a submission tool, the return value or confirmation should be described.

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% but descriptions are minimal. The narrative description greatly enriches parameter meaning: explaining node/edge kinds, ids, layers, and aggregation policy.

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 submits a structural code map, defines what constitutes a map (nodes/edges with constraints), and differentiates from sibling 'vibemap_scan_codebase' by specifying 'Build it yourself'. It also notes that re-submitting replaces the previous map.

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 implicitly tells when to use (when you want to manually provide a map) and contrasts with automated scanning. However, it does not explicitly list alternatives or state when not to use.

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

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

Annotations already declare the tool as non-read-only, non-idempotent, and non-destructive. The description adds the specific state transition and required evidence, providing useful behavioral context beyond what annotations offer. No contradiction.

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

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

The description is two sentences long, front-loading the purpose and then providing key details. Every sentence adds value with no redundancy or fluff.

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

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

The description covers the action, state transition, and required parameters. It does not mention that the criterion must be in 'in_progress' state, but this is inferable. No output schema exists, so return values are not described, but the core behavior is well-specified.

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 75% with descriptions for gitSha, diffUrl, and notes. The description reinforces gitSha and diffUrl as required evidence, adding context beyond schema. However, criterionId remains undescribed in both schema and description, leaving ambiguity about its role.

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 'Submit completed work for review' and specifies the exact state transition 'in_progress → in_review'. This distinguishes it from sibling tools like vibemap_resolve_review or vibemap_update_kanban_status, which handle different or broader state 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 says to use this tool when 'completed work' is ready for review, and lists required evidence (git SHA, diff URL). It does not mention alternative tools or when not to use it, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=false. The description adds workflow context but does not disclose additional behavioral traits beyond what annotations provide. No contradiction.

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

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

The description is informative but somewhat verbose. It front-loads the purpose and provides a structured workflow. Every sentence is useful, but could be slightly 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?

For a tool with 3 parameters and no output schema, the description is fairly complete: it explains the workflow, what the response contains ('lists affected map units and features'), and ties into sibling tools. Missing details on error cases or limits.

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

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

Schema coverage is 100% and the description's parameter explanations mirror the schema closely (e.g., 'repo-relative paths changed since anchor.commitSha (max 2000)'). The description adds no new semantics 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 reports codebase changes since last sync for VibeMap to flag spec drift. It uses a specific verb ('report') and resource ('codebase changes'), and the workflow distinguishes it from sibling tools.

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

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

The description provides a step-by-step workflow: call vibemap_get_code_map, run git diff, then call this tool. It also mentions follow-up tools for updates. However, it does not explicitly state when not to use this tool or discuss 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 provide minimal safety info (not read-only, not destructive, not idempotent). The description adds the state transition behavior, but lacks details on error conditions or prerequisites like the criterion needing to be blocked.

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

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

Single sentence that is front-loaded with the core action and immediately explains the state transition. No wasted words.

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

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

For a simple mutation tool without an output schema, the description covers the essential state change. However, it does not mention return value, error scenarios (e.g., criterion not found or not blocked), or prerequisites.

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 50% (only 'resolution' has a description). The tool description does not add any parameter-level detail beyond what the schema provides. 'criterionId' remains undocumented.

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 'Unblock' and the resource 'criterion', and explains the state transition from 'blocked' to 'prior_status'. This distinguishes it from the sibling tool 'vibemap_block_criterion'.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., when a criterion should be unblocked). The description relies on the tool name to imply usage.

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 non-readonly, idempotent, non-destructive. Description adds that it updates status or content, consistent with annotations. Does not disclose additional behaviors like side effects or required permissions.

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

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

Two sentences, each providing useful information. No wasted words. Efficient.

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

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

For a 7-parameter tool with no output schema, the description is too brief. It does not explain required parameters, the effect of updating different fields, or what the tool returns.

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 0% schema description coverage, the description barely compensates. It mentions 'status or content' but 'content' is ambiguous and doesn't map to specific parameters. No parameter details are provided.

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 that it updates an acceptance criterion's status or content. Provides specific examples of status values. However, it does not differentiate from sibling tools like block_criterion or unblock_criterion, which also modify criteria.

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 guidance on when to use 'passed' or 'failed' statuses. Lacks explicit when-not-to-use or alternatives (e.g., when to use create or block instead).

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, which the description does not contradict. However, the description adds no behavioral context beyond the annotations, such as auth requirements or side effects.

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

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

Extremely concise single sentence, no wasted words. However, it omits necessary details for a tool with 9 parameters, making it too brief.

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 9 parameters and no output schema, the description is insufficient. It does not explain return values, constraints (e.g., immutable fields), or how partial updates work, leaving the agent guessing.

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

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

With 0% schema description coverage, the description should explain parameter meanings but only mentions generic 'fields or status'. It does not clarify which fields are updatable, constraints, or relationships among them.

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

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

The description clearly states the verb 'Update' and the resource 'existing feature's fields or status' in VibeMap, distinguishing it from siblings like vibemap_create_feature and vibemap_list_features.

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

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

No guidance on when to use this tool versus other update tools (e.g., vibemap_update_user_story) or prerequisites. The description lacks context for when this tool is appropriate.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral context beyond annotations: it validates allowed state transitions, prevents invalid moves, and lists valid stage sequences for each entity type. No contradictions detected.

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

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

The description is concise (two sentences plus stage lists) and front-loaded with the deprecation warning. Every sentence serves a purpose: deprecation notice, atomic action, validation, usage context, and stage diagrams. Minor room for even tighter phrasing.

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

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

Given the tool's deprecation status and the absence of an output schema, the description covers all necessary context: why to avoid it, what it does, valid transitions, and entity types. It is complete for an agent to understand when and how to invoke it correctly.

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

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

Schema coverage is 100% (4 parameters documented). The description adds semantic value by enumerating allowed statuses per entity type (draft→open→in_progress→completed, etc.), which helps understand the newStatus parameter beyond its enum definition.

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: it atomically advances/updates the kanban status of features, stories, or criteria. It also distinguishes itself from sibling typed transition tools by explicitly deprecating itself and recommending alternatives.

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

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

The description provides explicit when-to-use guidance: 'Call this when you start or finish implementing something.' It also clearly states that the tool is deprecated and that typed transition tools should be used instead, offering strong usage boundaries.

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 does not disclose any behavioral traits beyond the annotations. It fails to mention that the update is partial (only provided fields change), authorization needs, or potential side effects. Annotations already mark it as idempotent and non-destructive, but no additional context is added.

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

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

The description is a single, concise sentence without waste. However, it lacks structured enumeration of parameters or examples, which would improve 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?

With 9 parameters, no output schema, and no parameter descriptions, the description is insufficient. It does not cover return values, error handling, or practical use context, making it incomplete for effective tool invocation.

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

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

Schema description coverage is 0%, and the description adds no meaning to the 9 parameters. Terms like 'soThat', 'iWantTo', and 'userRole' remain unexplained, leaving the agent to guess their purpose.

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

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

The description clearly states the verb 'Update' and the resource 'existing user story's fields or status in VibeMap', distinguishing it from sibling tools like create_user_story or list_user_stories.

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 lacks any guidance on when to use this tool, prerequisites (e.g., story must exist), or mentions of alternative tools for similar operations. Only a generic statement is provided.

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