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

No annotations are provided, so the description carries the full burden. It describes what the tool detects but does not explicitly state whether it is read-only or has any side effects. The name 'analyze' implies non-destructive behavior, but the description lacks an explicit guarantee. It does add the context that it complements source reading, which is useful, but does not cover all safety concerns.

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 three sentences that are all purposeful. It front-loads the purpose, lists detected items, gives usage guidance, and adds a limitation. No redundant information, well-structured for quick reading.

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 moderate complexity and lack of output schema, the description adequately covers what the tool does and when to use it. It explains the scope (detects various aspects) and provides a limitation (does not replace reading source). Minor gap: it does not describe the output format or whether the analysis is returned as a report, but for a single-parameter tool with no output schema, the description is sufficiently complete.

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

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

Schema description coverage is 100%, with one parameter (appPath) clearly described as the absolute path to the app's root folder. The description does not add additional parameter-specific details, so it earns the baseline score of 3. No extra semantics are provided 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 with a specific verb ('understand an existing app') and resource (app codebase). It enumerates what it detects (frameworks, language, dependencies, capabilities, folder structure, issues), and distinguishes it from siblings by positioning it as the FIRST tool to use for existing apps. This differentiates it from tools like import_app, test_app, and suggest_improvements.

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

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

The description explicitly states when to use it: 'Use this FIRST when asked to understand, improve, fix or extend an app that already exists.' It also provides an exclusion by noting it complements but does not replace reading the actual source code. This gives clear context and alternative behavior.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It reveals that execute=false only generates configs and commands, execute=true executes the deployment, and success marks the project done. It does not detail failure behavior or side effects beyond 'done', but the core behavior is transparent and actionable.

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 concise sentences, each with a distinct purpose: state the action, explain the two execution modes, and note prerequisites/success outcome. No filler words, and the most critical information is front-loaded. The structure is easy to parse.

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

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

For a 4-parameter tool with no output schema or annotations, this description is largely complete. It covers main behavior, mode differences, prerequisites, and post-conditions. However, it does not describe the return format (even though no output schema exists), nor does it mention failure handling or recovery steps. Given the tool's complexity, a slightly richer description would be ideal, but this is still strong.

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

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

The schema has 50% coverage (appPath and execute have descriptions; target and projectId do not). The description adds meaning by clarifying the execute parameter's role and giving an example of generated files (Dockerfile/compose for docker). While it doesn't elaborate on target or projectId, the enum for target and the phrase 'app root' for appPath provide enough context for correct invocation.

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

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

The description opens with a clear verb and resource: 'Deploys the finished app.' It distinguishes itself from sibling tools like run_audit or generate_blueprint by focusing on the deployment step. The two modes (execute=false/true) are introduced immediately, leaving no ambiguity about the tool's core function.

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 an explicit prerequisite: 'Only available once the audit has passed.' It also explains when to use the tool with execute=false (generate configs/commands) versus execute=true (actually deploy). While it doesn't name alternatives like get_deploy_options, the guidance is clear enough for an agent to choose this tool for deployment 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?

With no annotations, the description carries the full burden. It discloses a key behavioral trait: the tool advances the project to the interview phase (a side effect). It also describes the return value structure. It does not mention idempotency or error conditions, but the disclosed mutation is a significant addition beyond generic 'enhance' semantics.

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: the first front-loads the workflow position, the second lists inputs, outputs, and side effects. Every word earns its place; there is no fluff or repetition.

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

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

For a single-parameter tool with no output schema or annotations, the description covers the core: what it does, what it returns, and its side effect. It omits prerequisites (e.g., project must exist) but the workflow context and sibling tools provide sufficient completeness for an agent to invoke it correctly.

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

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

Schema coverage is 0%, so the description must compensate. It does not explicitly explain that projectId identifies the project whose description is analyzed, but the phrase 'the project description' indirectly links the parameter. Since there is only one obvious parameter with a clear name, the gap is minor, but the description adds no direct semantic detail.

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

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

The description clearly states the tool's function: it analyzes a project description against a checklist, returns a master prompt skeleton and gap list, and advances the project phase. The specific verb 'analyzes' and the detailed outputs distinguish it from sibling tools like get_next_questions or generate_blueprint.

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

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

The description explicitly labels this as 'Phase 1 of the App Factory workflow,' providing strong context for when to use it. It does not explicitly mention alternatives or exclusions, but the workflow phase makes the intended usage clear.

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

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

With no annotations provided, the description carries the behavioral burden and discloses the key transformation: HTML is stripped and readable text is returned. However, it does not cover edge cases like redirects, timeouts, or handling of non-HTML content, preventing a higher score.

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 efficient: two sentences accomplish purpose, output, and usage context. It is front-loaded with the verb and resource, followed by direct use-case guidance, with zero filler.

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

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

For a simple fetch tool, the description covers the core purpose and output, but the unexplained maxChars parameter and lack of any error/edge-case behavior leave a noticeable gap. With no output schema or annotations, the description should have done more to explain the tool's full behavior and parameter semantics.

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

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

Schema description coverage is only 50% (url has a description, maxChars does not). The tool description adds no meaning for maxChars—such as what it limits or how it behaves—so the agent cannot infer its purpose or range trade-offs. The description is entirely silent on parameters, failing to complement the schema gaps.

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

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

