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

With no annotations, the description fully discloses behavior: validates every op, snapshots files, applies, verifies via frank.toJSON, and rolls back on regression. It also mentions the return payload includes applied/skipped/rolledBack/baseline/finalState.

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 fairly long but structured with a summary line followed by details. It's front-loaded and every section adds value, though it could be tightened. 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 complexity, the description covers input format, validation/apply/verify/rollback behavior, and return value. It references prescribe_frankability_fixes for op kinds, which is acceptable since that's a sibling tool. No output schema was provided, but the return fields are described.

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

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

Schema coverage is 0%, so the description must compensate. It explains ops_json format in detail (either wrapped in {'ops': [...]} or bare array) and clarifies symbols_dir is the absolute path to the symbols/ directory. This adds meaning beyond the bare 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 opens with a specific verb+resource: 'Apply LLM-generated edit ops to a Symbols project with verify-or-rollback.' This clearly distinguishes it from siblings like prescribe_frankability_fixes (which generates ops) and rollback_frankability (which reverts).

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

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

The description implies when to use it: when you have LLM-generated edit ops to apply. It references prescribe_frankability_fixes for the op kinds, but doesn't explicitly state exclusions or alternatives like audit_and_fix_frankability. Still, 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?

With no annotations, the description fully carries behavioral disclosure. It details file modification behavior, verify-or-rollback safety, the sampling-driven LLM loop, retry logic, and the exact return fields (schema, opId, findings, applied/skipped, rolledBack, baseline, finalState, llmRounds). This is comprehensive and accurate.

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?

Although long, the description is well-structured with clear mode headers and numbered steps. Every sentence either defines behavior, gives constraints, or explains mode execution. The length is warranted given 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 is complex (multi-mode, LLM integration, rollback), but the description covers all aspects: prerequisites, step-by-step flow, edge cases (retry, fallback), and return schema. No gaps are evident, even with no annotations and minimal schema descriptions.

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 richly: symbols_dir is defined as absolute path to symbols/ directory, mode enumerates valid values, aggressive is tied to medium-confidence fixes, and max_iterations caps prescriptions. It adds meaning far beyond the bare 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 runs frank-audit and optionally applies fixes, with explicit modes for report, safe-fix, and full. It references the specific resource (symbols dir) and distinct operations, distinguishing it from sibling tools that only audit, prescribe, or apply edits individually.

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 each mode, including the difference between 'report' (no modifications), 'safe-fix' (mechanical fixes with rollback), and 'full' (adds LLM loop). It also notes prerequisites like MCP sampling support and explains graceful fallback when unavailable.

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 validation happens 'against an in-memory string of code' (implying no side effects), that it returns 'a tight report with violations + warnings', and that by default it returns 'ONLY the findings (≈1–2K chars)' unless include_playbook=True. It also warns default agents should not set include_playbook. This is strong, though it doesn't explicitly state whether any external state is modified or if authentication is needed.

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

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

The description is longer than the minimal example, but it is well-structured with bolded headers, bullet lists, and distinct sections for usage and args. Every section earns its place, though some redundancy exists (e.g., repeating that include_playbook defaults to False). It is front-loaded with the core purpose.

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

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

Given the tool's complexity (a deterministic ruleset) and the presence of an output schema (not shown), the description provides enough context: it names the rule categories, describes the return report, explains output size, and references the audit playbook. It also integrates well with sibling tools and the CLI, making the overall usage context complete. The output schema can handle formal return details.

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

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

Schema coverage is 0%, but the description's Args section fully explains both parameters. component_code is defined as 'The JavaScript/DOMQL source string to validate,' and include_playbook is described with its default, effect ('Append the full audit playbook to the response'), and guidance to keep it False. This fully compensates for the missing schema descriptions.

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

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

The description clearly states it is an 'Inline VALIDATOR for a single Symbols/DOMQL component string' and lists exactly what the deterministic ruleset checks. It distinguishes itself from sibling tools by explicitly naming adjacent tools and their different scopes.

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 'Use this' section provides specific scenarios (during generation, in clients without shell access, on a single file) and the 'Adjacent tools' section explicitly names audit_project and bin/symbols-audit as alternatives for different scopes. This gives clear when-to-use and when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full burden and exceeds expectations. It discloses strict mode defaults, exhaustive behavior, deep-fix and deep-framework-audit flags, fallback ladders, transport awareness, output artifacts, phase specifics, and the rule that reports must not be TODO lists. No contradictions with annotations exist.

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

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

The description is long, but well-structured with headers and bullets, and nearly every sentence delivers critical operational detail. It is front-loaded with the core purpose. Slight verbosity in repeated references to strict mode reduces the conciseness score, but the density is justified by 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 description is exceptionally complete for a complex tool: it covers the full phase lifecycle, transport considerations, CLI companions, output artifacts, fallback behaviors, and parameters. No gaps in context remain for effective agent use.

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

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

