Forge Engine

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

Beyond the annotation (destructiveHint=false), the description discloses a specific behavior: setting assignee to 'me' claims the task on creation. It also conveys that this is a DIRECT action, not a proposal, providing useful behavioral context.

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

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

The description is a single, compact sentence that conveys purpose and one key behavioral note. No filler words; every phrase 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?

With 9 parameters, no output schema, and only a minimal annotation, the description is under-specified. It does not explain how to choose between milestone/project_id/milestone_id, what effort/status/human mean beyond schema snippets, or what happens on success/failure, leaving significant gaps for the 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?

The description adds minor nuance to the assignee parameter ('claims on creation'), but the schema already describes assignee as '"me" claims it'. With schema coverage at 56%, the description does little to clarify milestone selection (milestone vs milestone_id) or the meaning of status/effort, leaving gaps.

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 'Add' and the resource 'task to a milestone', making the core purpose unambiguous. 'DIRECT' distinguishes this from proposal-based sibling tools like propose_milestone or propose_task.

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 word 'DIRECT' implies this is the immediate, non-proposal path to create a task, which hints at usage vs propose_* siblings. However, it does not explicitly state when to use this tool over update_task or propose_* alternatives, nor does it specify exclusions.

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

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

The annotation destructiveHint=true already covers the destructive risk. The description adds 'keep first' and 'DIRECT' which provide some behavioral context beyond the annotation, but it does not disclose potential side effects (e.g., impact on references or why 'screen' is needed).

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

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

The description is a single sentence with no filler. It delivers the core action, scope, and safety warning efficiently, making it easy to parse.

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 destructive tool with 3 parameters and no output schema, the description is too sparse. It doesn't explain what 'entries' means in practice (milestones vs elements), how 'screen' filters deduplication, or what happens to duplicate children. The destructive hint and 'keep first' help, but significant context is missing.

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 67% but the description adds no parameter detail. 'kind' and 'screen' are explained in the schema, but 'project_id' is undocumented and the description doesn't clarify its role. The relationship between parameters is implicit at best.

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

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

The description clearly states a specific action ('Remove duplicate-named entries') with a defined outcome ('keep first'), distinguishing it from deletion tools like delete_entity. The 'DIRECT, destructive' qualifier further clarifies the nature of the operation.

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 no guidance on when to use this tool versus alternatives such as delete_entity or reorder. It only warns that it is destructive but does not explain scenarios (e.g., cleansing duplicate milestones before proposing new ones) or when to avoid 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?

The annotation only provides destructiveHint=true, which could mislead an agent into thinking the tool performs a destructive action. The description adds critical behavioral transparency by explaining 'nothing deleted now' and that the proposal goes to an Inbox for owner adoption. This goes beyond the annotation without contradicting it.

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

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

The description is a single sentence that packs purpose, mechanism, and parameter guidance into less than 20 words. Every part earns its place without redundancy or fluff.

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

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

The description captures the core function and the key non-destructive nuance, but it lacks information about what happens after the proposal is made (e.g., how to check status, withdraw it) and what the response looks like. Given the tool's complexity (6 parameters, a destructive metaphor), a brief mention of 'use withdraw_proposal to cancel' would improve completeness.

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

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

The input schema has a high description coverage (83%), so the baseline is 3. The description adds value by specifying that 'id preferred or exact name' and that 'flow_edge may use from+to', guiding the agent on which parameters to use in which scenarios. This is a meaningful addition 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's purpose: 'PROPOSE a delete', which is a specific verb+resource combination. It also distinguishes the tool from siblings by clarifying it does not perform an immediate deletion but creates a proposal ('→ Inbox; owner adopts; nothing deleted now').

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 clear usage context: it is for proposing a delete, not for immediate deletion. It also gives parameter usage guidance ('id preferred or exact name; flow_edge may use from+to'), but does not explicitly mention alternatives or 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?

The description contradicts the readOnlyHint annotation by describing the creation/placement of screens, elements, and edges, which are write operations. Additionally, it provides no details about side effects, permissions, or return behavior. This is a serious inconsistency.

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 brief and front-loaded with the purpose, but the 'steps + batch id' phrasing is cryptic. It is not overly verbose and earns a 4 for efficiency, though it could be clearer.

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 appears to be a complex batch orchestration, yet the description omits critical information such as how the batch id works, what the steps entail, what output to expect, and how project_id factors in. Without an output schema and with the annotation contradiction, the description is wholly inadequate 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 description does not explain the project_id parameter at all, and the schema has 0% description coverage. The mention of 'batch id' is ambiguous and may not correspond to project_id. The agent is left without meaningful parameter semantics.

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

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

The description clearly states the tool is a 'Recipe to design the UI from Systems' and describes a batch process of confirming canvas aspect and creating screens, placed elements, and edges. This distinctively separates it from individual proposal tools like propose_screen or propose_element. The 'user request only' qualifier adds scope.

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

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

The description implies usage when a user requests a batch UI design from systems, but does not explicitly name alternatives or state when not to use it. It mentions 'batch' and 'user request only' but lacks exclusionary guidance; the contrast with sibling proposal tools is implicit rather than 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?

The description aligns with the readOnlyHint annotation and adds slight context about returning 'EVALUATED values' and covering stat tables, boards, and scenarios. However, it does not explain what 'EVALUATED' means, how board omission behaves, or the return structure, leaving 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?

A single, front-loaded sentence with no filler. It efficiently conveys the resource and verb, though 'EVALUATED' and 'scenarios' are jargon-y, but that doesn't detract from 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?

The tool has no output schema and a sparse description. It doesn't explain the domain terms (Balance Lab, EVALUATED values, scenarios), the meaning of including or omitting board, or what 'schema only' means for include_rows. Despite the readOnly annotation, an agent would need more context 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?

The schema already describes board and include_rows, but project_id is undocumented. The description provides no parameter semantics, so it doesn't help disambiguate the undocumented parameter or add meaning beyond the schema.

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

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

The description uses the specific verb 'Read' and identifies the Balance Lab resource with sub-resources (stat tables, boards, scenarios). This clearly distinguishes it from sibling tools like propose_balance_board and propose_balance_table, which are proposal/write operations.

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

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

The description implies a read-only usage for retrieving Balance Lab data, but provides no explicit guidance on when to choose this over alternatives or any exclusion criteria. There's no mention of alternatives or when not to use it, so the agent must infer based on the 'Read' verb.

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?

Despite the readOnlyHint annotation, the description adds substantial behavioral context by enumerating the complete set of returned information: systems with goals/acceptance/build status, coupled systems, pending Inbox changes, recent decisions, open-rejection count, active users, recent_changes for session handoff, and a task to claim. This goes far beyond the annotation's simple safety hint.

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 information-dense and front-loaded with the powerful 'ONE-CALL orientation before you build' hook. While it's a single long sentence with arrows and plus signs that can be slightly cumbersome, every piece of information earns its place and the structure makes the flow of inputs to outputs 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?

For a tool with no output schema and complex return payload, this description thoroughly covers what the tool returns, including systems, build metadata, coupled systems, inbox changes, decisions, and recent_changes. The only omission is an explanation of project_id, but overall the description gives a complete picture of the tool's function and output.

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 description enriches the meaning of `files` (paths about to touch, mapped to systems) and `task` (briefs milestone systems), aligning with and expanding on the schema descriptions. However, `project_id` is left undocumented in both the schema and description, and with 67% coverage the description does not fully compensate for that 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 it provides a one-call orientation before building, accepting files or a task and returning owning systems with detailed context. It distinguishes from siblings by explicitly naming the get_project_meta→get_system→get_build_region dance it replaces, making its unique role obvious.

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

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

It explicitly says 'before you build' and instructs to pass files you're about to edit or a task. It also names the exact alternative multi-call sequence it replaces, giving clear when-to-use guidance and differentiation from sibling tools.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavioral context: pagination with 'page N of M' instructions, payload size note about acceptance criteria being omitted, and the effect of passing `system`. This exceeds what annotations alone provide, though it doesn't cover all possible edge cases.

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 four sentences, front-loaded with the map content and followed by usage tips. Each sentence contributes necessary information about drift handling, single-system mode, and pagination, though the phrasing is slightly dense with symbols like '→' and capitalizations.

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 tool with three optional parameters and no output schema, the description covers the returned fields, the special single-system payload, and pagination behavior. It is fairly complete, though the role of `project_id` remains ambiguous and no example is given.

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 describes `page` and `system` (67% coverage); the description enriches both by explaining the page continuation pattern and that `system` returns acceptance-criteria detail. However, `project_id` has no schema description and is not mentioned in the description, leaving a gap for that parameter.

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

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