The description uses the specific verb 'Fetch' with a clear resource (URL) and defines the output as 'readable text content (HTML stripped)', which fully distinguishes it from sibling tools like web_search. It also names concrete use cases, making the purpose unmistakable.

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

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

The description explicitly states when to use the tool ('reading documentation pages, API references or content the user linked'), providing clear context. It does not mention exclusions or alternatives, but the use-case framing is sufficient guidance for an agent.

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

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

With no annotations, the description carries the burden. It discloses key behaviors: it compiles inputs into a blueprint, launches subagents, and advances the project to the build phase. However, it doesn't mention prerequisites (e.g., project must be in phase 3), side effects beyond state progression, or error conditions, leaving gaps.

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

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

The description is a dense paragraph of three sentences. Each sentence adds value: phase identification, compilation behavior, and parallelization instructions. It is front-loaded with purpose and not overly verbose, though the subagent launching instructions could arguably be trimmed without losing essential clarity.

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

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

Given the workflow complexity (parallelization, phase advancement) and lack of output schema, the description explains the tool's role, how to invoke it, and what to do afterward. It is reasonably complete for an agent to act, though preconditions and return values are not specified.

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

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

Schema coverage is 50% (workspacePath has a description, projectId does not). The description does not add parameter-specific meaning, but the parameter names are self-explanatory and the tool's role in the workflow implies what they are. Baseline 3 is appropriate since the description neither clarifies nor obscures.

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: 'Compiles the description, interview answers and design choices into a build blueprint with parallelizable work packages.' It uses a specific verb ('compiles') and resource ('build blueprint'), and distinguishes itself from sibling workflow tools by identifying as Phase 4 of the App Factory workflow.

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 usage context: 'Phase 4 of the App Factory workflow' and detailed instructions on launching parallel subagents per work package. It doesn't explicitly name alternatives or exclusion criteria, but the phase-based context and actionable step-by-step guidance make usage clear.

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

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

With no annotations provided, the description must disclose side effects. It clearly says the agent should 'Write the returned documents into the app as /privacy, /terms (and /cookies) pages and implement the compliance checklist items,' which implies modifying the app. It also includes an important disclaimer that these are templates, not legal advice. However, it doesn't detail permissions or potential irreversible changes.

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 and front-loaded with the core function, followed by operational instructions. Each sentence contributes meaningful information without redundancy. It could be slightly more compact, but the structure is logical and easy to parse.

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

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

Given the tool's complexity (10 params, no output schema), the description covers key aspects: what it generates, that it writes to the app, and the need to ask for inputs. It lacks detail on the return format (e.g., whether documents are returned as files or text) and edge cases, but overall it provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is low (40%), so the description must compensate. It highlights 'regions' and 'dataCollected' as key inputs, noting the region-aware nature of the output. However, it doesn't explain other parameters like usesCookies, usesPayments, usesAnalytics, or childrenUnder13, leaving ambiguity. The description adds some value but not enough to fully bridge the coverage gap.

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

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

The description clearly states the tool's function with a specific verb ('Generates') and resource ('legal document templates') plus a compliance checklist. It lists concrete document types (Privacy Policy, Terms of Service, Cookie Policy) and regulations (GDPR, CCPA/CPRA, DPDP, COPPA, PCI-DSS), making it distinct from all sibling tools like generate_blueprint.

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

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

The description gives actionable usage guidance: 'Ask the USER for the inputs first - especially regions and what personal data the app collects.' It also states what to do after generation (write documents into the app, implement checklist). It doesn't explicitly mention when not to use or provide alternatives, but the context is clear and specific.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It explains that the tool reconstructs context including project state, journal timeline, and memories, and describes the global recap without a projectId. This gives a solid understanding of what to expect, though it does not explicitly state side effects (e.g., read-only) or performance implications.

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, concise, and front-loaded with the core purpose. Each sentence adds valuable information: the main functionality, conditional behavior, and when to call it. There is no unnecessary wording or redundancy.

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

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

For a context-reconstruction tool with no annotations and no output schema, the description explains the core functionality and the two modes well. However, it omits details about the eventLimit parameter and does not describe the return format or structure, which leaves some incompleteness. It is sufficient for an initial understanding but not fully comprehensive.

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

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

The input schema has 0% description coverage, so the description must compensate. It explains the projectId parameter well by detailing the difference between providing it and not. However, the eventLimit parameter is entirely unexplained; the description does not mention how it affects the results or its default behavior, leaving a gap.

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

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

The description clearly states the tool's purpose with a specific verb ('reconstructs context') and outlines the exact scope: what is happening, what has happened, and what to do next. It distinguishes itself from siblings by detailing two modes (with/without projectId) and mentioning journal timeline and memories, which differentiates it from tools like get_project_state or list_projects.

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

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

The description provides explicit guidance on when to use the tool: 'at the START of any session that continues earlier work, after context loss, or whenever unsure what already happened.' It does not name specific alternatives or when-not-to-use scenarios, but the conditional behavior (with/without projectId) offers clear situational 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?