The input schema has a single 'phase' parameter with schema description coverage of 0%, but the description fully compensates: 'Args: phase: "all" (full playbook — default) | "0" | "1" | "2" | "3" | "4" | "5" (just one phase's section)'. This adds complete meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Returns the multi-phase PROJECT AUDIT PLAYBOOK (instructions for the agent).' It explicitly distinguishes itself from siblings by noting it is 'a playbook getter, not an executor' and references sibling tools like `audit_component` and `get_project_context` as complementary roles.

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 when-to-use guidance: 'Use this when the user asks to audit, validate, refactor for compliance, or "make my project publish-ready in one shot"'. It also gives alternatives and sequencing: 'get_project_context — call FIRST' and 'Pair with the bundled bin/symbols-audit CLI'. This clearly orients the agent among sibling tools.

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

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

With no annotations, the description must disclose behavior. It explains the tool returns a 'conversion context including component catalog, syntax reference, and design system tokens,' which suggests a read-only pure function. Yet it lacks details on side effects, prerequisites, 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 efficient, with a clear first sentence and an Args block that adds value beyond the schema. The phrase 'Provide HTML code and receive...' is slightly redundant but not wasteful.

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

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

Given the presence of an output schema and one simple parameter, the description is reasonably complete. It describes the output context (catalog, syntax reference, tokens) without needing to explain return values in detail.

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

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

The schema only lists 'source_code' with a title, but the description adds 'The HTML/CSS source code to convert,' clarifying the expected input. For a single parameter, this is sufficient compensation for the 0% schema coverage.

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

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

The description clearly states 'Convert raw HTML/CSS to Symbols.app DOMQL components' with a specific verb and resource. It differentiates from siblings like convert_react and convert_to_json by naming the target format.

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

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

It instructs the user to 'Provide HTML code' and describes the output, which implies usage. However, it does not explicitly state when to use this tool over alternatives like convert_react or provide any exclusion criteria.

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

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

The description mentions that the user will 'receive the conversion context including migration rules, syntax reference, and examples,' which partially discloses the output format. No annotations are present, so the description carries the burden, but it doesn't discuss edge cases, errors, or limitations, leaving some ambiguity about whether actual converted code is returned or just supporting context.

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

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

The description is three sentences plus an Args block, with no filler. The first sentence states the purpose, the second explains the output, and the third lists the parameter—all essential information.

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

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

The tool has a single parameter and an output schema, so the description doesn't need to detail return values. However, the phrase 'conversion context' is somewhat ambiguous—it suggests the tool provides guidance rather than the converted DOMQL directly—and no details on how the conversion is performed or what limitations exist. Overall, it's a minimal viable description but has gaps for a tool with no annotations.

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

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

The schema has one required parameter, source_code, and the description adds meaning by specifying 'The React/JSX source code to convert,' clarifying the expected input beyond the schema's basic title. With 0% schema coverage, this compensation is adequate.

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 'Convert React/JSX code to Symbols.app DOMQL,' a specific verb+resource pairing that clearly distinguishes it from sibling tools like convert_html and convert_to_json. The purpose is unambiguous.

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

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

The description states the required input ('Provide React component code') and the target output, which implies the tool is for React-to-DOMQL conversions. However, it doesn't explicitly compare with convert_html or provide exclusions, so it's clear context but not full guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals a key non-obvious behavior: 'Functions are automatically stringified (as the platform stores them as strings).' It also mentions that the tool mirrors the @symbo.ls/frank toJSON + stringifyFunctions pipeline, which sets accurate expectations for the output shape. It does not cover error cases, but overall it adds significant transparency beyond the basic purpose.

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 and front-loaded with the core purpose. Each paragraph adds value: usage guidance, pipeline mirroring, and parameter explanations. It is concise without being terse, and no sentence is wasted. The Args format is clean and organized.

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

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

Given that an output schema exists, the description does not need to detail return values. It covers purpose, usage timing, a key behavioral transformation, and parameter semantics. It is complete enough for an AI to select and invoke the tool correctly, though it could mention potential limitations or prerequisites (e.g., that exports must be present) for full completeness.

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

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

The input schema has 0% description coverage, but the description compensates with an 'Args' section. It explains source_code as 'JavaScript source code with export const/default statements' and section as 'Target section — "components", "pages", "functions", "snippets", "designSystem", "state"' including how it determines categorization. This adds meaning beyond the raw schema, though the source_code description could be more detailed.

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

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

