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

With no annotations provided, the description carries the burden of disclosing behavior. It clearly states the operation is static analysis (non-executing) and requires specific authentication. It does not explicitly state that no files are modified, but 'statically analyze' strongly implies a read-only operation, and the auth requirement is a key behavioral constraint.

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

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

Two concise sentences, front-loaded with the main purpose and immediately followed by the auth prerequisite. Every word earns its place; 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?

The tool is simple with only 3 parameters, and the description covers the core purpose and auth context. The absence of an output schema means a note about return format would be useful, but the phrase 'for performance anti-patterns' implies the output is a list of findings, 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?

All three parameters have descriptions in the schema (100% coverage), so the baseline is 3. The tool description does not add extra semantics about parameter formatting or relationships beyond calling out 'specific file', which aligns with the fileName parameter.

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

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

The description uses a specific verb 'statically analyze' with a precise resource 'specific Liquid file' and a clear objective 'for performance anti-patterns'. This distinguishes it from broader sibling tools like find_slow_templates or get_bottlenecks, which likely operate at the theme or page level.

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 (analyzing a specific file) and adds a critical prerequisite (legacy cookie authentication via login_legacy). It does not explicitly state when not to use it or name alternatives, but the prerequisites and single-file scope give solid 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. It discloses the output behavior ('Returns a summary comparison... sorted by render time'), a hard limit ('Maximum 10 pages per call'), and the scope constraint ('same store'). It does not explicitly state the operation is read-only, but the profiling context 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 two sentences with no wasted words. It front-loads the primary action, then provides the output, a use case, and a constraint—all in order of relevance.

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 2-parameter tool with no output schema, the description covers the essential aspects: what it does, what it returns, a use case, and a key limit. It lacks explicit return structure details, but the summary comparison is adequately described for agent invocation.

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

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

The schema already documents both parameters with descriptions, including an example for pagePaths. The description's 'Maximum 10 pages per call' merely reiterates the schema's maxItems constraint, adding little semantic value beyond what the schema provides. Baseline 3 applies.

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

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

The description clearly states the action ('Profile multiple pages on the same store') and identifies the resource ('multiple pages') and output ('summary comparison of all pages sorted by render time'). It distinguishes itself from siblings like profile_page by focusing on the batch/summary aspect, and the use case is explicit.

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

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

The description explicitly notes the tool is 'Useful for finding the slowest pages on a site,' which provides a clear use case. However, it does not directly mention when not to use it or name alternatives, though the batch context implicitly contrasts with single-page profiling.

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 tells the user what the tool outputs (differences in render time, template breakdown, recommendations) which is useful behavioral context. However, it does not mention side effects, authentication requirements, or failure modes, leaving some ambiguity about the operation's safety and prerequisites.

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 followed by practical use cases. Every word earns its place, with no redundant or vague content. This is an example of concise, effective tool documentation.

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?

Since there is no output schema, the description appropriately summarizes the return values (differences in render time, template breakdown, recommendations). For a comparatively simple 3-parameter tool, this covers the essential output aspects. Minor gaps include lack of detail on output format or error conditions, but the description is adequate for typical use.

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

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

The input schema provides full descriptions for all three parameters with 100% coverage, so the schema does the heavy lifting. The tool description adds minimal parameter-level semantics beyond reiterating that pagePathA and pagePathB are the two pages to compare. This meets the baseline for schema-heavy descriptions.

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

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

The description clearly states the tool's function: 'Profile two pages on the same store and compare their performance side-by-side.' This is a specific verb+resource combination that distinguishes it from single-page profilers like profile_page. The mention of 'render time, template breakdown, and recommendations' adds clarity about what the comparison includes.

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: 'Great for A/B testing template changes or comparing product vs collection page performance.' This implies the tool is for comparative analysis rather than single-page profiling. However, it does not explicitly name alternatives (e.g., 'use profile_page for single pages') or state when not to use it.

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

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