With no annotations provided, the description carries the full burden. It states the tool 'lists' deployment targets, implying a read-only operation, and adds workflow instruction about presenting options and calling deploy. However, it does not disclose side effects, permission requirements, or return format, leaving some behavioral aspects unclear.

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 that front-load the core purpose and then provide actionable workflow guidance. Every sentence adds value without redundancy or fluff.

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

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

The description adequately situates the tool within a larger workflow (Phase 6) and explains the expected next step (call deploy). However, it omits details about the return structure of the list and does not mention projectId, leaving minor gaps for a simple one-parameter tool.

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

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

The schema has no parameter descriptions (0% coverage), and the tool description does not explain the 'projectId' parameter at all. While the name is self-explanatory, the description fails to compensate for the lack of schema details, leaving the agent to infer its meaning and usage.

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

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

The description clearly states the tool 'Lists deployment targets with requirements and steps', using a specific verb and resource. It also identifies it as 'Phase 6 of the App Factory workflow', which distinguishes it from sibling tools like deploy that perform the actual deployment.

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 on when to use this tool by labeling it 'Phase 6' and instructing to 'present the relevant options to the USER... and ask which they want, then call deploy.' This implies it precedes deploy, though it does not explicitly mention alternatives or exclusions.

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

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

With no annotations, the description carries the full burden. It discloses the waiting=true behavior, the requirement to retry, and the side effect of advancing to blueprint phase when all four choices exist. This goes beyond a simple 'reads selections' statement.

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 concise sentences: action, waiting behavior, and completion condition. Front-loaded and free of waste.

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

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

For a simple read tool with one parameter and no output schema, the description covers the essential usage and behavior. Missing a bit of detail on the exact return contents, but the purpose and workflow are clear enough.

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

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

Schema description coverage is 0%, so the description should explain the projectId parameter. It does not mention projectId at all, leaving the agent to infer its meaning from context. This is a gap.

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

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

The description clearly states the tool reads the user's design choices from the design gallery. The verb 'reads' and resource 'selections' distinguish it from sibling tools like set_design_choice and launch_design_gallery.

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 on handling waiting states: if waiting=true, ask the user to finish and call again. It also implies this is the correct poll/read tool after the user interacts with the gallery, though it does not explicitly name 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?

With no annotations, the description carries the full burden of behavioral transparency. It discloses the IP caution (never copy logos/trademarks), the scope of content (palette directions and public UI patterns), and that it should be used to derive design tokens and confirm with the user.

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

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

The description is information-dense and well-structured: main purpose, use cases, IP warning, and filtering options. No filler; the category list and caution are necessary.

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

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

For a tool with no output schema, the description covers the tool's content, use cases, safety constraints, and filtering. It doesn't specify exact return shape or pagination, but it implies a list of inspirations via 'pick an inspiration', which is adequate given the tool's scope.

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 only 33% of parameters, so the description compensates by explaining query as matching name/traits and listing all category values. It does not explain limit, but the default/max are in the schema, and limit is unambiguous.

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

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

The description clearly identifies the tool as a library of design languages from ~100 famous apps, with explicit use cases for answering 'make it look like X' or building custom themes. It distinguishes itself from gallery presets by offering broader design directions.

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

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

The description explicitly tells the agent to use it when offering broader design directions than gallery presets, answering 'make it look like X', or building a custom theme. It does not name a specific sibling tool for exclusion, but the contrast with gallery presets 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?

No annotations are provided, so the description fully carries the burden. It discloses workflow behavior (phase transition), presentation guidance (multiple-choice), and handling of special answers ('skip', 'use your judgment'). However, it does not explicitly state whether the tool is read-only or describe the return format, leaving some ambiguity.

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

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

The description is four sentences, each earning its place: it gives workflow context, a clear purpose, user interaction instructions, and post-condition. No filler or redundancy.

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

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

The description thoroughly explains the tool's role in the workflow and how to handle responses, but it lacks details about the return value's structure (e.g., array of question objects, options format). Since there is no output schema, this is a notable gap. Still, the workflow context helps compensate.

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

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

The schema has one parameter, projectId, with no description (0% coverage). The description does not mention projectId at all, so it adds no meaning beyond the parameter name itself. Since the schema coverage is low, the description should compensate, but it does not.

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 'Returns the next batch of unanswered planning questions' – a specific verb and resource. The phrase 'Phase 2 of the App Factory workflow' provides context, and it is distinct from sibling tools like record_answer which saves replies.

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 explains when to use it ('Phase 2 of the App Factory workflow'), how to use the results ('Present them to the USER... then save each reply with record_answer'), and what happens afterward ('When no questions remain the project advances to the design phase'). This gives an agent a clear workflow sequence 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?

With no annotations, the description carries full behavioral disclosure. It clearly communicates what the tool returns (full state including next steps), which is appropriate for a read-only state retrieval tool. The description could add more detail about response format or side effects, but it covers the essential 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 only two sentences, front-loaded with the return content and ending with a usage directive. Every word earns its place; there is no redundancy or unnecessary detail.

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

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

For a simple getter tool with a single parameter and no output schema, the description is quite complete. It explains what the tool provides (full state, including next steps) and when to call it. It lacks details on the exact structure of the returned state, but the enumerated components help 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?