The description opens with a specific verb+resource: 'Convert DOMQL JavaScript source code to platform JSON format.' It clearly distinguishes from sibling tools like convert_react and convert_html, and further explains it parses export statements and stringifies functions, 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 explicitly states when to use the tool: 'Use this after generate_component or generate_page to get JSON that can be passed directly to save_to_project.' It gives clear context for the intended pipeline position, though it does not explicitly mention when not to use it or name alternatives (those are implied by sibling tools).

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

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

With no annotations, the description carries the full transparency burden. It discloses authentication requirements through the token and api_key parameters, explains that key is auto-generated if empty, and mentions the return value (project ID and key). This goes beyond the raw schema, though it does not cover failure modes or permissions explicitly, so a perfect score is not warranted.

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: a clear one-sentence purpose, a usage context sentence, a sentence about the return value, and a concise Args list. It is front-loaded with the most important information and contains no filler 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?

Although the output schema is not shown, the signal confirms one exists. The description explains the tool's role, when to use it, all parameters with their semantics, and what is returned (project ID and key). It also references downstream tools, giving a complete picture for a creation tool with six parameters and one required field.

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 must compensate. It does so thoroughly with an Args section explaining every parameter, including formats (pr_xxxx for key, sk_live_ for api_key), defaults (language: 'javascript', visibility: 'private'), and the auto-generation behavior for key. This adds substantial meaning beyond the schema.

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

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

The description clearly states 'Create a new Symbols project on the platform' with a specific verb and resource, and distinguishes this from sibling tools like save_to_project and publish by specifying it creates a new project rather than saving to or publishing an existing one.

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

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

The description provides explicit guidance: 'Use this when the user wants to save generated components to a new project.' It also mentions the returned ID and key are for use with save_to_project and publish, implying these are follow-up actions. However, it does not explicitly state when not to use this tool or name alternatives directly.

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 that the tool is legacy and depends on caller-supplied file flags rather than inspecting the filesystem. It also implies the output structure by referencing equivalent fields in `get_project_context`. However, it does not explicitly discuss side effects, read-only behavior, 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 well-structured with a legacy notice, a preference for an alternative, and a clear Args list. It includes some extra detail about `get_project_context`'s output, which is useful for migration but slightly extends length. Overall, every section earns its place.

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

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

Given the tool has 8 parameters and no annotations, the description covers input semantics thoroughly and provides migration guidance. Since an output schema exists, the description doesn't need to detail return values, but it still hints at the output fields by comparing to `get_project_context`. This is adequate 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%, so the description fully compensates. Every parameter (has_symbols_json, has_symbols_dir, etc.) is explained with a clear, specific meaning, e.g., 'Whether symbols.json exists in the project root.' The `file_list` parameter is also described as a comma-separated list. This adds substantial meaning beyond the raw 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 'Detect[s] Symbols environment from caller-supplied file flags,' specifying both the action and the resource. It distinguishes itself from the sibling tool `get_project_context` by explicitly noting it relies on caller-supplied flags and is a legacy alternative.

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

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

The description provides explicit usage guidance: 'Prefer `get_project_context`' and 'New code should call `get_project_context(cwd)` instead.' It also explains that this tool is 'Kept for backward compatibility with older agent prompts,' giving clear when-to-use and when-not-to-use direction.

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 behavioral burden. It explains that each rule has an `explain()` method returning human-readable descriptions, examples, and rationale, and specifies the return JSON fields. It doesn't state error behavior but is adequate for a read-only lookup.

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 efficiently structured with an opening purpose sentence, usage context, and clear Args/Returns sections. It avoids verbose language and front-loads the key action.

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

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

Given the tool's simplicity, the description provides sufficient context about usage, parameter format, and return value. It doesn't explain possible error cases, but with a clear return signature and usage, it's complete enough for an agent to invoke successfully.

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 only defines rule_id as a string, but the description's Args section elaborates with a description and concrete examples ('FA301', 'FA806'), making the parameter's meaning clear despite 0% 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 first sentence clearly states the tool returns the documentation block for a specific frank-audit rule, using the verb 'Return' and a specific resource. It distinguishes from sibling tools like audit_component or apply_frankability_edit_ops by focusing on rule documentation.

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

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

The description explicitly provides a usage scenario: 'Use this when an agent encounters an unfamiliar finding and needs context before deciding on a fix.' This gives clear context, though it doesn't 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, the description carries the full burden. It discloses the log file path, entry format (NDJSON with opId, timestamp, outcome), and that it returns the most recent entries. It also explains the limit parameter. However, it does not describe behavior on missing files or errors, leaving a minor gap.

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

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