The description clearly states the tool returns a system-to-code map with specific fields (implementing files, status, drift flag, last_commit, acceptance-evidence counts). It distinguishes from siblings by focusing on the build region map and explicitly pointing to report_drift for missing files. The purpose is specific, though it lacks an explicit verb like 'lists' or 'retrieves'.

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

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

It provides context on when to use the tool (when you need the system-to-code map) and directs to report_drift when mapped files are gone. It also explains the mode for querying a single system via the `system` parameter and pagination for large results. However, it doesn't explicitly contrast with other sibling getters like get_system or list_systems.

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 the description adds significant behavioral context beyond that: deterministic compilation, paging with 'part N of M' header and page parameter, inclusion of the project version, and the condensed summary projection mode. This fully discloses the tool's behavior.

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

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

The description is concise but information-dense: it covers purpose, use case, return format, paging behavior, and summary mode in four sentences. Each sentence earns its place with no redundancy or irrelevant detail, and the front-loaded main purpose is immediately 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 the tool's complexity (paging, summary projections, deterministic compilation), the description covers all essential aspects. It mentions the return type (markdown + version), paging mechanics, and the condensed form, making it fully self-sufficient for an agent to select and 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?

The schema already describes 'page' and 'for_summary', and the description adds deeper meaning (e.g., header indicates total parts, for_summary returns goal+boundary with tables stripped). The project_id parameter lacks schema description but is self-explanatory; overall the description compensates well for the 67% 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 specifies the tool's function: returning the entire design as a single readable markdown document compiled deterministically from the current design. It also distinguishes itself from siblings by explicitly contrasting with the alternative of walking list_systems then get_system repeatedly.

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 explicit context for when to use this tool: to understand a project end-to-end, and specifically recommends using for_summary:true for summarization. It also contrasts with the alternative approach of listing systems and fetching each one, giving clear guidance without ambiguity.

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 the description adds useful context by stating 'no project needed' and 'on demand', indicating this is a safe, immediate help lookup with no side effects. It does not add details about limitations or return format, but for a zero-parameter help tool, this is sufficient.

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

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

The description is two sentences, front-loaded with the core purpose, and uses compact examples. Every word earns its place, with no repetition or filler.

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

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

For a simple, zero-parameter help tool with read-only annotation, the description is complete: it states what it does, when to use it, and provides a list of covered topics. No output schema exists, but the return value is implicitly help content, which needs no further explanation.

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

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

The tool has zero parameters, so the schema fully covers parameters (100% coverage). The description does not need to explain parameter semantics, and the baseline for 0 params is 4, which is appropriate here.

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 provides on-demand Forge how-to content, listing specific topics like propose→adopt and Balance Lab formats. It also differentiates itself from sibling tools by noting 'no project needed', making its scope distinct from project-specific get_* 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 phrase 'Call when unsure' explicitly tells the agent when to use this tool. The note 'no project needed' implies it is not for project-specific queries, but no alternative tool is named explicitly, so it falls just short of a perfect score.

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

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

The readOnlyHint annotation already marks the operation as safe, but the description adds valuable behavioral context: it describes the content (decisions/logs/rejections), the associated metadata (who/when), and the meaning of an empty result. The warning 'don't invent one' is a critical behavioral caveat that goes beyond the annotation. No contradiction.

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

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

The description is two sentences, front-loaded with a 'DESIGN MEMORY' label, and every word adds value. It covers content, usage, and empty-result semantics without fluff. This is exemplary 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?

Given the tool has 4 optional parameters, no output schema, and a single annotation, the description provides strong contextual coverage: it explains what the tool returns (who/when), when to use it, and how to interpret empty results. It does not detail return format or parameter relationships, but for a simple read tool, it is sufficiently complete. A slightly higher score would require more specific output structure or parameter interaction details.

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 already describes 3 of 4 parameters (limit, query, system) with useful details like defaults and formats. The description does not mention parameters, but with 75% schema coverage, it doesn't need to compensate. The 'system' parameter is indirectly tied to the usage text ('changing a system's direction'), but not explicitly explained. Overall, the description adds little parameter meaning, but the schema mostly covers it.

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 identifies the tool as retrieving design memory—recorded decisions, logs, and rejections with who/when. The phrase 'DESIGN MEMORY' and the explicit mention of 'recorded decisions/logs/rejections' distinguishes it from sibling tools like get_rejections, which focuses only on rejections. The purpose is specific and actionable.

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

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

The description states a clear usage trigger: 'Read BEFORE changing a system's direction.' This tells the agent when to invoke the tool. It also adds interpretive guidance ('empty = no recorded WHY — don't invent one'), but it does not name alternatives or explicitly state when not to use it. Still, the guidance is strong and context-rich.

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 the description does not contradict this. The description adds valuable behavioral context beyond the annotation by stating the operation is 'deterministic' and enumerating the blast radius components. It also implies a safety/caution aspect with 'Run BEFORE changing it,' which is extra context not provided by the 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 a single sentence, front-loaded with the memorable 'BLAST RADIUS' metaphor, followed by a colon-separated list of contents. Every word earns its place; there is no fluff, repetition, or unnecessary detail.

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 output schema, the description compensates by explicitly listing the categories of information returned (upstream context, siblings, dependent screens, files, code-coupled systems, pending inbox, recent activity). It also provides a clear usage trigger. The only missing piece is elaboration on parameter selection, but that is partially covered by the schema, so the description is adequate for correct 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 67%, with 'id' described as 'Preferred' and 'name' as 'If no id.' The tool description itself adds no parameter-specific semantics. 'project_id' remains undocumented in both schema and description, creating a minor gap. Overall, the schema does the heavy lifting for two of three parameters, but the description does not clarify the selection logic between 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 identifies the tool as a 'BLAST RADIUS' analysis for a system, listing the specific types of context it returns (upstream, siblings, dependent screens/milestones, files, code-coupled systems, pending Inbox, recent activity). This is a specific verb+resource (get impact of system) that distinguishes it from sibling get_* tools like get_system or get_screen.

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

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

The description gives explicit usage timing: 'Run BEFORE changing it.' This tells the agent when to invoke this tool as a pre-modification assessment. While it does not explicitly name alternative tools, the context is clear enough that an agent would understand this is for impact analysis before edits, not for general system information.

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 the description reinforces with 'Read-only.' It adds that this is the owner's triage queue and the workflow note about checking before proposing, which are useful cues beyond structured data, but it doesn't describe filtering, ordering, or behavior with project_id.

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 extremely brief and front-loaded: 'PENDING Inbox' conveys the core immediately. Every word serves a purpose, and the usage guidance is packed into two short clauses.

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 one optional parameter, it covers purpose and usage context well. However, the lack of parameter semantics and any hint about the returned data (e.g., a list of pending items) leaves ambiguity. It's 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?

The input schema has a single optional project_id with 0% description coverage, and the tool description does not mention it at all. An agent cannot know whether project_id scopes the inbox or is ignored, making the parameter semantics completely unexplained.

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 identifies the tool as the owner's pending inbox/triage queue, implying it retrieves pending items. It distinguishes itself from proposal-related siblings by framing it as a pre-proposal check, though it doesn't explicitly state the return 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?

It explicitly instructs to 'Check BEFORE proposing — avoid duplicates,' giving a clear when-to-use directive. It doesn't mention alternatives or exclusions, but the context strongly implies this is a prerequisite before proposing.

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

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

With readOnlyHint=true annotation, the safety profile is clear. The description adds value by disclosing the exact fields returned (goal, weeks, difficulty, systems, tasks with their attributes), which is useful behavioral context beyond the 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 a single, compact sentence that thoroughly captures the tool's output in a structured list. Every word earns its place, and the key phrase 'ONE milestone' 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?

For a simple read-only get tool with no output schema, the description sufficiently outlines the response contents. It does not describe error handling or ambiguity cases, but these are less critical given the schema's optional parameters and the tool's simplicity.

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%, and the schema already explains id as 'Preferred' and name as 'If no id'. The description does not add extra semantic meaning for parameters, including project_id which lacks a schema description. Baseline 3 is appropriate as schema does most of the work.

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 indicates the tool retrieves a single milestone ('ONE milestone') and enumerates its contents (goal, weeks, difficulty, systems, tasks). This distinguishes it from list_milestones, though the verb 'get' is only implied by the tool name.

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 a single milestone rather than a list, but does not explicitly state when to use it over siblings or mention alternatives. There is no guidance on parameter selection or prerequisites beyond the schema hints.

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 the description adds useful behavioral context: the response is 'LARGE' and this should be a 'last resort'. This goes beyond the structured annotation by warning about payload size and cost. It could have mentioned response format, but given the annotation coverage this is solid.

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

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