The input schema has one required parameter, projectId, with 0% description coverage. The description does not mention the parameter or provide any context beyond the schema. While the parameter is self-explanatory from its name and type, the description adds no semantic value to help the agent understand how to supply the project identifier.

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 state of an App Factory project, enumerating specific components (phase, interview answers, design choices, work packages, recent audits, and next steps). This distinguishes it from narrower sibling tools like get_next_questions, get_design_choices, and get_work_package, making its purpose unambiguous.

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

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

The description explicitly instructs to 'Call this whenever unsure how to proceed,' giving a clear directive for when to use this tool over alternatives. This is strong usage guidance in terms of situational context, even if it doesn't enumerate exclusions.

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

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

No annotations are provided, so the description carries the burden. It discloses the return content and implies a read-only operation, but does not cover error cases, prerequisites, or varying output by package type beyond the scaffold template note.

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

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

Two sentences, front-loaded with the main purpose and output contents, followed by a practical handoff instruction. 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?

Without an output schema, the description adequately describes the return value's key components. It also provides an actionable usage directive. Missing parameter details and error behavior prevent a perfect score.

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

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

Schema description coverage is 0%, and the description does not explain projectId or packageId. It only implicitly associates packageId with the work package, leaving parameter semantics under-specified.

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 full spec for one work package, listing specific contents (instructions, done criteria, interview answers, design choices, scaffold template). This is a specific verb+resource that distinguishes it from sibling tools.

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

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

The description implies when to use the tool: when you need the complete spec to pass verbatim to a subagent. It provides clear context but does not explicitly mention alternatives or when not to use it.

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

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

With no annotations provided, the description carries the full burden of disclosure. It explicitly states that the tool analyzes the codebase, creates a project in phase=audit, journals the baseline, and places the project in maintenance mode. This goes beyond simply saying 'import' and gives meaningful behavioral context, though it does not discuss potential errors or reversibility.

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

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

The description is two sentences, front-loaded with the primary purpose. The second sentence efficiently conveys the resulting workflow. No wasted words.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description fully covers what happens on import, the resulting project state (maintenance mode, phase=audit), and the continuation workflow. Enough for an agent to select and invoke the tool correctly.

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

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

The input schema provides 100% coverage with descriptions for both parameters (appPath and goal). The description does not add parameter-specific details beyond the schema, but the schema descriptions are sufficient, so the 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 tool's action: 'Adopt an already-built app as an App Factory project in maintenance mode.' It specifies the resource (existing app) and the outcome (project creation with phase=audit), distinguishing it from other project-related tools like start_project.

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

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

The description gives clear context for when to use this tool: when you have an already-built app to adopt. It also outlines the downstream improve/fix loop, implying this tool is a prerequisite to suggest_improvements, test_app, etc. However, it does not explicitly contrast with alternative tools like start_project.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly explains that answers are auto-filled from description and preferences, the design gallery is opened for user selection, and then the standard pipeline continues. This is substantial behavioral context, though it does not mention side effects or prerequisites like existing projects.

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

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

The description is concise and well-structured. The first sentence states the purpose, followed by the distinguishing shortcut behavior, then the exact next steps. Every sentence provides necessary information with no filler.

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

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

The description effectively covers the essential context: the shortcut nature, what data is used, the design gallery interaction, and the follow-up pipeline. It does not mention return values or error handling, but given that this is a flow tool and there is no output schema, the description 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 schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful instruction that all content (business info, texts, links, images) should be passed in the 'description' parameter, which enhances understanding beyond the schema's generic 'Everything known about the site'.

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

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

The description clearly states the tool creates a website via a shortcut flow, using available data and skipping the deep planning interview. It distinguishes itself from sibling tools like start_project by explicitly describing its fast path and immediate design gallery opening.

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 conveys when to use the tool: when there is available data and the user wants to skip the planning interview. It also explains the subsequent pipeline steps. However, it does not explicitly contrast with alternatives like start_project or list when not to use it, so it falls just short of a 5.

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

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

With no annotations, the description covers key behaviors: starts a local web page, opens the browser, requires user interaction, and provides a fallback if the browser doesn't open. It also implies a return value (the URL). It doesn't discuss potential side effects or asynchronous behavior, but the core behaviors are disclosed.

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

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

The description is three sentences, front-loaded with the main purpose. Every sentence adds value: the workflow phase, what the tool does, the user interaction, and the fallback. No filler or redundancy.

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

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

Despite having only one parameter and no output schema, the description explains the tool's role, user interaction, next steps, and a fallback. It could mention prerequisites (e.g., project must exist) or whether it blocks, but it is largely complete for a simple launch tool.

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

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

The schema has one parameter (projectId) with no description, and the description does not mention or explain it. Since schema coverage is 0%, the description should compensate but doesn't, leaving the parameter's meaning entirely to its name.

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 specific action: 'Starts a local web page... showing live UI style mockups' and provides context as 'Phase 3 of the App Factory workflow.' It distinguishes from siblings by explaining what the gallery does and how to proceed afterward.

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

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

The description gives explicit workflow context ('Phase 3 of the App Factory workflow') and instructs to call get_design_choices after telling the user to make picks. While it doesn't explicitly mention when not to use, the workflow placement and next step provide clear usage guidance.

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

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

