Forge Engine

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

Annotations indicate readOnlyHint false (mutation) and destructiveHint false. Description adds that changes apply directly, not as a proposal. Does not detail side effects or error behavior, but provides useful behavioral context beyond annotations.

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

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

Two sentences with no unnecessary words. Front-loaded with key action and intent. 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 tool with 8 parameters (1 required) and no output schema, the description covers core logic: adding task to milestone, identification method, and assignee shortcut. Missing return value or error conditions, but sufficient for typical use.

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

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

Schema has 100% coverage with descriptions for all parameters. Description adds additional semantics: 'identify milestone by id (preferred) or unique name' and 'assignee 'me' = you', which clarify usage beyond schema.

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

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

Description clearly states verb 'add' and resource 'task to an existing milestone'. Distinguishes from proposal tools by saying 'applies DIRECTLY (in place, not a proposal)', which differentiates it from sibling propose_* tools.

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

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

Provides guidance on identifying milestone (by id preferred or unique name) and how to claim task with assignee 'me'. Does not explicitly state when not to use or list alternatives, but the direct vs proposal distinction is clear from context.

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

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

The description explicitly confirms the destructive nature ('applies DIRECTLY (destructive)'), aligning with annotations. It adds context about what triggers duplication removal (duplicate names for milestones, duplicate labels for elements), beyond what annotations provide.

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

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

The description is concise (two sentences) and front-loaded with the main action and nature. The second sentence efficiently details the options without superfluous information.

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

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

Given the three parameters (all described in the schema) and no output schema, the description covers the tool's behavior, scope, and key constraints. It is complete for an AI agent to understand when and how to use it.

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 enhances understanding of the 'kind' parameter by explaining the criteria for duplication (e.g., 'duplicate-named milestones') and clarifies that 'screen' is for elements only. The 'project_id' parameter is not covered, but the schema already describes it sufficiently.

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 and resource: 'Remove DUPLICATE entries, keeping the first of each'. It specifies two kinds (milestones, elements) with distinct behaviors, making it distinct from sibling tools.

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

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

The description indicates what to deduplicate and that it is destructive, but does not explicitly state when to avoid using it or compare with alternatives like delete_entity.

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 claims 'nothing is deleted immediately' (non-destructive at call time), but annotations set destructiveHint=true, creating a serious contradiction. This undermines the agent's understanding of the tool's actual effect.

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 paragraph with front-loaded purpose and clear sentences. It efficiently covers key aspects without redundancy, though a slight structural improvement (e.g., bullet points) could enhance 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?

Given 6 parameters (1 required), no output schema, and the need to explain the proposal mechanism, the description covers identification, kinds, and blast radius. It lacks mention of how to undo or conditions, but is fairly 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 100%, baseline 3. The description adds value by explaining identification preferences (id preferred, exact name, flow_edge from+to) and noting that a system's response includes blast radius, which goes beyond 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 tool proposes deletion of a design entity to a Forge Inbox, lists seven specific entity kinds, and distinguishes from siblings like propose_* tools that propose creation or other 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?

It explains when to use (to propose deletion) and provides identification methods (id, name, from+to for flow_edge). It does not explicitly state when not to use or mention alternatives like withdraw_proposal, but the context is clear.

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

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

No annotations present, so description carries full burden. Clearly states it is 'Non-destructive' and describes the batch process: it returns a batch id, requires canvas aspect confirmation, then proposes screens, placed elements, pop-ups, and flow edges in one batch. The owner adopts the whole UI at once.

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 well-structured sentence that front-loads purpose, then details the workflow. Every word adds value, no redundancies. Highly efficient.

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

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

Given the tool has one optional parameter and no output schema, the description explains the process and the return of a batch id. It adequately covers what the agent needs to know about invocation and outcomes for this simple 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?

Only one parameter (project_id) with 100% schema coverage. The description adds context: 'from list_projects' and 'omit = the connector URL's project.' This clarifies the parameter's source and default behavior beyond the schema.

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

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

Clearly states the purpose: 'ONE-PASS recipe to design the UI from the spec'd Systems'. It specifically targets generating screens, flow, or a prototype, which distinguishes it from other tools like propose_screen or propose_element that handle individual pieces.

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 'run when the user asks to generate screens / flow / a prototype.' Provides context on the workflow (confirm canvas aspect first, then propose in batch). Does not explicitly list when not to use, but the context is clear and implies this is the consolidated tool for bulk UI generation.

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

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

Annotations already declare readOnlyHint and idempotentHint true. The description adds value by detailing exactly what is read (stat-doc TABLES, node BOARDS, saved scenarios) without contradicting annotations.

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

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

Two sentences with no wasted words. The first sentence comprehensively lists what is read; the second provides usage guidance. Information is front-loaded and efficiently structured.

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

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

Given the tool's simplicity (read-only, optional parameters), the description sufficiently covers what data to expect. The output schema is absent, so the description hints at the return structure (tables, boards, scenarios), but more detail on format or pagination could 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?

Schema coverage is 100%, so the parameters are fully documented in the schema. The description adds no parameter-specific information beyond the schema, meeting the baseline expectation.

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

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

The description clearly states it reads balance lab data (tables, boards, scenarios) with specific details about content. The verb 'Read' is explicit, and the resource is well-defined, distinguishing it from siblings like 'propose_balance_board' which write.

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 advises using the tool 'to reason about game balance before proposing changes,' providing clear context. While it doesn't explicitly state when not to use or list alternatives, the guidance is direct and actionable.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by mentioning the 'drift' flag, the return condition (only systems with status/files/drift; empty if nothing reported), and the decay risk with a verification step. This goes beyond annotations.

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

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