No annotations are provided, so the description must disclose behavior itself. It states the required input format and implies the action completes login, but it does not discuss session/auth side effects, idempotency, or the single-use nature of the callback.

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

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

One concise sentence conveys the entire purpose and the critical input requirement, with no padding or wasted words.

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

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

The tool has a clear two-parameter contract and uses existing login context, so the description is adequately complete for selecting and invoking it. Some behavioral details (e.g., what a successful completion returns or whether it invalidates a previous session) are absent, but they are not essential for basic usage.

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

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

Schema already covers both parameters with meaningful descriptions (storeUrl same as login_in_chrome; callbackUrl includes code and state). The description adds no parameter details beyond that, so the baseline 3 applies.

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

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

The description uses a specific verb ('Complete') and identifies the resource ('login_in_chrome flow') and key input ('callback URL'), making its purpose clear and distinguishing it from the sibling login_in_chrome, which starts the flow.

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: this is for completing the flow with the full callback URL copied from Chrome's address bar. It does not explicitly name alternatives or when-not-to-use, but the sibling set makes the role 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 full responsibility. It discloses output behavior (save to file or return inline) and provides format details, but does not mention auth requirements, side effects, or whether it's a read-only operation. The format descriptions add some context, but the side-effect profile remains 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 two sentences, highly concise, and front-loaded with the main purpose. Every phrase adds useful information: the command, the formats, and output options. No wasted words.

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

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

The description covers the formats and output options, and the schema documents all parameters. However, it lacks guidance on when to use this versus sibling profiling tools and does not address behavioral aspects like authentication or side effects. Given there is no output schema, the return structure for inline content is also not detailed. Overall it is adequate for a simple export tool but leaves some gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining what each format means (speedscope JSON, csv spreadsheet-friendly, markdown report with tables and severity badges) and by clarifying outputPath behavior via 'Can save to a file or return inline.' This enriches the parameter understanding.

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

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

The description clearly states the tool profiles a page and exports results in a specified format, with a specific verb and resource. It lists supported formats, which helps understanding, but does not explicitly distinguish it from siblings like profile_page, so it stops short of a 5.

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

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

Usage is implied: if you need to export profiling data in a particular format, this is the tool. However, there is no explicit guidance on when to use this versus profile_page or other sibling tools, nor any exclusions or prerequisites mentioned.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It mentions OAuth2 authentication, which is a useful context, but it omits what the tool returns, whether it is read-only, how pagination or filtering works, or any side effects. The description is too sparse for an analysis tool with no output 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 single sentence that efficiently conveys the core purpose and the authentication requirement. Every word earns its place, with no fluff or repetition. Front-loaded with the main action, it is a model of conciseness.

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

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

Despite the tool having no output schema, the description does not explain what the tool returns (e.g., a list of templates with render times). It also ignores the optional pagePath parameter and how it interacts with the threshold. Given the presence of related sibling tools, this description lacks sufficient context for an agent to fully understand the tool's scope and output.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal semantic value by mentioning the threshold concept, but it does not elaborate on pagePath or thresholdMs beyond what the schema already states. The schema itself documents all parameters adequately, so no extra compensation is required.

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 identifies Liquid templates and sections exceeding a render threshold. The verb 'Identify' is specific and the resource is well-defined. However, it does not explicitly differentiate the tool from sibling profiling tools like get_bottlenecks or analyze_liquid_file, so it misses the highest distinction mark.

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

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

The description provides no guidance on when to use this tool versus alternatives. It only mentions OAuth2 authentication, which is a prerequisite, not a usage condition. There are no exclusions or hints about when to prefer this over get_bottlenecks or profile_page. This leaves the agent without direction for tool 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 provided, the description carries the full burden. It adds useful context by specifying the two authentication types (OAuth2 and legacy), but it does not disclose potential side effects, return format, or prerequisites. The behavior is minimally transparent but lacks depth.

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

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