No annotations are provided, so the description carries the burden. It clearly indicates a read/list operation, but does not explicitly state whether it is safe from side effects or mention pagination behavior. The description is not misleading, but could benefit from an explicit read-only note.

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

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

A single, focused sentence that conveys the essential information with no filler. It is appropriately sized for the simplicity of the tool.

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

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

For a simple, no-parameter list tool, the description is largely complete: it names the resource and key return field (current phase). However, it omits any mention of response format or ordering, which would be nice since there is no output schema.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The schema is empty and 100% covered, and there is nothing for the description to add about parameters.

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

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

The description clearly states the action ('List') and the resource ('all App Factory projects') with a useful qualifier ('with their current phase'). It distinguishes itself from sibling tools like get_project_state, which focuses on a single project's state.

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

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

The description implies usage when an overview of all projects is needed, but it does not explicitly mention alternatives or provide when-not-to-use guidance. The 'all' qualifier gives some context, but no direct comparison to get_project_state or other tools.

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

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

With no annotations, the description carries the burden. It adds a key behavioral note (tool calls are journaled automatically), but doesn't disclose other traits like persistence, editability, or permission requirements. It's adequate but not rich.

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

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

The description is compact and front-loaded with the main verb and resource, followed by illustrative examples and a behavioral nuance. No redundant filler; each sentence contributes.

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 logging tool with schema coverage and no output schema, the description provides enough context about what to log and how to format it. It doesn't cover edge cases or errors, but those are less critical here.

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

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

Schema coverage is 75%, and the description adds meaning beyond it by mapping the 'kind' enum to real-world examples (decision, problem, milestone, note) and illustrating detail format. This helps the agent choose appropriate values.

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 writes to App Factory's journal and gives concrete examples (decisions, problems, milestones, notes). It is specific about the resource and scope, though it doesn't explicitly differentiate from sibling tools like remember or record_answer.

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 usage context: 'Use it for things worth remembering mid-build' with enumerated categories. It also implies a when-not via 'Tool calls are journaled automatically - log the reasoning and events between them,' but doesn't explicitly name 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?

With no annotations, the description carries the full burden of disclosing behavior. It clearly indicates a read-only operation via 'Search' and 'recall', and it discloses the no-args listing behavior. It does not go into response size or edge cases, but for a search tool this is sufficient basic behavioral 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 three short sentences that front-load the primary action ('Search stored memories') and immediately follow with usage modes and a specific directive. There is no filler or redundant wording, 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?

The tool is simple with only 3 optional parameters and no output schema. The description covers the core behavior, invocation patterns, and a practical context (start of a new project). It lacks details about potential return values, but no output schema exists, so the description is reasonably complete for its complexity.

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

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

Only 'query' has a schema description ('Substring to search in keys and values'). The description merely lists 'query text, scope, and projectId' without explaining the meaning of scope or how it relates to projectId. Since schema coverage is only 33%, the description should have compensated but did not, leaving the agent to guess at the semantics of two parameters.

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

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

The description clearly states 'Search stored memories' with a specific verb and resource, and distinguishes it from the sibling 'remember' tool by indicating a retrieval operation. It also details two invocation modes (list recent memories with no arguments, or filter by query, scope, and projectId), which fully clarifies the tool's role.

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

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

The description explicitly tells the agent when to use the tool ('Call with no arguments to list recent memories, or filter...') and gives a strong situational directive ('Always recall global memories at the start of a new project'). It does not explicitly mention when not to use it or name alternatives, so it misses the full top score.

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

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

With no annotations provided, the description carries the full burden. It discloses that the answer is saved verbatim or faithfully summarized, and that certain responses trigger agent-decision marking in the blueprint. This provides meaningful behavioral context beyond the schema.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. 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?

For a simple save operation with no output schema, the description provides sufficient context: it names the target (planning interview question), specifies the data to save, and explains the consequence for skip/you decide. It is complete for the tool's complexity.

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

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

The schema covers 67% of parameters with descriptions (answer and questionId). The description adds significant semantics for the answer parameter, instructing the agent to record actual words and handle skip/you decide. It does not elaborate on projectId or questionId, but those are self-explanatory from their names and the hint about get_next_questions.

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 saves the USER's answer to a planning interview question, distinguishing it from sibling tools like get_next_questions or log_event. It also specifies the exact recording behavior for 'skip' or 'you decide'.

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

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

The description implies when to use this tool—whenever the user provides an answer during a planning interview. It also provides guidance on how to handle non-answers ('skip' or 'you decide'), which is a form of usage instruction. It does not explicitly mention 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?

The description discloses important behavioral traits: step 1 returns review material, lessons are injected into future get_context recaps and work packages, and scope affects applicability. With no annotations provided, this detailed behavioral context fully compensates.

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

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

The description is well-structured, starting with the overall concept, then breaking down the two steps, followed by scope guidance, duplicate warning, and ideal timing. Every sentence adds value, making the length appropriate for the tool's complexity.

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

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

Despite having no output schema, the description sufficiently explains what step 1 returns and what step 2 accomplishes. It covers the full workflow, lesson requirements, scope options, and ideal usage moments, making the tool completely understandable and actionable.

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 provides deep detail on the 'lessons' parameter, including formatting, evidence requirements, and scope semantics. However, 'projectId' and 'deactivateLessonIds' are not explicitly addressed; the schema covers one, but projectId lacks any explanation, leaving slight gaps.

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

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