The entire description is one short, front-loaded sentence. 'FULL design dump — LARGE, last resort' immediately conveys the critical warning, and the preference for alternatives is stated compactly. 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?

Given the tool has no output schema and one parameter, the description should explain what 'full design dump' actually returns. It does tell the agent it's large and a last resort, which is useful, but it does not enumerate the content or behavior. The guidance is adequate for a simple parameter but leaves the output open-ended.

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 says nothing about the required 'project_id' parameter. With a single undocumented parameter, the description should at least confirm that 'project_id' identifies the project to dump, but it does not. The meaning is inferable from the name, but the description adds no value.

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 'FULL design dump' clearly identifies the tool as returning a comprehensive design/context payload for a project, and it distinguishes itself from siblings by explicitly recommending lighter-weight alternatives. Although it doesn't use the exact verb 'get', the resource and scope are unmistakable.

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 ('last resort') and provides concrete alternatives ('prefer get_project_meta + list_*/get_*/search'). This gives the agent clear decision guidance and differentiates from the sibling tools.

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

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

Annotations already mark it readOnlyHint=true, and the description adds context about using working_now to avoid collisions. It also mentions forge_workflow_version, providing versioning context. 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?

One short sentence with a clear 'START HERE' hook. Lists content compactly without padding.

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 one parameter and no output schema, the description lists the key return elements (counts, members, task claims, working_now, forge_workflow_version) and the purpose (avoid collisions). It doesn't explain what the counts are counts of, but for a 'Tiny overview' it's reasonably complete.

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

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

The only parameter project_id is self-explanatory, but the description doesn't mention it at all. With 0% schema description coverage, the description should clarify parameter usage or requirements, but it doesn't. The schema also marks project_id as not required, which is ambiguous.

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 lacks an explicit verb+resource phrase like 'retrieves project metadata'; instead it says 'Tiny overview' and lists contents. It does specify concrete elements (counts, members, working_now), but the verb is implied rather than stated.

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 says 'START HERE', signaling to use this tool first before others. Also mentions 'working_now (avoid collisions)', which hints at using this to check active tasks before claiming. No explicit alternatives, but the start-here directive is strong 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, so the safety profile is covered. Description adds that entries contain guidance and that the intended follow-up is resolve_rejection, but it does not explain what the list contains beyond 'DECLINED' or any limitations, so it's minimal.

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

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

The description is a single, front-loaded sentence: 'Owner's DECLINED list — check at session start; follow each entry's guidance, then resolve_rejection(title).' Every phrase serves a purpose and no redundant information is present.

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, the description provides purpose and usage, but it ignores the project_id parameter and doesn't describe the output format. Since there's no output schema, the description should explain what the list contains; it only says 'DECLINED list' and 'each entry's guidance', leaving some ambiguity.

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 has one optional parameter project_id with no description, and the description never mentions it. With 0% schema coverage, the description leaves the parameter's meaning entirely to inference, failing to add value.

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 identifies the tool as 'Owner's DECLINED list' and ties it to a session-start check, making the resource and action clear. The reference to resolve_rejection distinguishes it from related list tools like get_inbox.

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 'check at session start' and provides the workflow 'follow each entry's guidance, then resolve_rejection(title)', giving clear when-to-use context. Does not compare with alternatives but the directive is unambiguous.

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, so the safety profile is already known. The description adds behavioral detail about what is returned (layout elements, links, popups) and the conditional use of get_screen_image based on has_reference_image, going slightly beyond the 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?