The description is two concise sentences that immediately convey the tool's purpose and scope. Every word adds value, with no filler or redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description is fairly complete. It explains what the tool does and distinguishes between two authentication types, though it could be more explicit about the form of the returned status 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 description coverage is 100% for the single optional parameter 'storeUrl'. The description does not add meaningful semantics beyond what the schema already states, so it remains at the baseline score of 3.

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

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

The description clearly states the tool checks authentication status, with a specific verb ('check') and resource ('authentication status'). It also distinguishes between OAuth2 and legacy authentication, setting it apart from sibling tools like login/logout.

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 (to check authentication status) and distinguishes it from login/logout siblings, but it does not explicitly state alternatives or when-not-to-use scenarios. However, the context is clear enough for an agent to select it appropriately.

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. It discloses the core behavior (profiling and detecting anti-patterns) and the output format (recommendations, severity, locations, impact, fixes). However, it doesn't mention any side effects, prerequisites like login, or whether it's read-only. The absence of such disclosure is a gap, but the description is not misleading.

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 that are front-loaded with the main action, followed by output details and a usage claim. Every sentence contributes value and there is no unnecessary 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 of this complexity, the description covers the primary behavior and the full output format, which is substantial. It doesn't mention preconditions (e.g., requires authentication) or limitations, but the core functionality is well-explained. Given no output schema and moderate complexity, this is fairly complete.

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

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

Schema coverage is 100%, so the schema documents both parameters (storeUrl and pagePath) with descriptions. The description adds no parameter-level information, so it doesn't go beyond the baseline 3 for high schema coverage.

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

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

The description uses a specific verb ('Profile a page') and clearly states the purpose: automatically detect performance anti-patterns. It also distinguishes itself from siblings by claiming to be the BEST tool for identifying what to optimize, giving it a unique role among profiling tools.

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

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

The description explicitly tells the agent when to use this tool: 'This is the BEST tool for identifying what to optimize.' However, it does not mention any exclusions or alternatives, and it doesn't explain when not to use it, but the strong usage recommendation elevates it above an implied guideline.

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 for behavioral disclosure. It reveals that profiling calls are auto-saved and that trends are shown, but it omits the destructive `clearHistory` capability, painting the tool as purely view-only when it can delete history. This is a significant under-disclosure for a tool with a mutation side effect.

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

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

Three sentences, each earning its place: purpose, detail, and usage guidance. No fluff or repetition. Front-loaded with the core 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?

For a 4-parameter tool with no output schema and no annotations, the description covers the primary functionality and use case, but lacks disclosure of the clearHistory side effect and does not describe what the returned history data looks like. These gaps prevent it from being fully complete, though the core viewing purpose is well covered.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some conceptual context (history auto-save, trend tracking) but does not enrich any specific parameter semantics beyond what the schema already states. The `clearHistory` parameter's destructive nature is not reinforced in the description.

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

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

The description opens with 'View profiling history and performance trends for a store' – a specific verb and resource. It clearly distinguishes from sibling tools by focusing on historical trends over time, and adds context with 'Shows how render times have changed over time.'

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 'Use this to track the impact of optimizations,' giving a concrete when-to-use scenario. It does not explicitly name alternatives or exclusions, but the use case is clear enough to differentiate from siblings like get_profile_summary or find_slow_templates.

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 states the output structure and authentication requirement, which adds useful context. However, it does not disclose whether the operation is strictly read-only, potential side effects, rate limits, or what 'top slow nodes' entails in detail. These are reasonable expectations for a profiling 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?

Two clear, front-loaded sentences. The first provides the purpose and output, the second adds a comparative advantage and prerequisite. No wasted words or repetition of schema info.

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

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

With no output schema, the description compensates by naming the key return components (top slow nodes, template breakdown) and the readability benefit. It misses a more detailed comparison with related siblings, but for a two-parameter, likely read-only tool, this is sufficient.

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

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