The description clearly identifies the tool as a self-improvement loop that distills lessons from the journal, with a specific two-step call pattern. It distinguishes this from sibling tools by focusing on iteratively improving behavior from past events.

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

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

Explicit guidance is provided on when to call the tool ('after a failed audit was fixed, after a tricky bug, at project completion') and how to use it in two distinct steps. It also warns against recording duplicate lessons, giving clear do's and don'ts.

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?

In the absence of annotations, the description discloses key behavioral traits: it persists data across sessions and global memories personalize future projects. It does not cover overwrite semantics or error conditions, but for a simple memory store the provided context is adequate and goes beyond a minimal statement.

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 exactly three sentences: the primary action, scope guidance, and a note on global effects. Every sentence earns its place, and there is no redundant content or filler.

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

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

For a simple tool with no output schema and no annotations, the description covers the essential aspects: persistence, scope selection, and global personalization. It does not explicitly mention the conditional 'projectId' requirement, but that is already defined in the schema, so the description is sufficiently complete for the tool's complexity.

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

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

Schema coverage is 75%, so the description is not required to fully compensate, but it adds semantic value to the 'scope' parameter by giving real-world examples and clarifying the global vs. project distinction. The 'key' and 'value' parameters are already clear from the schema, and the description does not add further detail, which is acceptable given the coverage.

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

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

The description clearly states the tool's action with 'Persist a fact for future sessions,' specifying the resource as a memory. It does not explicitly differentiate from sibling tools like 'recall', but the verb 'persist' and title 'Store a memory' make the purpose unambiguous. Therefore, it is clear but lacks explicit sibling 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 gives strong usage guidance by explaining when to use 'global' versus 'project' scope with concrete examples such as 'favorite styles, fonts, stacks, deploy targets.' It does not, however, mention alternatives like 'recall' or state when not to use this tool, which would fully elevate it to a 5.

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

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

With no annotations, the description carries the full burden. It discloses a key side effect—that completing all packages advances the project to the audit phase—which is not apparent from the schema. This adds important behavioral context beyond the simple 'mark complete' action, though it doesn't cover other traits like reversibility or error conditions.

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

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

The description is exactly two short sentences. The first sentence front-loads the primary action ('Mark a work package complete'), and the second adds the critical phase-transition context. Every word earns its place with no redundancy.

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

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

The description covers the core purpose and the key consequence of the operation, which is useful. However, it omits any explanation of the parameters (especially projectId and packageId), does not describe what happens on success or failure, and lacks prerequisites or error handling. For a simple action tool, it's adequate but clearly has 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 only 33%, with only 'summary' having a description. The description repeats 'short summary' from the schema but adds no clarity for 'projectId' or 'packageId', which remain entirely undocumented. With low schema coverage, the description should compensate, but it fails to explain what these identifiers refer to or how they relate to the action.

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 combination: 'Mark a work package complete' clearly states the action. It also differentiates from sibling tools like get_work_package (which retrieves) and run_audit (which executes audit), making the tool's purpose unambiguous.

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

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

The description provides clear context by stating 'When every package is done the project advances to the audit phase,' implying this tool is used to progress toward audit. However, it does not explicitly name alternatives or exclusions, so it misses the 'when-not-to-use' guidance that would earn a 5.

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

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

With no annotations, the description carries full burden and does well: it discloses conditional behavior (semgrep 'if installed', Lighthouse 'if a running app url is provided'), return content ('scored report with a concrete fix list'), pass criteria ('passed=true (score >= minScore, default 80, with zero critical findings)'), and instructs self-verification of manualChecklist items. It is transparent that this is an analysis/audit tool, not a mutator.

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 but every sentence adds value: workflow phase, pipeline contents, return value, fix/re-run loop, manual checklist, and standalone usage. It is slightly long but not wasteful; front-loading with 'Phase 5' anchors it immediately.

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

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

For a complex tool with no output schema, the description is remarkably complete. It covers the full audit pipeline, the report format, the pass condition, the relationship to deploy, and the standalone mode. It even includes operational guidance ('Fix EVERYTHING in fixList and re-run') which is essential for an agent to use it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the raw schema: it explains that projectId is for App Factory projects and should be omitted for standalone audits, that appPath is the root folder, that minScore is the quality gate with a default and can be raised, and that url triggers Lighthouse. This goes beyond the schema's field titles.

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 and resource: 'Runs the full audit pipeline against the app' followed by a concrete list of checks (typecheck, lint, tests, vulnerability scan, etc.). It clearly distinguishes itself from siblings like test_app and deploy by framing itself as 'Phase 5' and defining the gate to deploy.

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

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

The description gives clear workflow context ('Phase 5', 'only then does the project advance to deploy') and explicitly covers standalone use ('pass appPath without projectId'). It does not name alternative tools for exclusionary advice, but the usage context is strong enough to guide selection.

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

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

With no annotations, the description carries the full burden. It discloses that results are sorted by stars, includes license and maintenance signals, and provides behavior guidance on preferring permissive licenses and flagging GPL. It does not specify the response format or pagination, but the disclosed behaviors are meaningful and go beyond the schema.

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

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