The description is information-dense but front-loaded with the core purpose. It could be slightly tighter, but every sentence serves a purpose (usage, verification, edge cases). Not excessively verbose.

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 no output schema, the description explains return content (files, status, drift flag) and edge cases (empty if nothing reported). Combined with strong annotations, the tool is well-specified for an AI agent.

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

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

Schema coverage is 100% with one optional parameter (project_id). The description does not add extra meaning beyond the schema, but the schema is sufficient. Baseline of 3 is appropriate.

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

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

The description uses a specific verb-resource pair ('maps systems to files and build status') and clearly distinguishes itself from sibling tools like report_build_status and report_drift. It states what the tool does (finds where a system lives in the codebase and its build status) with precise 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?

Explicitly tells when to use: before editing a system to change the right files, or to see what's already built. Also explains when not to rely on stale data and how to handle drift by calling report_drift. Provides clear context and alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context about the type of help content provided (e.g., pending states, system definition), which is beyond what annotations offer.

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

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

The description is a single sentence that front-loads the purpose, lists specific topics, and ends with usage guidance. Every part earns its place 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?

Given the simplicity of the tool (no parameters, no output schema), the description covers the topics and usage. However, it does not explicitly state the output format (e.g., plain text or markdown), which could be helpful for the agent to set expectations.

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, and schema coverage is trivially 100%. According to the guidelines, 0 parameters baseline is 4, and the description adds no unnecessary parameter info.

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

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

The description clearly states that the tool provides guidance on using Forge well, listing specific topics like the propose→adopt flow, pending status, system definition, token-efficient reading, and billing. The phrase '(no project needed)' distinguishes it from project-specific sibling tools like get_project_context.

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

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

The description explicitly states when to call this tool: 'when unsure how something works or when the user asks.' This provides clear guidance, and the 'no project needed' qualifier contrasts with project-specific tools, helping the agent choose correctly.

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

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

Annotations already indicate readOnly and idempotent. Description adds crucial behavioral detail: empty result means no recorded decision, and warns never to invent a rationale. Also notes that every entry carries source/who/when for citability.

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 paragraph with no redundant sentences. Front-loaded with a memorable label ('DESIGN MEMORY — the recorded WHY'), then logically progresses through content, usage, and 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?

While the description covers purpose and behavior, it lacks explicit detail about the output schema (since none is provided). Mentions that entries carry source/who/when, but does not describe the full return structure. For a query tool without output schema, more completeness would be helpful.

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

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

Schema coverage is 100%, but the description adds value by explaining that 'system' accepts id or exact name, and clarifies that omitting 'project_id' uses the connector URL's project. Provides context beyond the schema's field 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 querying project history, specifying the types of records included (build decisions, activity logs, rejections, changelogs). It distinguishes itself from siblings like 'get_system' or 'get_rejections' by emphasizing the aggregated 'why' memory.

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 recommends using it before changing a system's direction, and explains filtering options (by system and query). Lacks explicit when-not-to-use guidance, but the context is clear. Could mention alternatives for more specific history, but not necessary.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context (e.g., you cannot adopt, owner acts in Forge) that complements annotations without contradiction. The phrasing reinforces safety and clarifies the tool's role.

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

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

Two sentences with no wasted words. First sentence states purpose and scope; second provides usage guidance and behavioral note. Information is front-loaded and efficiently delivered.

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, the description fully covers purpose, usage context, and limitations. No output schema is needed given the straightforward behavior. All relevant aspects are addressed.

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

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

Schema coverage is 100% with a single project_id parameter. The description adds meaningful context: 'from list_projects' and 'omit = the connector URL's project,' which aids correct invocation beyond the schema's type definition.

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

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

The description uses a specific verb ('list') and resource ('PENDING Inbox items') with clear scope: proposals not adopted. It distinguishes from sibling propose tools by specifying this is the triage queue before proposing, effectively differentiating.

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

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