Schema description coverage is 100%, and both parameters (storeUrl, pagePath) have meaningful descriptions in the schema. The tool description itself does not add extra parameter-level semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Profile' and identifies the resource 'Shopify store page' with a clear outcome: structured performance summary with slow nodes and template breakdown. It also distinguishes itself from profile_page by noting it is 'more readable than raw profile_page data', separating 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?

Provides explicit context: use for a readable summary over raw profile_page data, and requires OAuth2 authentication first. It does not explicitly exclude other likely alternatives like find_slow_templates or get_bottlenecks, but the purpose and contrast are clear enough.

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

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

No annotations are provided, so the description carries full burden. It states the check behavior but adds no details about side effects (likely none), return format, or potential failure modes. It is minimally sufficient but not revealing.

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

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

A single, front-loaded sentence that wastes no words. It directly states the tool's function without filler, appropriate for this simple 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 zero-parameter health check with no output schema, the description adequately conveys the tool's purpose. It could have specified the return format, but the essence is clear enough for basic 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 tool has zero parameters, and the schema is empty (100% coverage). Per guidelines, a 0-parameter tool receives a baseline of 4. The description correctly omits parameter information since 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 explicitly states the tool's purpose: checking server health. It uses a specific verb ('check') and resource ('Shopify Theme Inspector MCP server'), and is clearly distinct from sibling tools like login or profile queries.

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

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

The description implies a clear use case: verifying the server is operational before relying on other tools. It does not explicitly mention alternatives, but the context is unambiguous and no exclusions are needed.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It discloses the OAuth2 method, the browser interaction, and the resulting profiling capability. However, it does not explicitly state that the process requires a human to complete login, that it may block while waiting, or what happens to existing authentication state.

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 clear, front-loaded sentences with no filler. Each sentence adds essential information: the authentication method, the browser side effect, and the resulting benefit.

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 one parameter and no output schema, the description covers the key aspects: purpose, authentication mechanism, browser interaction, and what the authentication enables. It could be more explicit about the interactive nature and post-login behavior, but it is largely complete.

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

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

The schema provides 100% coverage of the single parameter, storeUrl, including a description and example. The tool description does not add extra semantic detail about the parameter, which is acceptable given full schema coverage, so the baseline score of 3 applies.

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

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

The description clearly states the specific action ('Authenticate with Shopify via OAuth2'), the resource (Shopify), and the method (browser-based OAuth2, same as Chrome Theme Inspector). It also distinguishes itself from sibling tools by mentioning the browser flow and the full flame graph profiling data it enables.

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: use this tool to authenticate via OAuth2 in a browser and to get access to flame graph profiling data. It doesn't explicitly mention when to avoid this tool or list alternatives, but the browser-based OAuth2 method and the purpose are enough to guide typical usage.

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

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

With no annotations, the description must carry the transparency burden. It discloses that the tool does not close Chrome and that user authorization is required, but it omits other behavioral traits such as whether a new tab is opened, whether the tool blocks while awaiting authorization, or how the callback URL is exposed to 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 two short sentences with no filler. It front-loads the primary action and then gives a concrete follow-up instruction, making every word earn its place.

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

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

For a one-parameter tool with no output schema, the description covers the basic flow but leaves the practical outcome under-specified. It does not indicate what the tool returns or how the callback URL is obtained after authorization, which is a noticeable gap for an interactive OAuth flow.

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

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

Schema coverage is 100% with a single parameter 'storeUrl' described as 'The Shopify store URL'. The description does not add any additional meaning, but the schema already fully documents the parameter, 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 uses a specific verb 'Start Shopify OAuth' and identifies the resource 'user's existing Chrome profile' plus a key constraint 'without closing Chrome'. It clearly distinguishes itself from the sibling 'complete_login_in_chrome' by positioning this as the initial step of a two-step flow.

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

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