The description is well-structured with a summary line, a context paragraph, and an Args section. Every sentence provides necessary information, with 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 simple log-tail tool, the description is complete. It specifies the log location, entry contents, parameters, and return shape ('{ ok, entries: [...] }'), enabling correct invocation and interpretation without needing to see the output schema.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains symbols_dir as 'Absolute path to the symbols/ directory' and limit as 'Maximum number of entries to return (default 50),' adding meaning beyond the bare 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 function: 'Tail the audit log for a Symbols project.' This uses a specific verb ('tail') and resource (audit log), and the explanation of returning most recent NDJSON entries distinguishes it from sibling tools like rollback or snapshot tools.

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

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

The description provides usage context: 'useful for understanding history without re-running ops.' This implies when it should be used, but it does not explicitly name alternative tools or state when not to use it. Still, it gives clear context for its intended purpose.

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

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

With no annotations, the description carries the full behavioral burden. It clearly discloses that the tool returns reference material and that the calling LLM performs the actual generation, which is a key behavioral nuance. It does not mention side effects, but the described behavior is transparent and consistent with a generation-context tool.

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

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

The description is concise, front-loaded with the primary purpose, and uses a clear structured Args section. Every sentence adds value without redundancy.

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

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

Given the output schema exists, the description need not detail return values. It sufficiently explains the tool's purpose, parameters, and the caller's role, making it complete for an agent to select and invoke the tool correctly. No significant gaps are apparent.

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 semantic explanations for both parameters, enriching the minimal schema. 'What the component should do and look like' clarifies the 'description' parameter, and 'PascalCase name for the component' adds a naming convention for 'component_name'. This compensates for the 0% schema coverage.

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

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

The description clearly states the action ('Generate') and the specific resource ('a Symbols.app DOMQL component') derived from a description. This distinguishes it from sibling tools like generate_page and convert_react, which target different outputs.

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 the tool is used to obtain reference context for generating a compliant component, but it does not explicitly state when to prefer this over alternatives or when not to use it. The distinction from siblings is inferable but not articulated.

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 return value ('Returns rules, project structure, patterns, snippets...') but does not address side effects, prerequisites, or whether it persists any changes. The ambiguity between 'Generate' and 'Returns' could confuse agents.

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

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

The description is three sentences with no redundancy. It front-loads the purpose, then summarizes return content, and finally lists the arguments. Every sentence earns its place.

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

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

Given the tool's complexity and the presence of an output schema, the description covers the essential context: purpose, key features, input parameters, and return content. It does not detail the output schema, but that is presumably captured in the schema itself.

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 explaining both parameters: description ('What the page should contain and do') and page_name ('camelCase name for the page (used in route map)'). This adds meaning beyond the bare schema properties.

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

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

The description clearly states a specific action: 'Generate a Symbols.app DOMQL page' and elaborates with routing, helmet metadata, and fetch integration. This distinguishes it from sibling tools like generate_component, which target components.

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 the tool is for page generation but does not explicitly mention alternatives or exclusions. It provides clear context—'page' with routing, helmet, and fetch—but lacks an explicit 'when not to use' statement.

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 that it mirrors `smbls/CLI_FOR_MCP.md` and details the exact content areas, including error-handling contracts and anti-patterns. It does not explicitly state side-effect safety, but the read-only nature is strongly implied by 'Returns' and 'Mirrors'.

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 each listed item adds distinct value. It is front-loaded with the core purpose, but the single-sentence structure with a massive list could be clearer. It earns its length given the breadth of content.

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

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

With no parameters and no annotations, the description fully compensates by explaining the complete return content, including coverage areas and error contracts. The presence of an output schema reduces the need to detail return values, but the description goes beyond what is necessary.

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

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

There are zero parameters, so the baseline is 4. The description correctly focuses on what the tool returns rather than parameter details, as none exist.

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 complete `smbls` CLI reference, a specific resource. It also enumerates the covered topics, distinguishing it from sibling tools like get_sdk_reference (SDK vs CLI) and search_symbols_docs.

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

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

Usage is implied: if you need the CLI reference, this is the tool. However, there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or when-not 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 implies a read-only operation via 'Get' and 'inspect,' but it doesn't explicitly state that no modifications occur or disclose potential error behaviors or side effects. It does mention branch and auth parameters, adding some useful context, but not rich behavioral detail.

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

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

The description is compact and well-structured: a one-sentence purpose, a usage hint, then an Args block. It front-loads the key information and contains no filler. Every sentence adds value.

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

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

The output schema is present, so return-value details are not needed. The description covers the purpose, usage context, and all parameters, making it sufficient for an agent to select and invoke this tool correctly. It's a straightforward read tool, and the description is complete for that 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 has no parameter descriptions (0% coverage), but the description provides meaningful explanations for all four parameters: project key/ID, JWT token, API key, and branch with a default. This fully compensates for the schema gap and gives agents the necessary 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 'Get a Symbols project's current data (components, pages, designSystem, state),' which is a specific verb+resource statement that clearly differentiates this tool from siblings like get_project_rules or get_project_context. The additional note about inspecting before saving changes reinforces its distinct purpose.

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

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