The description is a compact, front-loaded paragraph where every sentence delivers value: purpose, return behavior, licensing guidance, and configuration tip. There is no filler or repetition, making it appropriately sized for the tool's complexity.

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

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

The tool has four parameters and no output schema, so the description should cover both input and output. It covers input context well with examples and explains the sort order and license signals, but it does not describe the actual return structure or fields, which is a notable gap for an agent that must consume the result.

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

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

Schema description coverage is 50% (query and language have descriptions, but limit and minStars do not). The description provides an example for the query parameter and adds context for sorting, but it does not elaborate on limit or minStars semantics beyond their schema defaults and constraints, leaving a moderate gap in parameter understanding.

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

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

The description states a specific verb ('Search GitHub') and a clear resource ('GitHub') with a defined goal: finding libraries, starter kits, components, or reference implementations that support the app being built. This distinguishes it from siblings like web_search or fetch_url by focusing on code repositories and giving concrete examples.

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

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

The description gives clear usage context: when you need supporting code such as libraries, starters, or reference implementations, with examples of what to search for. It adds practical guidance on license preferences and rate-limit token setup, but it does not explicitly state when NOT to use this tool or name alternative tools for other kinds of searches.

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 are provided, so the description carries the full burden. It thoroughly describes valid choiceIds and custom JSON formats, giving insight into expected behavior. However, it does not disclose side effects (e.g., whether it overwrites existing choices), reversibility, error handling, or return values, leaving some behavioral ambiguity.

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

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

The description is long but information-dense, covering all necessary validity lists and usage context. It is front-loaded with purpose and use case. A bulleted format could improve scannability, but every sentence serves a functional purpose with 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?

The description thoroughly covers input semantics, allowed values, and special cases, which is the core of correct invocation. However, it lacks information about return values or potential errors, which would help an agent verify success. For a setter tool this is a minor gap, but the complexity warrants that information.

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

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

Schema coverage is only 25% (customValue has a description). The description compensates by enumerating all valid choiceIds for each category and providing detailed JSON structures for colors and layout, adding far more semantic meaning than the schema alone.

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

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

The description explicitly states it 'Sets one design category choice directly' and frames it as a fallback when the browser gallery cannot be used or the user stated a preference in chat, clearly distinguishing it from gallery-related 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?

It provides explicit when-to-use guidance: 'Fallback for when the browser gallery cannot be used (e.g. headless environment) or the USER stated their preference in chat.' This clearly defines the context and excludes other scenarios.

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

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

With no annotations, the description carries the full burden. It discloses the persistence behavior ('active across sessions until done'), how goals are surfaced to future sessions, and the update pathway via update_goal. It does not explicitly state whether setting a new goal overwrites an existing one, but the overall lifecycle is well conveyed.

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 core purpose, and includes a concrete example and references to related tools. Every sentence adds value with no filler.

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

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

For a simple 3-parameter tool with no output schema or annotations, the description covers the essential context: when to use, persistence behavior, how goals are retrieved, and how to update progress. It is sufficiently complete for an agent to invoke the tool correctly.

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

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

Schema coverage is only 33% (only successCriteria has a description), so the description must compensate. It provides a rich example showing the exact format for goal and success criteria, adding semantic meaning beyond the schema. However, projectId is not explained in the description, leaving some ambiguity.

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

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

The description clearly states that the tool sets a persistent goal with success criteria that remain active across sessions. It uses a specific verb ('set') and resource ('goal'), and differentiates from sibling tools like update_goal (which updates progress) and get_context/get_project_state (which surface goals).

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

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

Explicitly instructs to 'Set one at the start of substantial work', providing a clear when-to-use directive. It also contrasts with read tools (get_context, get_project_state) and the update tool (update_goal), preventing misuse.

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

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

With no annotations, the description carries the transparency burden. It discloses the workflow sequence and return value, giving the agent a clear idea of what happens. It does not mention side effects (e.g., persistence) but the 'Begin' verb implies a creating action, which is sufficient for this context.

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

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

The description is two sentences, front-loaded with the primary action, and includes necessary context (workflow stages, return value) without fluff. Every sentence earns its place.

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

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

Given there is no output schema, the description adequately explains the return value and workflow. It is slightly thin on what to do after the first step, but since sibling tools like get_next_questions exist, this is sufficient for an initial tool. It could mention prerequisites (e.g., name and description required) but the schema covers that.

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 fully documents parameters. The description adds a note to provide the user's description 'verbatim', which reinforces the intent of the `description` parameter but does not add new syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Begin the App Factory workflow') and the resource ('for a new app'), distinguishing it from sibling tools like enhance_prompt or get_next_questions by positioning it as the entry point. It also specifies the return value (project id and first step), making its purpose unambiguous.

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

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

The description implies usage context by stating it begins the workflow for a new app, which clarifies when to use it. It does not explicitly exclude alternatives, but given it is the workflow start, that is a minor gap. The mention of the workflow stages provides additional 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?

With no annotations, the description carries the full burden, and it excels. It discloses that the tool generates suggestions on two levels, can operate on stored context or codebase, and explicitly instructs the agent to present suggestions as a menu, not implement them, and add its own domain-specific suggestions. This fully informs the agent of expected 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?