The description provides a clear workflow: start OAuth, then copy the final callback URL and pass it to complete_login_in_chrome. It implies this is for reusing an existing Chrome profile, but it does not explicitly state when to prefer this over sibling login tools 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 burden of behavioral disclosure. It does mention that the tool is cookie-based and opens a browser for manual login, which informs the agent about the interactive nature. However, it lacks details on what happens after login, whether it revokes existing sessions, or how authentication state is managed, leaving room for 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 compact, consisting of three focused sentences. It front-loads the core purpose, provides necessary usage context, and does not waste words, making it highly 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?

Given the tool's simplicity (one parameter, no output schema) and the presence of sibling tools, the description adequately covers the core purpose, usage, and alternative. It also explains the dependency on analyze_liquid_file. However, it does not mention what the tool returns or how success is indicated, which could be a minor gap for an agent expecting a completion signal.

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% for the single parameter storeUrl, with the schema providing the format example. The description does not add any extra detail about the parameter itself, so it adds no value beyond the schema, resulting in a baseline score of 3.

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

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

The description clearly states it is a 'Legacy cookie-based Shopify login' that opens a browser for manual login. It distinguishes itself from the 'login' (OAuth2) tool by mentioning the legacy nature and cookie-based approach, making the purpose specific and well-differentiated among sibling tools.

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

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

The description explicitly states when to use this tool: 'Required for analyze_liquid_file tool which needs Admin API access.' It also provides an alternative: 'Use login (OAuth2) for profiling tools.' This gives clear guidance on context and exclusion, adhering to the best standard.

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 indicates a destructive action ('Remove saved authentication'), which is helpful, but it does not mention any prerequisites, side effects (e.g., needing to re-authenticate), or whether the operation is irreversible.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately states the action and scope, making it highly efficient 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 simplicity (one required parameter, no output schema), the description adequately covers the core functionality. However, it could be more complete by mentioning expected outcomes (e.g., success/failure response) or preconditions, but those are not critical given the clear purpose.

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 fully documents the storeUrl parameter (100% coverage), so the description's mention of 'a Shopify store' adds only minimal confirmation of the parameter's purpose without providing extra format, constraints, or usage details.

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 'Remove' and clearly identifies the resource: 'saved authentication' for a Shopify store. It also distinguishes from sibling login tools by explicitly mentioning both OAuth2 and legacy sessions, making the tool's unique purpose obvious.

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

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

The context implies this tool is for logging out or clearing saved credentials, but it does not explicitly state when to use it versus alternatives. No alternatives are named, and there is no when-to-use or when-not-to-use guidance beyond the basic action.

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. It discloses the authentication requirement and the output type (full flame graph). However, it does not explicitly state whether the operation is read-only, any potential performance impact on the store, or the format of the flame graph data. The reference to the Chrome extension provides some context but leaves room for more 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?

Two sentences, front-loaded with the action and purpose. The first sentence immediately states what the tool does; the second provides output type and auth requirement. Every clause earns its place 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?

Given no output schema, the description adequately conveys the return type ('FULL flame graph profiling data') and references the Chrome extension for familiarity. It covers the key context: purpose, prerequisites, and output. It does not detail edge cases or error handling, but for a straightforward profiling tool with two simple parameters, this is reasonably complete.

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

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

The input schema already covers 100% of parameter descriptions (storeUrl and pagePath), so the baseline is 3. The tool description adds little beyond the schema, only implying the target is a store page. No extra semantic nuance is added, but the schema is sufficiently clear on its own.

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: 'Profile a Shopify store page to analyze Liquid template rendering performance.' It uses a specific verb ('Profile') and resource ('Shopify store page'), and distinguishes from siblings like get_profile_summary (which likely provides a summary) and find_slow_templates (which targets slow templates).

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 the prerequisite: 'Requires OAuth2 authentication first (use the 'login' tool).' This tells the agent when to use this tool (after login) and provides an alternative for the auth step. It also hints at when to use this over summary tools by saying it returns 'FULL flame graph profiling data,' implying it's for detailed analysis rather than high-level summaries.

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