It explicitly states when to use this tool: 'Use this to inspect what's already in a project before saving changes.' This gives a clear context, but it doesn't name alternatives or provide explicit when-not-to-use scenarios. Still, the context is strong enough to guide 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 provided, the description carries the full burden. It discloses that the tool walks up from cwd, parses symbols.json, classifies the environment from filesystem signals, and returns a payload. It also gives operational behavior like checking for token presence and instructing the agent to ask the user when next_step says so. However, it doesn't explicitly state whether the tool is read-only or has side effects, though 'Read' implies it.

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

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

The description is well-structured with a main sentence, a section explaining return values in bullet points, and usage guidance in bold. It is somewhat long but every section adds value. Minor redundancy exists ('START HERE' and 'ALWAYS call this first' repeat similar guidance), but overall it is efficiently organized.

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 and that an output schema exists, the description is complete. It enumerates all return fields with meanings, explains the environment classification, gives actionable next_step guidance, and covers authentication-related context. No important aspect of the tool's behavior is left undocumented.

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 provides only a 'cwd' property with a default and no description (0% coverage). The description fully compensates by explaining the meaning of cwd, its default behavior (MCP server's cwd), and when to pass an absolute path. This is exactly the kind of semantic enrichment needed.

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

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

The description clearly states the tool reads the current Symbols project context and is the starting point for any Symbols task. It names specific resources (symbols.json, filesystem signals) and explicitly distinguishes it from the sibling tool detect_environment, which it replaces.

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

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

The description provides explicit usage guidance: 'ALWAYS call this first' for any Symbols-project task, and instructs to use it before auth-required tools like save_to_project, publish, push, and get_project. It also names the alternative detect_environment and explains when to use this tool instead.

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

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

With no annotations, the description carries the full burden. It discloses the consequences of violations ('silent failures — black page, nothing renders...'), emphasizes the most-violated rule about reusing built-ins, and instructs the agent to read all sections. This goes well beyond a simple 'Returns rules' 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 long and uses a bulleted list to enumerate files, which is appropriate for the complexity of the returned rules. It is well-structured and front-loaded with the 'ALWAYS call this first' imperative. While lengthy, each entry serves a purpose and the content is not wasted, though a more compact summary could be added.

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 complex, returning a rich set of rule documents. The description thoroughly explains the content and purpose of each file, and provides clear, actionable guidance on how to use the returned information. An output schema exists, so return value details are not needed; the description is complete for the tool's context.

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

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

There are zero parameters, so the baseline is 4. The description adds no parameter-related meaning (none needed), and the schema is empty, so there is nothing to elaborate on. No deduction is warranted.

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 mandatory Symbols.app rules' and is explicitly positioned as the first call before any generate_* tool. It distinguishes itself from siblings by focusing on the authoritative rule set for code generation, not just general context or reference material.

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 gives explicit, actionable usage instructions: 'ALWAYS call this first before any generate_* tool' and lists specific tools ('generate_component, generate_page, convert_react, convert_html, or any code generation task'). It also explains the consequences of not using it, which is strong guidance.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Returns' and 'Mirrors sdk/SDK_FOR_MCP.md', implying a read-only operation, but does not explicitly confirm no side effects, authentication requirements, or caching behavior. The description focuses on content coverage rather than operational 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 long but well-structured, front-loading the primary purpose and then enumerating coverage areas in a clear list. Each service and section listed adds value for an agent deciding whether this reference contains the needed information, so the length is justified.

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

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

Given the tool has no parameters and an output schema exists, the description covers all necessary context: version, source file, and an exhaustive list of covered services and sections. It is complete for a reference retrieval tool, leaving no ambiguity about what the agent will get.

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

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

The tool has zero parameters, so the schema fully describes its interface. The description adds no parameter-specific information, which is acceptable given there are no parameters to describe. Per the rubric, 0 parameters sets a baseline of 4, and the description meets that baseline.

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

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

The description clearly states the tool 'Returns the complete @symbo.ls/sdk API reference (3.14.0).' This specifies the verb, resource, and version, distinguishing it from sibling tools like get_cli_reference. The detailed enumeration of services and sections further clarifies exactly what the agent will receive.

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 the tool is used to retrieve the SDK API reference but does not explicitly state when to use it versus alternatives like get_cli_reference or search_symbols_docs. It mentions that it mirrors a specific file, which gives some context, but lacks explicit when-not-to-use or alternative tool references.

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

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

No annotations are provided, so the description carries the burden. It discloses the authentication requirement and the output fields. However, it does not explicitly state that the operation is read-only, nor does it mention error behavior or rate limits. The word 'List' implies safety, but the description does not make it explicit.

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 short and well-structured: purpose, return info, authentication note, then argument details. Every sentence adds value with no redundancy or filler.

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

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

For a simple list operation with two parameters and an output schema, the description covers the essential purpose, usage context, authentication, and parameter semantics. It does not detail error handling, but that is reasonably left to runtime behavior. It is sufficient for an agent to use correctly.

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

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

The schema has no parameter descriptions (coverage 0%), but the description's Args section compensates by explaining token as 'JWT access token from login' and api_key as 'API key (sk_live_...) from project integration settings.' This adds meaningful format and source context, though it doesn't clarify whether both parameters are required or how they interact.

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 'List the user's Symbols projects', a clear verb and resource. It specifies the return values (project names, keys, IDs) and positions the tool as a prerequisite for choosing where to save/publish, distinguishing it from get_project or create_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?

It provides the intended use context: 'so the user can choose which project to save to or publish.' This clearly indicates when to call the tool. It does not explicitly name alternatives or exclusion criteria, but the use case is specific and actionable.

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

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

With no annotations, the description must carry transparency. It discloses the JWT token return and its applicability to all project tools, but omits details like token expiration, security implications, or credential handling. 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 three short paragraphs: purpose, usage, and Args. Every sentence is informative, no repetition or fluff. Front-loaded with the core purpose.

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

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

For a simple login tool with an output schema, the description covers the essential actions and expected return. It lacks details on failure modes or prerequisites, but overall it is complete enough for an agent to select and invoke the tool.

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

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

Schema description coverage is 0%, so the description compensates by explaining email and password as 'Symbols account email address' and 'Symbols account password.' This adds minimal value beyond the schema's parameter titles, but is sufficient for simple auth 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 'Log in to the Symbols platform and get an access token' with specific verb and resource. It uniquely identifies the authentication purpose, distinguishing it from all sibling tools which are project operations.

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

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

Explicitly states 'Use this when the user needs to authenticate before any project operation.' This provides clear when-to-use context, though it does not mention when-not-to-use or alternative authentication methods.

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 the tool generates prescriptions and that the agent must apply them via a separate tool, implying no mutation happens here. It also describes the return shape (JSON with schema version, opId, prescriptions). However, it does not explicitly state side effects, permissions, or error behavior of this specific tool, and spends significant space describing the sibling apply tool's behavior.

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

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

The description is front-loaded with purpose and uses clear headings/bullets, but it is fairly long. It includes a full list of op kinds and detailed behavior of the follow-up apply tool; these are useful in context but could be trimmed if those details live in sibling tool descriptions.

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 one parameter, an output schema, and a complex workflow, the description is highly self-contained. It explains what the prescription contains, how to handle findings with and without proposedOps, what the follow-up tool does, and when to stop—covering all the information an agent needs to invoke and use this tool correctly.

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

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

The input schema has one required string param with 0% schema description coverage. The description fully compensates by saying 'symbols_dir: Absolute path to the symbols/ directory', which gives the agent precise, actionable semantics beyond the bare 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 opens with a specific verb ('Generate') and a clear resource ('LLM-ready prescriptions for frank-audit findings that can't be auto-fixed'), immediately distinguishing this tool from adjacent siblings like apply_frankability_edit_ops. It also enumerates the prescription contents, which further clarifies the tool's role as a planning/proposal generator.

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 an explicit 4-step workflow: call this tool, inspect/modify proposedOps, call apply_frankability_edit_ops, and repeat. It clearly states the intended use case (findings that can't be auto-fixed) and gives specific instructions for the no-proposedOps case, including a list of valid op kinds.

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 that authentication is required (token or api_key) and that the action makes a version live, implying a state change. It does not mention reversibility or side effects on previous versions, but the core behavior is transparent enough for a publish operation.

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 and front-loaded with the main purpose. The opening sentence is immediately informative, followed by a short clarification, authentication note, and a cleanly formatted argument list. Every sentence contributes value, with no filler 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 tool with 5 parameters and no annotations, the description covers purpose, usage flow, authentication, and all parameter semantics. Since an output schema exists, the absence of return-value details is acceptable. The description is complete enough for an agent to invoke the tool correctly in the intended write-then-publish workflow.

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 includes an 'Args' section that explains every parameter: project (ID or key), token (JWT), api_key (sk_live_...), version (empty for latest), and branch (default main). This fully compensates for the schema's lack of descriptions and adds meaningful guidance beyond raw property names.

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 specific verb+resource: 'Publish a version of a Symbols project to the platform.' It further clarifies that this makes the specified version (or latest) the published/live version, which clearly distinguishes it from sibling tools like save_to_project (which saves changes) and push (which likely pushes code). The purpose is unambiguous.

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

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

The description explicitly instructs to 'Call save_to_project first to save your changes, then publish to make them live,' providing a clear workflow context. It also states authentication requirements, but it does not explicitly enumerate when not to use this tool or compare to all siblings. Still, the guidance is sufficient for an agent to select it for publishing after saving.

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 burden of behavioral disclosure. It reveals authentication needs, parameter dependencies (e.g., version required when mode is 'version'), and the publish-before-push ordering. However, it does not explicitly mention potential side effects like overwriting existing deployments or whether deploys are reversible. This is above average but not exhaustive.

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

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

The description is well-structured with a concise summary followed by a structured Args list. Every sentence adds value, and the format makes it easy for an agent to scan. It includes all necessary detail without unnecessary fluff, striking an ideal balance between completeness and brevity.

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

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

Given the 7-parameter complexity and zero schema descriptions, the description is thoroughly complete. It covers authentication, sequencing with publish, all parameter semantics, and environment targets. Since there is an output schema, not describing return values is appropriate. This description fully equips an agent to invoke the tool correctly.

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

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

The schema has 0% description coverage, so the description must fully compensate. It does so with a detailed Args section explaining every parameter: project, token, api_key, environment, mode, version, and branch. It also adds conditional logic (e.g., 'Required when mode is version') that goes beyond the schema, providing complete semantic clarity.

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

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

The description clearly states the tool's function: 'Push/deploy a Symbols project to a specific environment.' The verb is specific, the resource is identified, and the scope is defined with examples (production, staging, dev). It also distinguishes itself from the sibling `publish` tool by stating that publish sets the live version first, then push deploys it.

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

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

The description provides explicit usage guidance: 'Call publish first to set the live version, then push to deploy.' It also gives clear authentication requirements, stating 'provide either token or api_key.' This directly informs when and how to use the tool, and the sequencing with publish helps avoid 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 provided, the description carries the full burden and does well by explaining the snapshot mechanism and the return format. However, it does not explicitly warn about the destructive nature of the operation (e.g., overwriting current files) or mention error/failure cases. Still, it adds significant 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 efficiently structured: a clear purpose statement, a contextual explanation of snapshots, usage guidance, parameter definitions, and return format. Every sentence serves a purpose with no fluff, making it highly readable and scannable.

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 two parameters and an output schema (as signaled), the description covers the core functionality, parameters, return shape, and references a sibling for listing opIds. It lacks edge-case behavior (e.g., invalid op_id, rollback failure) but is generally complete for a well-understood operation. The presence of an output schema reduces the need to describe return details, but the description already includes them.

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

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

Schema coverage is 0% (no parameter descriptions in the schema), so the description must compensate. It does: 'symbols_dir: Absolute path to the symbols/ directory' and 'op_id: The opId to roll back to (from a prior apply-edits result).' This adds meaning beyond the bare titles 'Symbols Dir' and 'Op Id', earning a strong score, though it could include more detail about validation or format requirements.

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: 'Restore a Symbols project to its state before a specific op ran.' This uses a specific verb ('restore') and resource ('Symbols project'), and distinguishes it from siblings like apply_frankability_edit_ops and snapshots_frankability by focusing on undoing a previous operation.

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

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

Explicit guidance is provided: 'Use this to undo a specific op (or a chain by walking backwards through opIds listed by snapshots_frankability).' This clearly indicates when to use the tool and references a sibling for discovering opIds. The description also mentions the snapshot mechanism, giving context for how the undo works.

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 does well: it discloses side effects ('applies changes to the project and creates a new version'), merge behavior ('omitted sections are left unchanged'), and auth requirements via token/api_key parameters. This goes beyond minimal safety declarations to explain how the tool behaves.

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 due to the necessary JSON example, but every part serves a purpose: overview, usage, behavioral notes, parameter details, and example. It is well-front-loaded with the core purpose and not overly verbose, though the JSON block makes it less scannable.

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

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

Given 6 parameters, no annotations, and an output schema (which covers return values), the description is remarkably complete. It covers purpose, usage context, parameter semantics, merge behavior, and even versioning side effects. No major gaps are evident for an agent to invoke this correctly.

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

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

Schema description coverage is 0%, but the description compensates fully with an 'Args:' section explaining each of the 6 parameters. It also provides a detailed JSON example for the 'changes' parameter, clarifying its structure and optional sections, which is far more than a plain schema would offer.

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 'Save components, pages, or design system data to a Symbols project' with a specific verb and resource. It further distinguishes from siblings by noting 'Use after generate_component/generate_page to persist the output,' clarifying its role as a persistence step.

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

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

The description gives clear context: 'Use after generate_component/generate_page to persist the output.' It also explains merge semantics ('Only include the sections you want to update — omitted sections are left unchanged'), but does not provide explicit exclusions or alternatives beyond the generation 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?

No annotations are provided, so the description carries the burden. It is a search tool, implying read-only behavior, and mentions max_results limitation. However, it does not explicitly state that it does not modify anything or describe any request/response behavior, which is minimal but adequate for a straightforward search tool.

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

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

The description is extremely concise: a single opening sentence plus a compact Args list. Every sentence earns its place, with no redundant or filler content. It is front-loaded with the primary purpose.

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

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

For a simple search tool with only two parameters and an output schema, the description covers purpose and parameter semantics adequately. It does not need to explain return values because the output schema exists. It could mention broader scope (e.g., whether search is full-text or semantic), but the description is sufficient for a basic search 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 properties have no descriptions (0% coverage), but the description provides clear semantics for both parameters: query is described as 'Natural language search query about Symbols/DOMQL' and max_results is described with a range. This fully compensates for the schema gap.

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

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

The description clearly states the tool's function: 'Search the Symbols documentation knowledge base for relevant information.' It uses a specific verb (search) and a specific resource (Symbols documentation knowledge base), effectively distinguishing it from sibling tools like get_cli_reference or audit_component.

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

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

The phrase 'Search the Symbols documentation knowledge base for relevant information' and the query description 'about Symbols/DOMQL' imply the tool is for looking up documentation. It provides clear context for when to use it, but it does not explicitly mention alternatives or exclusion criteria.

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

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

With no annotations, the description carries the full burden. It discloses the return format (JSON with ok and opIds array including opId, timestamp, files), clarifies that entries correspond to frank-audit ops that wrote files, and explains their role in rollback. It doesn't mention ordering or time window, but for a simple list tool, this is reasonably transparent.

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 efficient: three sentences plus a return format line. The purpose is front-loaded, and every sentence adds value without unnecessary fluff.

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

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

For a simple one-parameter list tool, the description is complete: it explains what the tool does, what each entry contains, how the result is used with rollback, and provides the return structure. No critical information is missing.

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

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

The schema has zero description coverage, and the only parameter, symbols_dir, is not explicitly described. The description indirectly refers to it by saying 'for a Symbols project,' which hints at the parameter's purpose, but it doesn't state the parameter name or format directly. Minimal compensation is provided.

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

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

The description clearly states the tool's action: 'List recent snapshotted opIds for a Symbols project.' It specifies the resource (snapshotted opIds) and scope (Symbols project), and differentiates from the sibling tool rollback_frankability by explaining that the opIds can be passed to rollback to restore pre-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 provides clear context: it lists snapshotted opIds from audit ops that wrote files, and explicitly mentions the next step of passing an opId to rollback_frankability. It doesn't state exclusions or when not to use, but the usage scenario is apparent.

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 does well: it discloses that the tool runs the same round-trip as apply-edits, that it is a standalone check, and that it returns JSON with 'ok, bundleable, scanIssues.' This implies a non-mutating verification operation. It doesn't explicitly state it is read-only, but the context strongly suggests it. Minor gaps like error behavior are not covered, but overall the behavior is transparent.

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 (four sentences) and well-structured: it opens with the core purpose, then explains independence and usage context, and ends with the return value. Every sentence adds value, and key information is front-loaded. No wasted words.

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

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

For a tool with a single parameter and an output schema, the description is fairly complete. It explains why the tool exists, when to use it, and what it returns. The output schema exists, so the explicit return listing is a bonus. Missing elements like prerequisites (e.g., does symbols_dir need to be absolute?) or potential error conditions, but these are not critical given the simplicity.

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

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

The input schema has only one parameter, symbols_dir, but with no description (0% coverage). The description does not explicitly explain the parameter; it only implies that the tool operates on a Symbols project. Since schema coverage is low, the description should compensate, but it fails to elaborate on what symbols_dir should contain (e.g., a path to the project root, expected format). The parameter is somewhat inferable from the tool name and purpose, but not explicitly described.

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

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

The description clearly states the tool's specific purpose: 'Verify a Symbols project bundles cleanly via frank.toJSON.' It uses a specific verb (Verify) and resource (Symbols project), and further distinguishes itself from audit/fix by noting it is an independent standalone check. This sufficiently separates it from sibling tools like audit_component or apply_frankability_edit_ops.

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

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

The description provides explicit usage context: 'Useful for the agent to confirm a project is in a known-good state before starting a fix loop, or after a series of manual edits.' It also states it is 'independent of audit/fix,' implying that for actual auditing or fixing, other tools should be used. It does not explicitly name alternative tools, but the guidance is clear and practical.

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