Explicitly states when to call ('BEFORE proposing') and why ('so you don't duplicate something already waiting'). Also notes that propose is write-only and the owner handles adoption, providing clear context for alternative actions.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. Description adds detail about the returned content (goal, week estimate, difficulty, systems, tasks with id/name/done/status/effort), which is valuable beyond annotations.

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

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

Two sentences, no redundancy. First sentence states purpose and return fields, second sentence provides usage guidance. 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?

Given no output schema, the description enumerates return fields comprehensively. It also explains parameter semantics and usage context. Adequate for correct tool selection and invocation.

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

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

Schema has 100% coverage, but the description adds context: id is preferred, name must be exact and unique, and project_id is optional (defaults to connector project). This clarifies usage beyond the schema's property 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 starts with 'Get ONE milestone's full detail' using specific verbs and resources, lists exact return fields (goal, week estimate, etc.), and distinguishes from list_milestones by emphasizing it retrieves one milestone's full detail.

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

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

Explicitly states 'Use after list_milestones to read a specific milestone without pulling the whole project.' Also instructs to prefer id over name, and notes uniqueness requirement for name.

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 idempotentHint=true; description adds a critical warning about size and token cap, but doesn't elaborate on exact output structure.

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

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

Two sentences, economically front-loaded with key information, 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 many siblings and lack of output schema, the description sufficiently orients the agent, though a note on return format would be beneficial.

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

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

Schema covers the single optional parameter fully (100%), and description adds no additional semantic detail beyond what the schema provides.

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

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

Description explicitly states 'FULL design dump' and contrasts with sibling tools like get_project_meta, list_*, get_system, etc., making the unique scope 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?

Explicitly says 'NOT the entry point' and lists appropriate alternatives for different tasks, plus warns about large size exceeding token caps.

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 read-only, idempotent, non-destructive. Description adds value by noting it's cheap and includes current task claims, which aids understanding beyond annotations.

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

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

Two concise sentences front-loaded with 'START HERE', efficiently conveying purpose and usage.

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?

Complete for a simple tool with one optional parameter: covers return fields, usage guidance, and positioning among siblings.

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

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

Schema coverage is 100% with clear parameter description. Description doesn't add new info beyond schema, meeting baseline.

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

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

The description clearly states it's a 'tiny project overview' and lists specific fields returned, distinguishing it from siblings like get_project_context.

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

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

Explicitly says 'START HERE' and provides a workflow: browse with list_*, drill with get_*, noting it's cheaper than get_project_context.

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

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

The description adds important behavioral context beyond annotations: entries have 'guidance' and automatically drop off when resolved, and it defines the workflow for handling rejections.

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 and front-loaded with the tool's core purpose, but the second sentence is somewhat dense and could be more structured.

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

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

With no output schema, the description partially explains return fields (guidance, title implied) but does not fully describe the structure, leaving gaps for an agent.

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

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

Schema description coverage is 100%, so baseline is 3. The tool description adds no additional meaning about the single optional parameter beyond what the schema provides.

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

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

The description clearly states the tool returns 'The DECLINED list' and explains what entries are and how to handle them, distinguishing it from sibling tools like resolve_rejection.

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 specifies to check at session start and implies using resolve_rejection after following guidance, but does not explicitly exclude other use cases or mention alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that it is the only compact way to read a layout, enumerating all included data components, which adds value beyond annotations.

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

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

Single paragraph packs many details without redundancy. Front-loaded with essential output description. Could be slightly more structured, but remains concise.

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

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

Despite no output schema, the description comprehensively lists all returned data (elements, flow links, popups, etc.) and when to use the tool. Provides complete guidance for an AI agent.

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

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

Schema coverage is 100% with clear descriptions for all three parameters. Description adds minimal nuance (preferred id, fallback name, project_id optional), not significantly exceeding what schema provides.

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

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

Description clearly states it returns the full layout of a screen, including kind, purpose, resolution, elements with positions, flow links, and popups. It distinguishes from sibling get_project_context by noting that the latter omits element positions.

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 advises to read this before update_element or adding onto an existing screen. Also contrasts with get_project_context which omits element positions, providing clear usage context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by specifying the exact data returned (Goal, Boundary, Acceptance, etc.), enhancing transparency beyond annotations.

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

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

Two sentences, no unnecessary words. First sentence states purpose and output; second provides usage guidance. Highly efficient.

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

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

For a simple read-only tool with 3 optional params and good annotations, the description fully covers when to use, what it returns, and how parameters relate. No gaps.

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

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

Schema coverage is 100% with descriptions for each parameter. The description reinforces that id is preferred and name is fallback, but adds minimal new meaning beyond schema.

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

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

The description clearly states the verb 'Get' and the resource 'ONE system's full spec', listing specific fields (Goal, Boundary, Acceptance, raw markdown, sources, status). It distinguishes from siblings like get_project_context and list_systems.

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 recommends using after get_project_context to read a specific system in detail without pulling the whole project, providing clear context and alternative.

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 instructs the agent to create/replace a file block, implying a write operation, but annotations set readOnlyHint=true. This is a clear contradiction. The description adds some behavioral context (e.g., 'remove it if they object') but the inconsistency undermines transparency.

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

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

The description is front-loaded with the important usage context, but it is somewhat long and includes imperative instructions that could be streamlined or separated. It effectively communicates the purpose but could be more concise.

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

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

Given no output schema, the description explains the two return components and the required action. However, it lacks specifics on the format or content of the greeting and working agreement block, which could help the agent understand what to expect.

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 no parameters, so schema description coverage is 100%. The description does not need to explain parameters. It adds value by describing the output and actions, which is sufficient.

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 should be run first on a new repo/session and returns a greeting routine and a working agreement block. The verb 'get' in the name suggests retrieval, but the description instructs actions (adding the block), causing slight ambiguity.

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

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

The description explicitly says 'Run this FIRST on a new repo/session (no project needed).' This provides clear context on when to use the tool, though it does not explicitly contrast with 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, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context: it returns a full recipe and batch id, and describes the internal process of proposing one context overview and one system per real module, which goes beyond the annotations.

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

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

The description is a single sentence but contains essential information. It front-loads the purpose and is efficient, though slightly dense. No wasted words, but could be slightly restructured for 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?

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what the tool does, what it returns (full recipe + batch id), and the process. No output schema is needed as the description sufficiently describes the return.

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

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

The input schema has 100% coverage with a clear description for the only parameter (project_id). The description does not add additional parameter semantics, so it meets the baseline of 3.

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

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

The description clearly states the action ('import of an EXISTING codebase') and the resource ('codebase'), with the verb 'import' and a specific scope. It distinguishes itself from sibling tools as no other tool performs import.

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

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

The description explicitly states when to use the tool: 'run when the user wants Forge to reflect their code.' It provides clear context but does not include explicit when-not-to-use or alternatives, though no direct alternative exists among siblings.

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

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

Description adds behavioral context beyond annotations: returns newest-first rows with specific fields. Annotations already indicate safe read-only operation, and description aligns with no side effects.

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

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

Extremely concise: two sentences covering purpose, output format, ordering, filters, and an alternative. Every word adds value.

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

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

Despite no output schema, the description explains the return format, ordering, and filtering. Combined with rich annotations, it fully informs usage for a simple list tool.

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

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

Schema coverage is 100% with parameter descriptions. The description summarizes the filters but does not add significant new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it lists the project's change history, specifies output fields and ordering, and distinguishes from the sibling tool get_project_meta for real-time info. Answers the questions 'what changed recently / who touched X'.

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

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

Explicitly states when to use ('answers what changed recently / who touched X') and when not to (for real-time building info, read claims in get_project_meta), providing a clear alternative.

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

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

Annotations already show readOnly, idempotent, non-destructive. Description adds specifics about compact payload (no goals/task names) and tiny size, enhancing transparency beyond annotations.

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

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

Two dense sentences with no fluff. First sentence states purpose and fields; second adds usage guidance. Slight redundancy ('tiny payload' echoes 'compactly') but overall efficient.

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

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

Given no output schema, description fully explains returned fields (id, name, week estimate, order, done/total counts) and contrasts with sibling tools. Parameter is simple and well-explained. Complete for a small 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?

Only one parameter (project_id) with 100% schema coverage. Description adds context about default behavior (omit = connector URL's project) and source (from list_projects), adding value beyond schema.

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

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

Describes listing milestones compactly with specific fields (id, name, week estimate, order, task counts). Clearly distinguishes from get_project_context (large) and get_milestone (drill-in).

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

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

Explicitly states use to browse plan or get milestone ID without pulling whole project. Contrasts with get_milestone for detail. Provides clear context for when to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: shows projects user can access with an account key, returns specific fields, and explains behavior with project-scoped keys. 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?

Three sentences, front-loaded with the main purpose, then usage guidance, then an important note. No unnecessary words. Efficient and clear.

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

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

Despite no output schema, the description states the return fields (id, name, role). It also covers the key scope nuance. For a simple list tool with no parameters, this is complete.

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

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

The tool has no parameters, and schema coverage is 100%. Description does not need to add parameter info. Baseline score for 0 parameters is 4.

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 Forge projects the user can access, including id, name, and role. It distinguishes itself from siblings by its purpose of discovering which project to work on, which is unique among sibling tools.

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

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

The description explicitly says to use this tool to discover which project to work on, then pass the project_id to any tool. It also notes that a project-scoped key returns just one project. No explicit exclusions or comparisons to alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds that payload is 'tiny' and 'compact', which is consistent but adds minimal behavioral insight beyond annotations.

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

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

Two sentences: first states core function and output fields, second states use case and benefit. No filler, front-loaded with key info.

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

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

Given no output schema, description covers output fields and payload characteristic. Lacks explicit return format details but sufficient for a simple list tool with one optional parameter.

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 provides full description of project_id with default behavior. Description does not mention this parameter, so adds no meaning beyond schema. Baseline of 3 is appropriate given 100% schema coverage.

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

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

Description explicitly states action (list), resource (screens), and output fields (id, name, purpose, build status). Distinguishes from get_screen by noting compactness and from list_projects by scope (screens vs 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?

Implies usage for browsing screens or grabbing IDs, and contrasts with 'pulling the whole project', but does not explicitly state when not to use or name alternative tools like get_screen for full details.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds that the payload is tiny and includes only specific fields, which is useful behavioral context but does not reveal additional traits like auth needs or rate limits. Given the strong annotation coverage, this is appropriate.

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, all essential, no redundancy. It front-loads the purpose and then adds usage guidance. Highly efficient.

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

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

The description explains the return fields (id, name, status, goal) and mentions the compact nature. Although there is no output schema, it gives enough information for an agent to understand the result. It could mention pagination or ordering, but for a simple list, this is adequate.

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

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

The input schema already describes the sole parameter (project_id) with a clear description. The tool description does not add new information about the parameter beyond what the schema provides. With 100% schema description coverage, baseline 3 is correct.

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 is to list systems, the resource is the project's systems, and the scope is compact (id, name, status, goal only). It also distinguishes from get_system by saying 'Drill into one with get_system', providing clear differentiation.

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

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

The description implies when to use (browse systems or grab an id without full project), and explicitly directs to get_system for full details. It does not mention when not to use, but the sibling tools list includes potential alternatives like propose_system or update_system, which are not discussed. However, the guidance provided is sufficient for typical use.

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

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

Annotations already indicate destructiveHint=false, but the description adds that the operation is 'Non-destructive, attributed to you,' providing extra context about attribution and safety. No contradictions with annotations.

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

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

The description is two sentences with a parenthetical clarification, front-loading the main action. Every sentence adds value with no wasted words. Highly efficient.

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

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

Given the tool's simplicity with 4 parameters (1 required) and no nested objects or output schema, the description provides sufficient context for typical use. It could optionally mention response behavior but is reasonably complete as is.

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

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

Schema coverage is 100% with all parameters described, so baseline is 3. The description adds further meaning, especially for 'version' (explains it stamps the entry to a concrete build) and 'text' (clarifies it's one or two sentences). 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?

Description clearly states the tool appends a build-log entry to the Activity feed, specifying it's for recording what was built, decisions, or divergences, like a commit note. It distinguishes itself from the sibling tool report_milestone_progress by positioning itself as the narrative counterpart.

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

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

Explicitly states when to use: 'Use as you work' and contrasts with the alternative tool: 'the milestone tick is report_milestone_progress; this is the narrative.' Provides clear guidance on when to choose this tool vs. siblings.

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

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

The description states 'Adopting REPLACES a same-named board', which implies destructive behavior, contradicting the annotation destructiveHint: false. Score 1 as per guidelines for 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 concise (3 sentences) and front-loaded with the core purpose. It efficiently packs essential details without unnecessary verbosity.

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

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

Given no output schema, the description covers the proposal workflow, node types, auto-layout, and replacement behavior. It provides sufficient context for an AI agent to use the tool correctly.

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

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

Schema coverage is 100% with basic descriptions, but the description adds significant meaning beyond the schema, such as detailed node examples, name-magic, and auto-layout. This enriches 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 specifies the tool proposes a 'Balance Lab BOARD (a node canvas)' and explains what nodes are, with examples and auto-layout behavior. This differentiates it from siblings like propose_balance_table, propose_screen, etc., by resource type.

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 node canvases but does not explicitly state when to use this tool over alternatives like propose_balance_table. No when-not or alternative guidance 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?

Although annotations are neutral (readOnlyHint=false, etc.), the description adds value by stating the tool never performs a silent write and that adopting replaces a same-named table, providing crucial behavioral context for a mutation tool.

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

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

The description is two sentences, front-loaded with purpose, and every sentence adds necessary information. No fluff or redundancy.

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

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

Given 6 parameters and no output schema, the description covers input options and lifecycle but does not mention what the tool returns (e.g., a proposal ID or inbox confirmation). This gap reduces completeness slightly.

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

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

Schema coverage is 100%, and the description adds meaning beyond schema: it explains that first column in CSV is name, a 'name' column is guaranteed in schema mode, and describes the 'registry' parameter. This enhances 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 proposes a 'Balance Lab stat-doc TABLE' for entity catalogs like Weapons, Monsters, Skills, distinguishing it from sibling tools like propose_balance_board (which likely handles board-type docs). The verb 'propose' and resource 'table' are specific.

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 explains two input modes (csv or schema+rows) and notes that re-proposing updates an existing table. However, it does not explicitly contrast with alternatives like propose_balance_board or propose_dna, though the context suggests the resource type differentiates.

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 value beyond annotations: it states 'Non-destructive,' matches the destructiveHint=false annotation, and explains the update behavior (title-matching, sending to Inbox, requiring complete revised text). This provides good context 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?

The description is five sentences with no wasted words. It front-loads the main action and every sentence contributes meaningful information, making it highly efficient.

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

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

Given no output schema and minimal annotations, the description thoroughly covers the tool's behavior (non-destructive, inbox delivery, diff behavior) and parameter usage. It could optionally mention the return value (e.g., proposal ID), but it is already sufficiently complete for reliable 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?

Although schema coverage is 100%, the description adds crucial usage context: for the 'content' parameter, it clarifies 'Send the complete revised text, not a delta,' and for 'batch' parameter, it explains the group adoption purpose. This enriches the schema definitions.

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

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

The description clearly states 'Propose a new/updated Context (Idea) note → Inbox.' It uses a specific verb ('propose') and resource ('Context note'), and distinguishes from sibling propose_* tools by focusing on context notes.

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

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

The description gives a clear when-to-use: 'Use when the build changes something the upstream idea should reflect.' It implies the goal of keeping the source-of-truth in sync. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Beyond annotations (destructiveHint=false, etc.), the description adds that the proposal goes '→ Inbox to Adopt', indicating it's a non-destructive proposal, not a direct update. It also specifies the requirement for at least one input field, providing clear behavioral expectations.

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

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

The description is two sentences with no wasted words. The first sentence defines the tool's action and content; the second provides usage requirements and behavioral note. It is front-loaded and efficiently structured.

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

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

For a tool without an output schema and with well-documented parameters, the description covers the essential: what it does, required inputs, and the outcome (Inbox to Adopt). It lacks detail on the adoption process but is sufficient given the complexity and 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 description coverage is 100%, and the schema itself already describes each parameter well. The description adds the high-level constraint 'at least one required' and groups DNA/tech_notes into the two proposal options, but does not significantly enhance understanding of individual parameters beyond what the schema provides.

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

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

The description clearly states the tool proposes 'Project DNA (north star: what it is · who it's for · pillars · non-goals) and/or Tech Notes', distinguishing it from sibling propose_* tools by specifying the exact content types and the outcome ('→ Inbox to Adopt').

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 constraints: 'At least one of `dna` / `tech_notes` required' and 'Non-destructive.' It implicitly differentiates from siblings by content type but does not explicitly state when to use this tool over other propose_* tools like propose_context or propose_element.

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 beyond annotations: the tool is non-destructive, it creates a proposal that goes to an inbox for adoption, and omitting coordinates results in an unplaced pile. Annotations are all false, so 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 a single efficient paragraph with no wasted words. Each sentence adds value, though the term 'SECONDARY (user-driven UI)' may be slightly cryptic but not detrimental.

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 10 parameters, no output schema, and minimal annotations, the description covers the core action, coordinate requirements, lifecycle, and consequences. It references related tools (get_screen) and provides necessary user interaction guidance.

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

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

Schema coverage is 100%, but the description adds meaning: explains x/y/w/h as pixels on the screen's canvas, references get_screen for resolution, and clarifies the role of system and note. It also describes the consequence of omitting coordinates.

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 the tool's purpose: 'Propose a UI element onto a screen → Inbox to Adopt.' It clearly identifies the resource (UI element) and the action (propose). It also distinguishes from siblings like propose_screen by focusing on elements.

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 guidance: 'ALWAYS pass x/y/w/h' and explains the consequence of omitting coordinates ('dumps it in an unplaced pile'). It also notes the screen can be adopted or pending. However, it does not explicitly compare to alternative tools or state when not to use.

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

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

Description states 'Non-destructive (connection only, no layout)', aligning with destructiveHint=false. It adds that it creates an 'Inbox to Adopt' proposal, which is useful beyond annotations. No contradiction.

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

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

Extremely concise with three sentences. The first sentence front-loads context (secondary, user-driven), then the core action, then constraints. Every word adds value, no 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?

Given no output schema and 4 parameters (2 required), description adequately covers input constraints and behavior. It mentions 'Inbox to Adopt' hinting at the outcome, but lacks explicit return details. Still, it's sufficient for selection and invocation in most cases.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds extra guidance: 'Use screen names from get_project_context', aiding parameter selection. This provides value beyond the schema.

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

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

Clearly states the tool proposes a navigation link between two existing screens, specifying the verb 'propose' and resource 'flow edge'. It distinguishes from sibling tools by focusing on connections between screens, not other propose actions.

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

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

Explicitly labels as 'SECONDARY' and 'user-driven UI', providing context for when to use. It notes it's not part of the core build loop and only for user-initiated screen flow mapping. No explicit alternatives given, but context is clear.

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

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

Annotations already indicate non-destructive. The description adds the '→ Inbox to Adopt' flow, which is key behavioral context beyond what annotations provide.

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

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

The description is very concise, one sentence plus a tag, with all information front-loaded. 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 is relatively simple with 4 parameters and no output schema. The description covers the proposal flow and non-destructive nature, which is sufficient. Could mention return value but not critical.

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

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

Schema coverage is 100% with descriptions for all parameters. The description only notes 'optional tasks', which is already in schema. No additional parameter meaning is added.

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 'Propose a NEW milestone' with optional tasks, going to inbox for adoption. It distinguishes from siblings like update_milestone and add_task by indicating a creation proposal.

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 proposing new milestones but does not explicitly state when not to use or highlight alternatives. Siblings include update_milestone and add_task, but no guidance is given.

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

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

Description states 'Non-destructive,' which aligns with annotations (destructiveHint=false) and adds clarity. It also describes the outcome (proposal → Inbox to Adopt). No contradictions, but does not detail authorizations or rate limits.

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

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

The description is compact (two sentences plus a short note) and front-loads key information. Every phrase adds value, though it could be slightly more structured.

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

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

Given 4 parameters with full schema coverage and no output schema, the description effectively covers usage context, behavioral traits, and parameter semantics. It provides enough information for an AI agent to select and invoke the tool correctly without 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 100%, so baseline is 3. The description adds value by clarifying that 'parent' makes the screen a POPUP overlaying an existing screen, and 'purpose' is used to ground element suggestions—beyond what the schema names and descriptions provide.

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

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

The description clearly states it is for proposing a new screen (HUD + flow node) that goes to Inbox to Adopt. It distinguishes from sibling tools by noting it is 'SECONDARY (user-driven UI)' and directs users to run design_ui_from_systems for whole UI generation.

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 when to use this tool (user-driven screen proposal) and when to use an alternative (design_ui_from_systems for whole UI). It also explains that pending screens from the same batch can be referenced by elements/edges and adopted together.

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 transparency beyond the annotations: it explicitly states 'non-destructive' (consistent with destructiveHint=false) and explains the behavioral trait that 'the owner adopts' the proposal. It also defines the spec structure, which is not covered by 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 extremely concise (2 sentences) and front-loaded with the core purpose. It includes the alias without extra fluff. Every sentence adds value.

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

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

Given 5 parameters and no output schema, the description covers the essential context: purpose, usage, and key behavioral traits. It lacks explanation of what the tool returns, but for a proposal tool this is often implicit. It is nearly complete for an agent to use effectively.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description mentions the spec format and batch parameter briefly, but the schema already describes all parameters well. The description adds minimal additional 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 clearly states the tool's purpose: 'Propose a NEW system spec' and specifies the outcome '→ Inbox (non-destructive; the owner adopts)'. It distinguishes from sibling tools by advising to use update_system if the system already exists. The verb and resource are specific and unambiguous.

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

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

The description provides explicit guidance: 'Check list_systems/search first — if it already exists, use update_system instead.' This tells the agent exactly when to use this tool and when to use an alternative, which is excellent for decision-making.

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 destructiveHint=false and idempotentHint=true. The description adds valuable behavioral context: the rename applies live (not a proposal), and flow links/elements follow automatically since they reference by ID. No contradictions found.

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 core action, no unnecessary words. Every sentence adds value.

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

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

For a simple rename tool with 3 parameters and no output schema, the description covers purpose, in-place behavior, link handling, and name source. It's complete enough for an agent to use 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 has 100% coverage with descriptions for all parameters. The description adds 'Identify it by its current name' and references list_screens/get_project_context for the name parameter, but doesn't significantly enhance beyond what the schema provides.

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

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

The description clearly states the tool renames a screen in place, distinguishing it from sibling tools like propose_screen and get_screen. 'Rename an existing screen IN PLACE' is a specific verb+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?

The description provides clear context: rename is direct, safe, reversible, and names are from list_screens/get_project_context. It lacks explicit when-not or alternative tool mentions, but 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?

Annotations already provide idempotentHint true and destructiveHint false. The description adds 'safe & reversible' and explains omitted entries keep relative order, which is useful beyond annotations.

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

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

Two sentences efficiently cover purpose, safety, and parameter details. Front-loaded with key info, no 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?

All 6 parameters are adequately explained in schema and description. No output schema but not needed for reorder. Description provides complete guidance for correct usage.

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

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

With 100% schema coverage, baseline is 3. The description adds significant meaning: order can include milestone names, omitted entries keep order, and specifies required additional parameters for tasks and elements.

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 reorders milestones, tasks, or elements, with specific verb 'Reorder' and resource types. It also distinguishes three kinds and mentions direct application.

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 indicates when to use (reordering these items) and notes additional parameter requirements for tasks and elements. However, it does not explicitly mention when not to use or compare to sibling tools like propose_milestone or update_milestone.

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

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

Annotations indicate idempotentHint: true and destructiveHint: false. The description adds behavioral context: it shows immediately (not an inbox item), it replaces the files list on each call, and empty files on non-todo yields a specific display. This goes beyond annotations but does not detail authorization or rate limits.

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

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

The description is a single sentence that packs multiple instructions and caveats. While it is not excessively long, it could be better structured with separate sentences for each aspect (e.g., status display, files guidance, decisions guidance). It is somewhat run-on.

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 7 parameters, 1 required, and no output schema, the description covers the main points: status, files, decisions, version. However, it does not explain the return value or what the agent receives after a successful call. Given the complexity, a mention of the response 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?

Schema description coverage is 100%, so baseline is 3. The description adds meaningful semantics: for files it explains the system-to-code map and replacement behavior; for decisions it clarifies they are prose notes not in files; for version it explains how it anchors decisions in history. This enhances the schema.

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

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

The description clearly states the tool reports build status of a SYSTEM with a live badge showing todo/in-progress/implemented and immediately visible, not in inbox. The verb 'report' and resource 'system build status' are explicit. However, it does not explicitly differentiate from sibling tools like report_drift or report_milestone_progress, which would make it 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?

The description provides usage guidance on passing files and decisions, including that files are replaced on resend and that non-todo with no files shows as done-but-EMPTY. However, it does not clearly indicate when to use this tool versus alternatives like report_screen_status or report_milestone_progress, leaving the agent to infer from the tool name alone.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description adds behavioral details: 'Advisory only (blocks nothing)', how the flag appears and is cleared, and parameter usage. 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 consists of two well-structured sentences that front-load the main action and then provide necessary detail. Every phrase adds value without redundancy.

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

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

Given the tool's advisory nature and lack of output schema, the description adequately explains input parameters, behavior, and interaction with sibling tools. It could explicitly state the return value but the overall context is sufficient.

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

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

Schema coverage is 100% with 5 parameters. The description adds value by explaining the purpose of missing_files and note in context (e.g., 'Pass the stale paths in missing_files'). It enhances the schema descriptions with practical usage guidance.

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

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

The description clearly states the verb 'Flag' and the resource 'CODE DRIFT on a system', and explains the condition (system→code map mismatch) and effect (advisory flag). It distinguishes from siblings by referencing related tools like get_build_region and 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 specifies when to use (when the code map no longer matches the repo) and what the tool accomplishes (advisory flagging). It also explains how to clear the flag using report_build_status, providing implicit context but no explicit when-not-to-use or alternatives.

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

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

Annotations already cover idempotency (true) and destructiveness (false). Description reinforces 'Non-destructive' but adds minimal new behavioral context beyond that.

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

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

Extremely concise: three brief phrases that cover action, example, prerequisite, and safety. 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?

Covers action, prerequisites, and safety. Lacks output description but given no output schema and simplicity, it's adequate. Mentions resulting 'Inbox progress card' for context.

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

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

Schema coverage is 100% with clear parameter descriptions. Description adds value by advising to use exact names from get_project_context, improving parameter usage.

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

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

Clearly states action ('Mark tasks... as done') and resource ('existing milestone'). Differentiates from siblings like propose_milestone (create) and update_milestone (modify properties) by emphasizing existing milestone.

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

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

Provides explicit guidance on sourcing data ('Use exact milestone + task names from get_project_context'). Implies alternatives by specifying 'existing', but does not explicitly list 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 adds context beyond annotations by explaining the workflow (report -> inbox -> owner adopts) and stating it's non-destructive, which aligns with annotations. No contradictions.

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

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

Two sentences with no wasted words. Front-loaded with the core purpose, followed by usage context and safety statement.

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 no output schema, the description explains the overall flow and context adequately. It covers parameter usage and the outcome, though could briefly mention the inbox mechanism.

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

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

Schema coverage is 100%, so the schema already documents parameters. The description reinforces the source of screen names and adds slight context, but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the action (report), the resource (SCREEN's build status), and the outcome (inbox for owner to adopt). It distinguishes from the sibling 'report_build_status' by focusing on screens.

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?

Guidance is provided on when to use ('as you build out a screen') and how to identify the screen. However, it does not explicitly mention when not to use or alternatives like 'report_build_status'.

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

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

Annotations (readOnlyHint: false, destructiveHint: false) indicate mutation but non-destructive. The description adds the behavioral effect: 'unlocks the owner's Clear button' and explains the workflow consequence. No contradictions.

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

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

Two sentences, front-loaded with action, no wasted words. Every sentence adds critical usage 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?

With 100% schema coverage and no output schema, the description fully explains the tool's purpose, prerequisites, effect, and parameter usage. Complete for a simple tool.

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

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

Schema coverage is 100% and description adds meaning: for 'title', it specifies 'exactly as get_rejections returned it'; for 'project_id', 'omit = the connector URL's project'. This exceeds what the schema provides.

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

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

The description clearly states the tool's action: 'Tell the owner you've REVERTED a declined change'. It identifies the specific verb (resolve/revert) and resource (rejection), and distinguishes from sibling tools 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?

The description explains when to call it ('right after you bring the build back in line') and the prerequisite (pass the rejection's title). It also describes the effect (unlocks owner's 'Clear' button). It lacks explicit when-not-to-use but provides clear context.

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

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

The description adds behavioral details beyond the annotations: it states case-insensitive search, compact hit structure with kind/id/name and snippets for body matches, and optional kind limiting. The annotations already indicate read-only, idempotent, non-destructive behavior, and the description enriches this with specific output format and search 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 with two sentences. The first sentence is dense but clear, and the second sentence adds the optional parameter. It is front-loaded with the core purpose. Slight improvement possible by breaking the first sentence for 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?

Given no output schema, the description adequately explains the return format (compact hits with fields). Combined with high schema coverage and supportive annotations (readOnlyHint, idempotentHint), the description covers all essential aspects 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 coverage is 100% with good parameter descriptions. The description adds minimal semantic value, only reiterating that `kinds` is optional. For high schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the verb 'search' and the resource 'project', and explicitly lists the entity types it can find (milestone, task, system, screen, context, open question). This distinguishes it from sibling tools like list_milestones or get_project_context, which target specific entities.

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 good context on when to use the tool ('without scanning the whole context') and mentions the optional `kinds` parameter to limit results. However, it does not explicitly state when not to use it or provide direct comparisons to alternative tools.

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

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

Adds context beyond annotations: describes operation as live, safe, reversible, and notes element already adopted, complementing idempotentHint and not contradicting other 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?

Front-loaded with main purpose and includes essential usage notes. Efficient though could trim slightly; overall well-structured for agent 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?

Covers identification, live nature, and canvas behavior. No output schema but description sufficiently explains tool use among 42 siblings. Minor gaps in response 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?

Adds meaning beyond schema by explaining that passing x+y pulls unplaced elements onto canvas and that label must be unique, providing valuable context for agent decision-making.

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 updates existing elements (move/resize/relabel/retype) and distinguishes from delete+re-propose, providing specific verb and resource.

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 guidance to apply directly to live elements, advising against delete+re-propose, and mentions preferred identification method. Lacks explicit comparison to sibling tools.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds key behavioral context: edits are applied 'DIRECTLY (live)' and renaming does not create a new ID. No contradictions with annotations.

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

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

Two sentences with all critical information front-loaded. Every word serves a purpose; no redundancy or filler.

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

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

Given no output schema, the description covers the core behavior for a mutation tool with 7 optional parameters. It explains live application and rename semantics. Could mention that only provided fields are updated, but that's implied by optionality.

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 100% coverage with descriptions for all 7 properties. The description reiterates the rename behavior and identification method but does not add significant new 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 starts with a specific verb 'Edit' and resource 'milestone', listing the editable fields (goal, weeks, difficulty, name). It clearly distinguishes from sibling tools like propose_milestone (for creation) and delete_entity (for deletion).

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 explains when to use this tool for renaming versus delete+recreate ('never delete+recreate — that mints a new id'). It also provides preferred identification method ('by id or exact unique name'). However, it does not explicitly contrast with propose_milestone for creating new milestones.

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 update is a reviewable diff in inbox (owner adopts) and explicitly states 'Non-destructive'. Aligns with annotations (idempotentHint=true, destructiveHint=false). Adds value beyond annotations.

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

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

Two sentences, well-structured with em dashes for bullet points. No extra words, every sentence adds value. Front-loaded with the main action.

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

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

Covers all aspects: prerequisite (read get_system), core action (send full spec), optional features (rename, update context). No output schema needed; behavior is clear.

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

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

All parameters have schema descriptions (100% coverage). Description adds meaning: spec is 'full revised markdown', context requires context_title, new_title renames. Clarifies relationships and constraints.

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 proposes an update to an existing system via a reviewable diff. It distinguishes from siblings like propose_system (new system) and update_element (element-level update).

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

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

Provides explicit workflow: read get_system first, then send full revised spec. Explains optional renaming (new_title) and updating upstream idea (context_title+context). Lacks explicit when-not-to-use or alternatives like propose_system, but context is clear.

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

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

Discloses error condition if another holds claim, explains override with force:true, and release on done:true. Annotations already indicate non-readonly, idempotent, non-destructive; description adds context beyond annotations.

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

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

Description is dense but well-structured, front-loaded with core action, then details on claiming, then release/override. No fluff, each sentence adds value.

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

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

Despite no output schema, description covers key scenarios: edit fields, claim, error handling, release, and sibling differentiation. With 8 parameters and complex behavior, it's complete enough for agent to use 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 100%, so baseline 3. Description adds meaning: assignee:'me' vs '' for claim/release, done:true releases, effort enum explained, status as work-status label. Adds value beyond schema.

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

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

Description clearly states it edits a task or claims it, specifying fields like name, done, status, effort, assignee. Distinguishes from siblings by noting alternative use of report_milestone_progress for human review.

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

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

Explicitly instructs when to claim ('CLAIM before you build'), how to handle stale claims with force:true, and when to use report_milestone_progress instead. Also explains that done:true or assignee:'' releases claim.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds context: the tool 'removes it before the owner adopts', clarifying the nature of the removal as a cancellation rather than permanent deletion. It does not discuss side effects, but enough context is provided for a safe usage.

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 main action and purpose, followed by parameter guidance and constraints. Every sentence adds necessary information with no redundancy.

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

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

Given the simple nature of the tool (two parameters, no output schema), the description covers the action, preconditions (must be own, pending), how to obtain the id, and the effect. It is sufficiently complete for an agent to use 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 provides full descriptions for both parameters (100% coverage). The description adds value by explaining how to obtain the `id`: 'Pass the `id` from the propose call's response or get_inbox.' This guidance is helpful 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 specifies exactly what the tool does: 'Withdraw YOUR OWN still-pending Inbox item (a propose_* / delete_entity you made by mistake)'. It clearly distinguishes from sibling propose_* and delete_entity tools by targeting only pending items authored by the user.

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 when to use the tool: to remove your own pending item before adoption. It also provides conditions: 'Only items you authored and only while pending.' It does not explicitly list when not to use it, but the conditions imply it is not for others' items or adopted items.

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