Two sentences, front-loaded with the most important content ('ONE screen's layout'), and no filler. Every word earns its place while conveying the core purpose and an actionable pointer to get_screen_image.

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 strong annotations and no output schema, the description covers what is returned (resolution, elements, links, popups), the usage case, and the reference-image branch. It could mention error cases or id requirements, but for this complexity it is sufficiently complete.

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

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

The description does not mention or elaborate on any parameters. Schema coverage is 67% (id and name have descriptions, project_id does not), and the description fails to add meaning beyond the schema, such as when to use id vs name or the role of project_id.

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 ('get') and identifies the resource ('ONE screen's layout') with concrete contents (resolution, elements x/y/w/h, links, popups). It clearly distinguishes itself from siblings like list_screens and get_screen_image by emphasizing 'ONE screen' and the reference-image condition.

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 phrase 'Read before editing a screen' gives explicit when-to-use guidance. The instruction 'has_reference_image:true → get_screen_image shows you the actual image' points to an alternative when a reference image exists. However, there are no explicit when-not-to-use or exclusionary conditions.

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

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

With readOnlyHint already declaring the safe read nature, the description adds meaningful context: it reads the stored file inline and falls back to a signed URL past 4MB. This goes beyond the annotation by clarifying the delivery mechanism and response format.

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

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

A single sentence packs the core purpose, the image nature, and the storage/fallback behavior without redundancy. The structure front-loads the key purpose and uses a dashed aside for technical detail, making it easy to scan.

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 image retrieval, the description plus readOnlyHint covers the return mode and storage behavior. However, it lacks parameter usage guidance and does not fully compensate for the undocumented project_id or clarify how to select the correct screen when multiple parameters are available.

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%, with id and name described but project_id not. The tool description does not explain parameter relationships or selection precedence, leaving the undocumented project_id without compensation. The description adds no meaning beyond the schema's parameter hints.

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 indicates the tool retrieves a screen's reference image as a viewable image, with 'reads the stored file inline' providing a specific verb. It distinguishes itself from sibling get_screen by emphasizing the actual image output, though it lacks an explicit imperative verb.

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 phrase 'as an actual IMAGE you can see' implies when this tool should be used, but it does not explicitly state when to use it versus alternatives like get_screen or list_screens. No exclusions or alternative recommendations are provided, so usage guidance is only implied.

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 the readOnlyHint annotation, the description adds valuable behavioral context: 'computed deterministically (no AI, no tokens)' assures the user of zero cost and predictable output. It also details the return categories, which enriches the user's mental model.

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: it opens with the core idea, enumerates the three kinds, and ends with usage guidance. Every sentence contributes meaningful information without redundancy, and it remains readable despite its 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?

For a read-only tool with no output schema, the description adequately explains what the tool returns by naming the three kinds of drift. It lacks a precise output format (e.g., list of objects with fields), but the enumeration is sufficient for an agent to understand the tool's value and integration.

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 required-less parameter 'project_id' with 0% description coverage, and the description does not mention it at all. While the parameter is self-explanatory, the description fails to compensate for the low schema coverage, leaving the parameter's role implicit.

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 identifies the tool as returning a list of drift between the Idea lane and System Specs. It specifies three distinct kinds of stale items, making the purpose concrete and distinguishing it from sibling tools like report_drift or resync_from_idea.

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

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

It explicitly says 'Read this before assuming the design is coherent', giving a clear precondition for use. It also directs the user to resync_from_idea for fixing the first kind, naming an alternative tool and its 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 declare readOnlyHint=true, so the read-only nature is already disclosed. The description adds valuable behavioral context by specifying exactly what the return contains (full spec components plus pending Inbox changes). This goes beyond simple read-only confirmation and gives the agent a clear picture of the data scope.

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, tightly packed sentence that front-loads the core purpose ('ONE system's full spec') and then lists the included elements in parentheses. Every word adds value; there is no fluff or repetition.

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

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

Given the read-only annotation, 3 parameters, and no output schema, the description adequately explains what the tool returns. The mention of pending Inbox changes is an important contextual nuance. However, it doesn't clarify potential use cases or how to select between id/name/project_id, but those are partially covered in the schema. Overall complete for a retrieval 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 67%, with id and name having brief descriptions ('Preferred', 'If no id') but project_id undocumented. The tool description does not mention parameters at all, so it adds no additional meaning beyond the schema. The schema carries most of the parameter burden, and coverage is moderate; a 3 is appropriate.

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

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

The description uses a specific verb+resource construction: 'ONE system's full spec' clearly indicates this tool retrieves a single system's specification. It enumerates concrete contents (Goal/Boundary/Acceptance, markdown, sources, status) and additionally lists pending Inbox changes, distinguishing it from sibling tools like list_systems or get_screen.

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 sets context: it is for a single system's full spec, implying use when you need comprehensive system details including pending changes. It doesn't explicitly name alternatives, but the 'ONE system' qualifier differentiates from list_systems. No explicit exclusions or when-not-to-use guidance, hence not 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 contradicts the readOnlyHint annotation by stating it will 'ADD to AGENTS.md/CLAUDE.md', implying a write operation. This is a serious inconsistency, as the annotation indicates a safe read. The description also includes user interaction steps (tell user, remove if objected) which are behavioral but undermine the read-only claim.

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

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

The description is a single sentence that packs essential information: when to run, what to do, and how to handle user objections. It's front-loaded with 'Run FIRST' and contains no fluff, though it could be slightly clearer in structure.

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 no parameters and no output schema, the description provides a fair amount of behavioral guidance (new repo, add block, tell user). However, the contradiction with the readOnlyHint annotation leaves ambiguity about whether this is a read or write operation, and the 'first-connect routine' is not elaborated on. This prevents a higher score.

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?

There are no parameters in the schema, and the baseline for 0-param tools is 4. The description doesn't add parameter information, but there is nothing to document. Thus a score of 4 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's purpose: to run the first-connect routine and add a working-agreement block to AGENTS.md/CLAUDE.md in a new repo with no project. It uses specific verbs and context, distinguishing it from sibling get_* tools that retrieve information.

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

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

It explicitly says 'Run FIRST in a new repo (no project)', providing a clear condition for use. However, it does not explicitly mention alternatives or when not to use it, though the context implies it's only for initial setup.

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 that the tool only proposes items and that the owner adopts them, which is a key behavioral trait beyond the readOnlyHint annotation. It also adds that it creates one Context overview and one System per module. However, terms like 'recipe' and 'batch id' remain unexplained.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core action. However, the cryptic 'recipe + batch id' sacrifices clarity for brevity.

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 no output schema and only one parameter, the description fails to explain the parameter, the meaning of 'recipe' and 'batch id', or the adoption process. It is too high-level to enable correct invocation without additional 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?

The schema has one parameter (project_id) with 0% description coverage, and the description does not explain it. Instead, it introduces 'recipe' and 'batch id', which do not correspond to any schema parameter, leaving the agent without guidance on how to fill the parameter.

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

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

The description clearly states the tool's purpose: a one-command codebase import that proposes a Context overview and one System per real module. It distinguishes itself from sibling propose_* tools by emphasizing batch processing and owner adoption.

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 phrase 'one-command' and 'all at once' implies this is for bulk import scenarios, but there is no explicit guidance on when to use this tool versus manually calling propose_context or propose_system. Alternatives are not named or excluded.

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 the description adds useful behavioral context: newest-first ordering, returned fields, and filter capabilities. This enriches beyond the annotation 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?

A single, dense sentence packs essential information: output fields, ordering, and filters. No wasted words; front-loaded and easy to parse.

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 no output schema, the description compensates by listing the return fields and sort order. It omits pagination details, but the schema provides limit parameters, so overall context is adequate for a low-complexity 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?

The schema has good coverage (80%) with descriptions for most parameters. The description adds clarity by explicitly identifying kind, who, and query as filters, and implicitly excluding limit and project_id from filter semantics, aiding parameter selection.

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

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

The description clearly states the tool lists change history with specific fields (who, change, entity, kind, when) and sorts newest first. This specific verb+resource combination with field detail effectively distinguishes it from sibling tools like get_history.

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

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

The description implies usage via 'filter kind/who/query' but does not explicitly differentiate when to use this tool over alternatives like get_history. It lacks exclusionary guidance or alternative tool references.

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 the useful detail that the return is 'compact' and lists the response fields, but it fails to disclose whether project_id filters the results or if all milestones across all projects are returned. With readOnlyHint=true already covering safety, the description could add more context about scope and default 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 a single, tight phrase that conveys the core purpose and response format with no filler. It front-loads the key information and every word contributes 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 list tool with one optional parameter and no output schema, the description covers the response shape but omits parameter semantics and scope clarification. The lack of any mention of project_id's role makes it partially incomplete 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 0% and the description does not mention the project_id parameter at all. It only describes response fields, not how the parameter influences the result. This leaves the agent to guess whether project_id is required, optional, or what values it accepts.

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 returns all milestones in a compact format, listing the specific fields included (id, name, weeks, order, done/total). This distinguishes it from singular tools like get_milestone and mutation tools like propose_milestone, matching the list_* sibling pattern.

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

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

The description implies usage for retrieving an overview of all milestones, but it does not explicitly state when to use this tool versus alternatives like get_milestone for a single milestone or report_milestone_progress for progress updates. There is no mention of 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?

Discloses that the list is scoped to key access and includes role, but misleadingly suggests a project_id parameter not present in the schema. This creates a false behavioral expectation for the agent.

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 sentence that front-loads the core function. The second clause is awkwardly appended, but overall it is appropriately sized for the tool's simplicity.

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 exists, so the description carries responsibility for return values; it does list id, name, role and key scoping. However, the switching behavior is unexplained and the missing schema parameter leaves a gap in 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?

Input schema has zero parameters, so the baseline is 4, but the description invents a project_id parameter with no schema support. This is actively misleading and should be corrected or reflected in 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 resource (projects accessible by the key) and the response fields (id, name, role). However, the appended 'pass an id as project_id to switch' introduces a second action, muddying the primary purpose.

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

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

Provides a hint about switching projects by passing an id, but no explicit guidance on when to use this tool vs siblings like list_systems or get_project_context. The switch instruction is incomplete because the schema accepts no parameters.

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 readOnlyHint annotation covers the safety profile, and the description adds the return fields (id, name, purpose, status) and the 'compact' formatting. However, it does not disclose the effect of the optional project_id parameter or any pagination/ordering behavior, so transparency is limited.

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

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

The description is a single concise phrase, front-loaded with the resource and purpose. It is efficiently worded, though it uses a fragment rather than a complete sentence, and omits necessary parameter context.

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 is simple (1 optional param, no output schema), the description should at least clarify whether project_id filters the list and what 'all screens' means without it. The absence of this information leaves an incomplete picture for an agent to select and invoke the tool correctly.

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

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

The input schema has one parameter, project_id, with zero description coverage. The tool description does not mention this parameter at all, leaving its purpose and behavior completely unexplained. The description 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?

The description clearly states the tool lists all screens in a compact form, including id, name, purpose, and status. The resource 'screens' is specific and distinguishes it from sibling tools like get_screen (singular) and other list_* tools for different resources.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_screen or get_screen_image. It does not mention any filters, prerequisites, or exclusions, leaving the agent to infer usage from the name alone.

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

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

The readOnlyHint annotation already indicates a safe read operation, lowering the bar. The description adds that the output is compact with specific fields, but does not disclose behavior regarding the optional project_id parameter or any limits like pagination.

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

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

The description is a single, front-loaded sentence with no wasted words, effectively conveying the purpose and key output fields.

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 read-only annotation, the description covers return fields but fails to explain the project_id parameter or provide usage context. The missing parameter semantics and absence of an output schema leave moderate 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 one optional parameter (project_id) with 0% description coverage, and the description does not mention or explain it. The agent is left guessing whether it scopes results to a project or is ignored.

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 lists all systems in a compact format with id, name, status, and a one-line goal. This is a specific verb+resource combination that distinguishes it from siblings like get_system or list_projects.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of get_system for detailed system info, nor any explanation of how project_id filters results or when to omit 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?

The description discloses atomic claim behavior, ordering, skip rules, and the difference between normal and dry_run mode. This goes beyond the minimal annotations (destructiveHint false) by explaining concurrency safety and return values. 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 a single dense sentence that front-loads the tool's purpose and includes significant behavioral details. Every clause adds value, such as skip rules and return values, without 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?

For a complex dispatcher tool with no output schema, the description explains input (dry_run), behavior (atomic, ordered, skipping), and output (claimed task + systems or reason none free). It is sufficiently complete for an agent 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?

The schema describes dry_run as 'Peek without claiming', and the description reiterates this. However, project_id lacks any description in the schema, and the description does not explain its purpose or filtering behavior. With 50% schema_description_coverage, the description fails to compensate for the undocumented parameter.

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

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

The description clearly states the tool's function: atomically pick and claim the next task to build. It specifies the algorithm (walks milestones in order, skips human-only and conflicting tasks) and distinguishes it from siblings via the DISPATCHER label. This clearly separates it from tools like get_workflow or update_task.

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

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

The description implies usage in multi-agent scenarios via 'DISPATCHER (multi-agent)' and explains when tasks are skipped. However, it does not explicitly name alternative tools or give when-not-to-use guidance. Clear context but no exclusions.

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

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

Annotations only include destructiveHint: false, which is minimal. The description adds 'append' semantics and a non-destructive feel, but doesn't clarify side effects, idempotency, or whether it updates other state. Without a readOnlyHint, the write nature is clear from the verb but no deeper behavior is disclosed.

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

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

A single sentence, front-loaded with the core action and purpose. No redundant phrases or filler.

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

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

For a simple log-append tool, the description is sufficient: it states the action, target, and style. No output schema exists, but the return value is likely trivial. However, missing details about project_id and whether entity/version are needed could be a gap, hence not a 5.

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 75% (text, entity, version described; project_id missing). The description doesn't add parameter-level details beyond the schema. The 'commit-note style' hint aligns with text being short, but this is already implied in the schema's description.

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

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

The description uses a specific verb ('append') and resource ('build-log entry to Activity'), clearly stating what the tool does. The 'commit-note style' phrase adds useful context and helps distinguish it from broader reporting tools like report_build_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 when to use it (to log what you built/decided) but provides no explicit guidance on when not to use it or alternatives. Sibling tools like report_build_status or list_activity could serve related purposes, but no exclusions or comparisons 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?

Beyond the annotation destructiveHint=false, the description discloses key behaviors: proposals go to the Inbox, and if adopted, they replace any same-named board. This is critical context about the proposal lifecycle. It does not detail response formats or further side effects, but the annotation already covers the destructive safety aspect.

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 extremely concise—three short sentences covering purpose, node kinds, and adoption behavior. Every sentence adds unique value; no filler or repetition of schema fields. It is structured logically from function to details to side effect.

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 proposal tool with three parameters and no output schema, the description covers the main usage: target destination, node content, naming conventions, and replacement warning. Missing is any mention of the response or proposal ID, but the core operation 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?

The description adds substantial meaning to the 'nodes' parameter by specifying allowed kinds (const, formula, item, etc.), that formulas reference blocks by NAME, and that omitting x/y enables auto-layout. This goes beyond the schema's generic 'e.g. {kind...}' example. It does not clarify project_id, leaving a small gap, but the key content parameters are well explained.

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 proposes a node board into the Inbox, with a specific verb ('Propose') and resource ('node board'). The list of supported node kinds (const, formula, etc.) distinguishes this from other proposal tools like propose_balance_table, which targets a different format. Though it doesn't explicitly name siblings, the unique board focus makes purpose 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 implies when to use this tool: to propose a balance board composed of nodes, with formulas referencing blocks by name. It does not explicitly state when not to use it or mention alternative tools, but the context is clear for a proposal workflow. The '→ Inbox' phrase indicates it is for submitting proposals rather than direct edits.

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 behavioral traits: proposals go to Inbox, and adopting REPLACES same-named tables. Annotations only include destructiveHint:false, so this adds meaningful context beyond the structured data.

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

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

The description is two compact sentences, front-loaded with the main purpose. Every clause adds value: table type, inbox destination, input options, and replacement behavior.

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 proposal tool with 6 params and no output schema, the description covers the core purpose, input formats, and adoption consequence. It omits project_id and registry details, but those are likely standard context parameters shared across sibling tools.

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 high (83%), but the description adds important format details: csv header requirements, percent notation, first column as name, and the schema+rows combination. This goes beyond the schema descriptions.

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

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

The description clearly states the verb 'Propose', the resource 'stat-doc TABLE', and the target 'Inbox'. It distinguishes from sibling tools like propose_balance_board by specifying TABLE, making it 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?

Usage is implied by the resource type (table vs. board) but no explicit alternatives or exclusions are mentioned. The description does not say when to use this tool instead of propose_balance_board or other propose_* 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 only include destructiveHint:false, so the description carries the burden. It discloses upsert behavior (title-match to update), the requirement for complete text, and the consequence of resync:true—re-stamping staleness signals to prevent immediate regeneration nagging. This goes well beyond the minimal 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 three sentences, each dense with useful information. There is no filler, but the third sentence on resync is long with nested clauses. Given the complexity of the parameter, this is acceptable and stays concise enough.

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 6 parameters, no output schema, and sparse annotations, the description covers core usage: create/update behavior, complete text requirement, and resync semantics while referencing get_stale. It omits some parameter details (batch, project_id) but those are in the schema. Overall, it is complete for an 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 coverage is 83%, so baseline is 3. The description adds significant value by explaining the resync parameter in detail (when to set true and why), and clarifies that content must be complete. It does not describe batch or project_id, but the schema already covers those, so the description complements rather than repeats.

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 proposes a new/updated Idea note to the Inbox, using a specific verb and resource. It distinguishes from sibling propose_* tools (e.g., propose_screen, propose_system) by focusing specifically on Idea notes and mentions title-match update 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?

The description provides clear context: title-match determines update vs. new, and content must be the complete revised text. It also gives an explicit condition for setting resync:true, referencing get_stale to identify stale notes. It does not explicitly mention alternatives, but the resource type and update semantics make usage 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?

Beyond the destructiveHint annotation, the description only adds the inbox destination. It does not disclose side effects, permission requirements, what happens if both optional fields are omitted, or the role of project_id. With no readOnlyHint and minimal annotation coverage, this is insufficient.

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

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

The description is a single concise sentence that front-loads the purpose and includes the key constraint. Every word earns its place with no unnecessary detail.

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 no output schema and only minimal annotations. The description does not clarify the role of batch or project_id, the expected result, or how this proposal integrates with the inbox workflow. Given the complexity of multiple optional parameters and many sibling propose_* tools, this is incomplete.

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

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

The schema already describes dna, batch, and tech_notes; the description adds the cardinality constraint that at least one of dna/tech_notes is required. However, project_id is undocumented in both the schema and description, leaving a gap in parameter understanding.

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

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

The description clearly states the action ('Propose') and resources ('Project DNA and/or Tech Notes') with an explicit destination ('→ Inbox') and a required constraint ('at least one'). This distinguishes it from sibling propose_* tools by naming the unique resource combination.

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

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

No guidance is given on when to use this tool over alternatives such as propose_system or propose_screen. The 'at least one' phrase is a requirement, not a usage context, and there is no mention of prerequisites or exclusions.

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

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

With only a minimal annotation (destructiveHint false), the description adds meaningful behavioral context by explaining that the tool creates a proposal (→ Inbox) rather than directly modifying a screen, and how missing coordinates are handled. This goes beyond the schema and annotation, though it still doesn't disclose return values or error conditions.

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 the core purpose front-loaded and a clear emphasis on the mandatory coordinate parameters via 'ALWAYS'. It is concise, direct, and avoids unnecessary detail.

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 10 parameters and no output schema, the description covers the primary operation, critical usage constraint, and proposal workflow. It leaves some gaps around return values and preconditions, but partially compensates for schema limitations with the coordinate explanation. This is close to complete but not fully comprehensive.

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 80%, but the description adds crucial semantics for x/y/w/h by specifying they are in pixels on the screen's resolution from get_screen and that omitting them results in an unplaced pile. This enriches the meaning of these parameters 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 clearly identifies the tool as proposing an element onto a screen, with a specific verb and resource, and indicates that it goes to an Inbox. It distinguishes from sibling tools like propose_screen and propose_system by focusing on element-level UI additions and emphasizing coordinate requirements.

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 explicit usage rules, such as 'ALWAYS pass x/y/w/h' and the behavioral consequence of omitting coordinates ('unplaced pile'). The 'SECONDARY (user-driven UI)' label gives some context for when to use it, but it does not name alternative tools or state when not to use it, so it lacks the strongest differentiation.

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 annotation only provides destructiveHint=false. The description adds that this is a user-driven secondary action and that the result goes to the Inbox, which suggests a proposal workflow. But it doesn't disclose whether it creates a formal record, requires permissions, or how the proposal is processed further. With minimal annotation coverage, the description only partially compensates.

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, focused sentence with no filler. It front-loads the important usage context ('SECONDARY') and states the purpose and outcome efficiently. 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 propose tool, the description provides the core purpose and inbox destination. However, with no output schema and four parameters (one undocumented), plus numerous sibling propose tools, more context on when to use this vs. alternatives would improve completeness. It's adequate but not fully comprehensive.

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 already describes 'from' and 'to' with clear descriptions, and label is described as optional. The description doesn't add any parameter-specific meaning beyond schema, and project_id remains undocumented in both. Since schema coverage is 75%, the description's lack of parameter detail is acceptable but not additive.

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

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

The description clearly states the action (propose), the resource (a link between two existing screens), and the outcome (→ Inbox). It distinguishes from sibling tools like propose_screen or propose_system by specifying 'existing screens', making the purpose unambiguous.

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

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

The 'SECONDARY (user-driven UI)' prefix indicates this is a user-initiated action, and 'existing screens' implies it is not for creating new screens or systems. However, it doesn't explicitly name alternative tools or state when not to use this tool, so it misses full 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 only include destructiveHint: false. The description adds the 'Inbox' destination, suggesting a proposal workflow rather than direct creation, which is useful. However, it doesn't detail side effects, the need for acknowledgment, or what happens after proposing.

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

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

A single sentence that is perfectly front-loaded and contains no wasted words. It efficiently communicates the core action, purpose, and one key parameter behavior.

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 gives the core purpose but lacks context about the proposal workflow, when to set acknowledge_rejection, and how it fits with sibling tools. With 5 parameters and no output schema, more guidance would be helpful, though the schema fills some gaps.

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

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

Schema description coverage is 80%, so the baseline is 3. The tool description itself adds minimal parameter meaning beyond mentioning optional tasks, which is already in the schema. The project_id parameter is left undocumented in both the schema and description.

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 ('Propose'), resource ('milestone'), and destination ('Inbox'), clearly distinguishing it from update_milestone and other propose_* tools. The 'NEW' qualifier reinforces that this is for creating new milestones.

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 the tool (to propose a new milestone, optionally with tasks), and 'NEW' implies not for updating existing ones. However, it doesn't explicitly name alternatives or provide when-not-to-use guidance, so it stops short of a 5.

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

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

Annotations only include destructiveHint=false. The description adds useful context by explaining that parent creates a popup over another screen and that purpose grounds AI suggestions, and it indicates a proposal workflow via '→ Inbox'. However, it does not disclose the proposal lifecycle, permissions, or return behavior, leaving some ambiguity about what happens after the proposal is created.

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 packs essential guidance into a single dense sentence, using arrows and semicolons efficiently. It is not padded, though the 'SECONDARY (user-driven UI)' prefix is slightly jargon-heavy and could be clearer.

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 low complexity (4 params, no output schema, no enums), the description covers core behavior, key parameter roles, and the primary alternative tool. It omits the project_id parameter and does not describe return values, but these are minor gaps given the available sibling context.

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

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

Schema covers 75% of parameters with descriptions. The description adds functional meaning for 'parent' ('popup over that screen') and 'purpose' ('grounds AI suggestions'), going beyond the schema. The 'project_id' parameter remains undocumented in both schema and description, preventing a perfect score.

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

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

The description clearly states 'propose a NEW screen → Inbox', specifying the action, the resource (screen), and the receiving queue. It distinguishes this tool from sibling propose_* tools by targeting screens specifically and points to design_ui_from_systems for whole-UI work, making its scope unambiguous.

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

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

It explicitly frames itself as 'SECONDARY (user-driven UI)' and instructs 'Whole UI? design_ui_from_systems first', naming a concrete alternative for a different use case. This provides clear when-to-use and when-to-use-other guidance, exceeding the minimum.

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 only include destructiveHint=false. The description adds behavioral context by indicating proposals go to an 'Inbox' and that the tool is for new systems only, implying it does not modify existing ones. This complements the annotation without contradicting it.

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

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

The description is concise and front-loaded with the core purpose. Two sentences convey the action, destination, spec format, and the key alternative, with zero filler.

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

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

For a 7-parameter tool with no output schema and minimal annotations, the description covers the core behavior (proposal → Inbox), the critical spec format, and the alternative for existing systems. It does not explain all optional parameters, but the schema covers them, and the description is adequate for an AI agent to invoke the tool correctly.

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

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

Schema description coverage is 86%, so most parameters are already documented. The description adds critical meaning for the 'spec' parameter by specifying the required Markdown format: '## Goal / ## Boundary (Owns · Doesn't own) / ## Acceptance.' This goes beyond the schema's generic mention.

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

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

The description clearly states the action and resource: 'Propose a NEW system → Inbox.' It specifies the destination and distinguishes from update_system (for existing systems), making its purpose unambiguous relative to 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 provides clear context for when to use this tool ('NEW system') and an explicit alternative: 'Exists? use update_system.' It does not explicitly exclude other propose_* siblings, but the resource (system) is distinct, 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 only declare destructiveHint: false, which is minimal. The description adds the behavioral detail that links/elements follow because screens are id-referenced, shedding light on side effects. However, it doesn't cover prerequisites, reversibility, or possible collisions beyond the schema's note.

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

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

A single, front-loaded sentence that uses emphasis (caps) to convey key nuances. It is concise and every phrase adds meaning, though could be slightly more structured with a trailing note.

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 rename tool with no output schema, the description explains the critical behavioral outcome (links follow) but omits context about project_id disambiguation and how success is indicated. It's adequate for a straightforward tool but not rich.

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 description adds no parameter information. Schema coverage is 67%, with descriptions for 'name' and 'new_name', but 'project_id' is undefined. The description's 'id-referenced' clue is too indirect to clarify parameter usage or the role of project_id.

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 ('Rename') and resource ('screen'), and adds clarity by specifying 'IN PLACE' and 'DIRECT', distinguishing it from proposal-based workflows. It also clarifies the effect on links/elements, making the purpose unambiguous.

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

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

The phrase 'IN PLACE — DIRECT' implies this is the actual rename action rather than a proposal, but it does not explicitly name alternatives (like propose_screen) or state when not to use it. The description gives context but lacks explicit exclusions.

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

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

The description reveals key behavioral semantics: the order array directly specifies the new sequence, and IDs not included retain their relative order. This goes beyond the schema, which only says 'Ids in the new order.' The annotation destructiveHint=false already signals it is not destructive, but the description adds operational detail about how the reordering affects unmentioned items.

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

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

The description is a single, compact sentence that front-loads the core action. It packs the key rule about omitted items without redundancy, earning every word.

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 multiple conditional parameters (screen, milestone, milestone_id) and no output schema. While the schema gives brief usage hints, the description does not explain which parameters are required for each kind or what the API returns. The core reorder behavior is explained, but parameter coordination and return values remain ambiguous.

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 description adds valuable semantics for the 'order' parameter by explaining that omitted items keep their relative order, which is not present in the schema. The schema already documents 'kind' and some conditional parameters with 83% coverage, so the description supplements rather than duplicates. It does not clarify the purpose of project_id, but overall it enhances parameter understanding.

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

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

The description clearly states the tool's function: reorder milestones, tasks, or elements. The 'DIRECT' qualifier and the explanation of the order parameter distinguish it from other list/update tools. Sibling tools like update_task or propose_milestone do not overlap with reordering, so it 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 implies this tool is used to reorder resources, providing clear context. However, it does not explicitly mention alternatives or when not to use it, such as for updating properties or creating entities. Since no sibling tool offers reordering, the context is sufficient but lacks explicit exclusion 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 the minimal destructiveHint:false annotation, the description thoroughly discloses replacement semantics ('it REPLACES'), verification tiers (VERIFIED vs GREEN), exemption tags, failure output (response names unbacked criteria), and evidence staleness. 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 dense and information-rich, but formatted as a single run-on paragraph. It front-loads the purpose and then cascades into rules; every sentence earns its place, though bullet points would improve readability.

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 complex tool with 8 parameters, no output schema, and minimal annotations, the description covers the full behavioral contract: status semantics, file replacement, evidence verification, exemptions, output behavior, and staleness policy. There are 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 coverage is high, but the description adds critical semantics: files replaces the full set with 'done-but-EMPTY' behavior, evidence requires criterion/proof structure, and passed:true yields the green guarantee. These details go beyond the schema 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 opens with 'Report a SYSTEM's status (todo|in-progress|implemented) — DIRECT, live', a specific verb+resource+scope. The allowed statuses are enumerated, and the system focus distinguishes it from sibling tools like report_screen_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?

Provides clear operational rules: 'ALWAYS pass files (full list — it REPLACES)', the empty-state caveat, and the 21-day green staleness re-run instruction. It lacks explicit alternatives or exclusions, but the system-specific scope implies when it applies.

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 only declare destructiveHint=false, so the description carries extra weight. It discloses that the operation is advisory and that the state can be cleared by a fresh report_build_status, adding lifecycle context. It avoids 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 the main action, and no filler. Every word contributes to understanding purpose and behavioral context.

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 advisory flagging tool with no output schema, the description covers core purpose and clearing behavior. It doesn't explain the significance of no required parameters or the return format, but the schema covers parameter meaning, and the absence of an output schema lowers that expectation.

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 80%, so the schema already documents most parameters (id, name, note, missing_files). The description does not add additional parameter-level meaning beyond what the schema provides, 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 uses a specific verb 'Flag' with a concrete resource 'CODE DRIFT' and defines the condition ('mapped files no longer match the repo'). It distinguishes from siblings by noting the clearing mechanism via report_build_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?

Description provides clear context that the tool is advisory and that report_build_status clears the flag, effectively guiding when to use this tool (to flag) vs. when to use the alternative (to clear). However, it lacks explicit 'when not to use' or broader alternative scenarios.

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 annotation only indicates destructiveHint=false, so the description carries some burden. It adds useful context: that the action results in an 'Inbox progress card' and that 'owner adopts the ticks'. However, the phrase 'owner adopts the ticks' is cryptic and not fully explained. It does not disclose edge-case behaviors (e.g., what happens if tasks do not exist) beyond the simple flow.

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 extremely concise—a single arrow-separated phrase. It is front-loaded with the core action and outcome. The cryptic 'owner adopts the ticks' adds a potential point of confusion, but overall the structure is efficient and without unnecessary 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?

Given the tool has 4 parameters, no output schema, and only a destructiveHint annotation, the description is too sparse. It does not explain the purpose of the Inbox progress card, the meaning of 'owner adopts the ticks', or when to choose this over reporting tools like report_build_status. The tool likely needs more context for an agent to use it correctly in all scenarios.

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

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

Schema coverage is 75%, which is moderate. The description clarifies that the operation is for 'existing-milestone' tasks and that 'done_tasks' are marked done, adding some context beyond the schema. However, it does not explain the id vs milestone fallback or the role of project_id, so it does not fully compensate for missing schema descriptions.

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

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

The description clearly states the action: 'Mark existing-milestone tasks done' and specifies the output effect ('Inbox progress card'). It distinguishes from sibling tools like add_task (new tasks) and update_task (generic updates) by focusing on milestone-specific progress. However, it does not explicitly name an alternative, so it falls short of a 5.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The description implies it is for marking tasks in an existing milestone as done, but it does not state exclusions (e.g., when to use update_task instead) or mention prerequisites such as milestone existence. No 'when to use' or 'when not to use' is provided.

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

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

With only destructiveHint=false in annotations, the description carries some burden. It specifies the destination (Inbox) and allowed statuses, but does not disclose whether this action modifies the screen's actual status or merely sends a notification/report. This ambiguity limits transparency about side effects.

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

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

The description is a single, front-loaded sentence with no filler. It communicates the action, resource, allowed values, and destination efficiently. Every part 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 tool, it covers the basics: what, where, allowed values. However, it lacks any description of the return value (no output schema), does not mention project_id, and does not clarify whether it updates the screen entity or only sends an inbox message. Given the sibling set includes similar reporting tools, a bit more context would 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 description coverage is 67%, and the description adds no new parameter semantics. The status values are already listed in the schema, and project_id is undocumented in both schema and description. The description does not explain the role of project_id or how screen/status relate, leaving a clear 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 uses a specific verb ('report') with a clear resource ('SCREEN's status') and destination ('→ Inbox'), and lists the allowed status values. This clearly distinguishes it from sibling tools like report_build_status or report_milestone_progress, which target different resources.

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

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

The description implies usage: when you need to report a screen's status to the Inbox. However, it provides no explicit guidance on when to choose this tool over alternatives (e.g., report_build_status) or any exclusions. It does not state prerequisites or 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?

The description discloses the effect of unlocking the owner's Clear and the timing (after realigning). This goes beyond the destructiveHint annotation, which only indicates it is not destructive. It does not contradict the annotations.

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

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

Two sentences, front-loaded with the action, and no unnecessary words. The structure is ideal for quick understanding.

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 is simple and the description covers the action, the prerequisite timing, and the outcome. It lacks details about return values or idempotency, but given the low complexity and sibling context, it is sufficiently complete.

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

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

The description does not discuss parameters. The schema provides a description for 'title' but not for 'project_id'. With only 50% schema coverage, the description should compensate, but it does not, leaving some ambiguity.

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

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

The description clearly states the tool's action: reporting that a declined change was reverted. It also provides context by mentioning it unlocks the owner's Clear, and the verb+resource structure distinguishes it from siblings like get_rejections.

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

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

It explicitly says 'Call after realigning the build', giving a clear usage condition. However, it does not mention when not to use it or name alternatives, though the context is clear enough.

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

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

The description adds significant context beyond the readOnlyHint annotation: it explains that the tool returns the note and affected specs, that the agent does the writing, and highlights the critical requirement to send updates with 'resync:true' to avoid stale designs. This gives the agent useful behavioral expectations not captured in annotations.

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

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

The description is somewhat lengthy but each sentence provides unique value: purpose, return contents, workflow, and a crucial usage caveat. It front-loads the core purpose and is well-structured for an agent, though it could be tightened.

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 no output schema, the description compensates well by stating what is returned (note, specs, instructions). It also explains the adoption workflow and the resync flag. However, the missing project_id semantics and lack of detail about edge cases leave some gaps, so it is not a 5.

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 50% — 'note' is described, but 'project_id' has no schema description and the tool description does not mention it at all. Given the low schema coverage, the description should compensate for the undocumented parameter but does not, leaving the agent to guess project_id'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 the tool's specific function: 're-syncing ONE changed Idea note into the specs that depend on it.' It differentiates from siblings by emphasizing the scoped single-note job and references the app's 'Re-sync N systems' button, distinguishing it from broader operations.

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

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

The description gives clear context on when to use it: for a single Idea note, and it notes the result should be sent to the owner's Inbox to ADOPT. It references 'get_stale' in the schema but does not explicitly name an alternative or state when not to use it, so it falls short of a 5.

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

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

The annotations already declare readOnlyHint=true, so the safety profile is known. The description adds value by disclosing the output shape (compact hits with kind, id, name, and snippet), which is not present in annotations. It does not contradict annotations and provides meaningful behavioral context on top of them.

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, focused sentence that immediately states the tool's purpose and output. It is front-loaded and every word contributes value, with no filler or redundant information.

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

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

For a simple read-only search tool, the description provides the essential purpose and output structure, especially given the lack of an output schema. However, it omits details like search scope (all projects?), result ordering, or case sensitivity, which could affect usage. Still, it is sufficient for a basic task and sits at a reasonable level of 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%, with query and kinds described but project_id undocumented. The description adds no parameter-level information beyond the schema; it does not explain the project_id purpose or any search syntax/behavior. Since coverage is not high and the description does not compensate for the missing parameter description, this dimension scores low.

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 'Keyword search — compact hits {kind, id, name} + snippet' clearly states a specific verb (search) and resource (various kinds). It also specifies the output format, distinguishing it from sibling tools like get_system or get_screen that retrieve specific entities rather than performing a general search.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention when to prefer search over direct getters, nor does it list exclusions or alternative tools. The context must be inferred solely from the tool name and sibling list, which is insufficient.

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 far beyond the minimal annotations by disclosing that this writes directly (not through Inbox), is a derived AI summary (not design truth), is easily reversible by the owner, and automatically stamps the project version. It also specifies content constraints (only facts, no invented numbers, describe never evaluate, dominant language) and structural rules, giving the agent a clear behavioral model.

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 every sentence earns its place. It is well-structured with bold labels, a code block for the outline, and clear grouping of rules and constraints. The main purpose is front-loaded, and the level of detail is justified by 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?

For a write tool with no output schema and only destructiveHint=false, the description is remarkably complete. It covers the action, the direct-write behavior, prerequisites, formatting, word count, language, evaluation policy, and even version stamping. There is no significant missing behavioral or usage information that the agent would need.

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

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

The schema covers only 50% of parameters (summary has a description; project_id does not). The description compensates by detailing the exact markdown structure and word count for `summary`, and it implies `project_id` through phrases like 'the project version.' It does not explicitly define `project_id`, but the overall context makes its purpose clear, so the added value is strong but not perfect.

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

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

The description clearly states the action ('Write') and the resource ('the Design Document's Overview'), and differentiates it from sibling tools by emphasizing 'WRITES DIRECTLY (no Inbox)' — distinguishing it from propose_* tools. It also specifies the exact purpose ('human-readable page a new team member reads first') and even names a prerequisite tool (get_design_document).

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 explicit context: this is for writing the design overview, and it mandates a precondition ('call get_design_document with for_summary:true first'). It also states 'HARD RULES, same as the in-app button,' which signals consistency with an existing workflow. However, it does not explicitly contrast with alternative write/update tools beyond the no-Inbox note, so it stops short of a full when-to-use versus when-not-to-use guide.

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 the readOnlyHint annotation, the description adds valuable behavioral context: it returns the image itself plus the recipe, explains the coordinate conversion to prevent misplaced elements, and mentions existing screen contents to avoid duplication on a second pass. It also notes that proposals land in the owner's Inbox. No contradiction with the readOnlyHint annotation since the tool itself only reads/returns data.

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 dense but well-structured. It is front-loaded with the 'SECONDARY (user-driven UI)' label and immediately states the action. Every sentence adds value: the return payload, coordinate conversion, duplicate prevention, the propose/update workflow, and the trigger condition. No filler or redundancy, though it is a bit long.

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 absence of an output schema, the description does a good job explaining what the tool returns (image, recipe, canvas resolution, conversion, existing elements) and how to proceed (propose_element/update_element). It doesn't specify the exact recipe structure, but that is not essential for selecting the tool. It is sufficiently complete for a read-only tool with a clear trigger.

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 'screen' parameter is described in the schema as 'name or id', and the description elaborates on tracing that screen's reference image. However, 'project_id' has no description in the schema or the tool description (schema coverage is 50%), and the description does not compensate by explaining its role. The description adds some meaning via the recipe and conversion context but leaves project_id ambiguous.

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

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

The description clearly states the tool's function: 'turn a screen's REFERENCE IMAGE into placed elements.' It uses specific terminology like 'recipe', 'fraction→pixel conversion', and distinguishes itself from siblings by emphasizing it is a 'SECONDARY (user-driven UI)' tool. This is a concrete verb+resource statement, not a tautology.

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

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

The description explicitly states when to use it: 'Use when the user wants the wireframe to match a screenshot or mockup they uploaded.' It also labels the tool as 'SECONDARY (user-driven UI)' and instructs to follow up with propose_element/update_element, giving clear contextual guidance. It doesn't explicitly name alternatives or exclusions, but the trigger condition is sufficiently 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 only include destructiveHint:false, so the description adds useful behavioral context: updates are DIRECT and live (immediate), and placing an unplaced element is covered. However, it does not disclose return values, permissions, or rollback behavior, which would be helpful.

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

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

A single sentence front-loaded with action verbs and critical qualifiers ('DIRECT, live', 'preferred', 'also places'). Every phrase carries meaning, with zero filler.

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

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

For a 12-parameter mutation tool with no output schema, the description covers core scenarios and identification strategy efficiently. It lacks explicit mention of project_id requirements or return shape, but schema property descriptions cover several parameters and the essential behaviors are conveyed.

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 67%, and the description compensates with key selection logic: element_id preferred, screen+label fallback, and x+y special placement behavior. It does not fully explain h/w/y semantics, but the verbs 'move/resize' and placement hint imply their roles.

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 verbs 'move/resize/relabel' and clearly identifies the resource 'element'. The 'DIRECT, live' qualifier distinguishes it from proposal-based tools like propose_element, making its purpose unmistakable.

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 usage context: element_id is preferred over screen+label, and x+y can place an unplaced element. It implies immediate/direct use but does not explicitly name alternative tools or state when not to use it.

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

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

The annotation already marks destructiveHint false. The description adds that new_name renames without deletion and characterizes the operation as DIRECT, reinforcing non-destructiveness. It does not disclose other behaviors like needing an id or name to locate the milestone, which is partly in the schema.

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

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

One sentence, front-loaded with the action and target, and every phrase adds meaning ('DIRECT', 'never delete+recreate'). 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?

The tool has 7 parameters with no required fields, and the description covers the main edit fields and rename behavior. However, it lacks guidance on identifying the target (id vs name), project_id context, or effects of omitted fields, making the description incomplete for a moderately complex 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 57%: id, name, new_name, difficulty have descriptions. The description adds that new_name renames (not delete+recreate) and reinforces that name is editable, but does not explain the id-vs-name resolution or how to clear difficulty (only in schema).

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

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

The description uses a specific verb ('Edit') with the resource ('milestone') and lists the modifiable fields (goal, weeks, difficulty, name). It adds behavioral context ('DIRECT', 'never delete+recreate') that distinguishes it from delete-and-recreate approaches, making the purpose 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?

The description implies this is the direct update path for milestones, explicitly noting that new_name renames rather than delete+recreate. However, it does not name alternative tools (e.g., propose_milestone) or provide explicit when-not conditions beyond the no-delete behavior.

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 that this tool creates a proposal (Inbox diff) rather than a direct mutation, which is critical behavioral context. It also explains the resync behavior ('re-stamps the staleness signal on adopt') and adds a caution ('Never set it on an ordinary edit'). With only destructiveHint:false provided, the description adds substantial 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 three sentences, front-loaded with the primary purpose, and every sentence adds critical operational detail. It is dense but not verbose, with no filler or redundancy.

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

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

For a 9-parameter tool with no output schema, the description covers the most nuanced behaviors: the proposal/inbox-diff pattern, the need to fetch the system first, the resync condition, and the rename/bundle parameters. Remaining parameters (acknowledge_rejection, project_id) are covered by the schema, so the description is sufficiently 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 high (89%), but the description goes beyond schema by clarifying the purpose of new_title ('renames'), context_title+context ('bundles the Idea update'), and resync ('ONLY when you rewrote this spec FROM its upstream Idea'). It also emphasizes that spec must be the 'FULL revised spec,' which is not fully captured in the schema's 'Full revised spec markdown'.

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 'Propose a system UPDATE → Inbox diff,' which clearly states the verb (update), the resource (system), and the resulting artifact (inbox diff). This distinguishes it from siblings like propose_system, update_element, and update_task, which target different resources or 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?

The description gives explicit sequential guidance: 'get_system first' and 'send the FULL revised spec.' It also conditionally references resync_from_idea ('see resync_from_idea') and clearly states when resync:true should be used. It does not explicitly list alternatives for when to use propose_system, but the purpose statement makes that distinction obvious.

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 the single annotation (destructiveHint:false), the description reveals error behavior when a task is held, the stale-takeover semantics with force:true, and the release mechanisms. It also notes 'DIRECT' to imply no proposal workflow, adding valuable 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 terse and front-loaded, packing claim/release conditions, error semantics, and stale-force behavior into two short sentences with no wasted words.

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

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

The most complex behavior (claiming/releasing) is fully explained, and field-level details are mostly covered by the schema. The lack of explanation for project_id and overall field editing is a minor gap, but the tool's purpose is still clearly understood.

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 already describes individual fields like done, force, assignee, and status. The description adds the critical combination logic for claiming (assignee+status) and release (done or assignee), which is not evident from the schema alone. However, project_id remains undocumented in both schema and description, slightly lowering the score.

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

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

The description explicitly states 'Edit a task or CLAIM it', providing a specific verb and resource that distinguishes it from sibling tools like add_task and update_milestone. The claim/release behavior is clearly identified.

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 concrete usage patterns: assignee:'me'+status:'in-progress' to claim, force:true for stale, done:true or assignee:'' to release. However, it doesn't explicitly mention when to choose this tool over others or mention exclusions, though the context is clear and no alternatives are needed.

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 only include destructiveHint=false; the description adds useful constraints ('YOUR OWN', 'still-pending') and id provenance. However, it doesn't disclose what happens after removal or whether it's reversible, so behavioral transparency 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 a single, front-loaded sentence that conveys the action, scope, and id source without wasted words. Every element 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 two-parameter tool with no output schema, the description covers the key usage context: what to remove and where to get the id. The only notable omission is the role of project_id, which is a minor gap given the tool's simplicity.

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 documents id as 'The pending item's id' (50% coverage). The description adds that the id comes from the propose response or get_inbox, which helps. But project_id has no description in the schema and is not addressed in the description, leaving a semantic 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 specifies the action ('Remove'), the target ('YOUR OWN still-pending Inbox item'), and the id source ('propose response / get_inbox'). This clearly distinguishes it from sibling tools like delete_entity and resolve_rejection by scoping to your own pending inbox items.

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 clear usage context: it's for withdrawing a still-pending proposal that you created, and it tells the agent where to obtain the id. It doesn't explicitly name alternative tools for different conditions, but the ownership and pending-status exclusions are clear enough.

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