Three sentences, each packed with essential information: what the tool does, how parameters work, and how to handle the output. No redundancy, no fluff, and the most critical usage instruction (present as menu, never implement) is front-loaded.

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

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

Despite no output schema or annotations, the description gives a complete picture: what the tool returns (suggestions), how to invoke it (projectId, appPath, or both), what to do with the results (present as menu, add your own), and the scope of suggestions (app and idea levels). No critical information is missing for an agent to use it correctly.

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

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

Schema coverage is only 33%, with appPath having a brief description and focus/projectId lacking descriptions. The description compensates by explaining projectId uses stored context and appPath analyzes the codebase, and that both can be used together. It does not explicitly describe the 'focus' parameter, but the enum values are self-explanatory and align with the tool's two-level framing.

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

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

The description clearly states a specific verb ('Generates improvement suggestions') and resource ('the app and its idea'), with concrete examples of what each level covers. It distinguishes itself from sibling tools like analyze_app or run_audit by focusing on generating actionable improvement ideas rather than analysis or audits.

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

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

The description provides clear context for when to use the tool: it works with a projectId, appPath, or both, and instructs the agent to present suggestions as a menu and never implement them unasked. However, it does not explicitly mention alternatives or exclusions (e.g., when to prefer analyze_app or run_audit), which would push it to a 5.

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

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

No annotations are present, so the description carries the full burden. It discloses the step-by-step behavior including running tests/build, starting the app, checking HTTP responses without server errors, and cleanly stopping it. It could additionally mention potential side effects like build artifacts or timeouts, but the overall behavior is well conveyed.

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

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

The description is two sentences, front-loaded with the core process, and every word earns its place. 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?

For a tool with 5 parameters and no output schema, the description provides a complete picture of what happens, when to use it, and what to do next (open returned URL). It lacks specifics on error behavior or return value structure, but the absence of an output schema makes that less critical. The description is sufficient for an agent to decide and invoke correctly.

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

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

Schema coverage is 60% with url, appPath, and startCommand described. The description adds flow context (e.g., 'if any' for tests/build) but does not directly explain skipBuild and skipTests beyond implying optionality. It partially compensates for the missing parameter descriptions but does not fully detail their semantics.

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

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

The description starts with 'One-step app verification' and enumerates concrete actions: runs test suite, production build, starts app, checks HTTP response, and stops it. This clearly distinguishes it from sibling tools like analyze_app or deploy by specifying the exact resource (the app) and the verification workflow.

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: 'Use after building or changing an app.' It also provides guidance for when not to use it for visual verification, directing the user to follow up with browser tools instead. This gives 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?

No annotations are provided, but the description adds behavioral context by explaining the semantics of statuses and the intent that a fresh session can pick up instantly, implying persistence. It does not detail overwrite behavior or response format, but covers key behavioral aspects.

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 redundant wording. The first sentence front-loads the core function and all details serve a purpose, making it concise and well-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?

The description covers all three parameters and provides enough context for correct invocation. No output schema exists, so return values need not be explained. It also distinguishes between status and progress updates, making it complete for the tool's complexity.

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

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

Schema description coverage is 0%, but the description compensates by fully explaining the status enum and providing a concrete example for progress ('3 of 5 packages built, audit pending'). The meaning of goalId is self-evident from the name.

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

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

The description uses specific verbs ('Record progress', 'change its status') with a clear resource ('goal'), and the focus on updating an existing goal distinguishes it from sibling tools like set_goal. It clearly states what the tool does.

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 for each status value: 'done' when all success criteria are verifiably met, 'paused' if shelved, 'active' to resume. It also advises updating progress at meaningful milestones, giving clear context on when to use the tool.

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

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

No annotations are provided, so the description carries the full burden. It discloses the underlying engine (DuckDuckGo) and the return format (titles, URLs, snippets), which is useful. However, it does not explicitly state that searches are read-only, safe, or free of side effects, nor does it mention limitations like rate limits or lack of advanced filtering. For a simple search tool, this is adequate but not comprehensive.

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

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

The description is two sentences, front-loaded with the action and purpose, and contains no fluff. Every word adds value: the engine, the use cases, and the output format.

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

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

Given the tool's low complexity (one string parameter, no output schema, no annotations), the description provides the essential context: what it does, what engine it uses, what it returns, and when to use it. It could be more complete with an explicit read-only note or error/edge-case behavior, but for a simple search tool it covers the core needs.

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

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

The schema has 0% description coverage, so the description must compensate. It offers guidance on what kinds of queries to use (documentation, libraries, best practices, current information), which adds meaning beyond the bare parameter name 'query'. However, it doesn't provide examples or specify query formatting/constraints, leaving some semantic gaps. The parameter is simple and somewhat self-explanatory, balancing the low schema coverage.

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

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

The description uses a specific verb ('Search') and resource ('the internet (DuckDuckGo)') and clearly states the intended use: finding documentation, libraries, best practices, or current information during planning or building. This distinguishes it from siblings like search_github (GitHub-specific) and fetch_url (URL retrieval).

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

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

The description provides clear context for when to use the tool ('while planning or building'), but it does not explicitly mention alternatives or when not to use it. It implies general web searches for development-related information, which helps differentiate it from search_github, but falls short of naming exclusions.

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