Server Quality Checklist

Tool Scores

• get_preview_urlA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the bar is lower. The description adds behavioral details: links are valid for 1 hour, and both storefront and local development URLs are provided. It also clarifies that publishing is separate, which adds context beyond annotations.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the core purpose and key constraints (1-hour validity, draft state, two URL types). No wasted words.

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

  Completeness4/5

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

  With no output schema, the description explains that preview links are returned for two environments)Skip but doesn't detail the response structure. It also mentions the 1-hour expiry and that publishing is done from the panel, which helps context. Missing pagination or error behavior is acceptable given annotations and simplicity.

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

  Parameters3/5

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

  Schema coverage is 100% with clear descriptions for page and locale params. The tool description does not add significant param-level detail beyond what's in the schema, so baseline 3 is appropriate. It does add the draft context, but that's not param-specific.

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

  Purpose5/5

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

  The description clearly states the tool generates preview URLs for draft pages, specifying the 1-hour validity and the two environments (storefront and local development). This distinguishes it from sibling tools like get_page which retrieves page data, and the scope (drafts only) is explicit.

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

  Usage Guidelines4/5

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

  The description implies when to use this tool (for drafts before publishing) and notes that publishing is done from the panel. While it doesn't explicitly name alternative tools, the context is clear enough. However, it lacks explicit exclusions or comparisons to siblings.

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

• list_componentsA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it reads from disk (implying file system access), and explains the difference between summary and full detail levels, which is beyond what annotations provide.

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

  Conciseness5/5

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

  The description is concise and front-loaded with the core purpose. It uses two sentences to convey the main function and the key usage tip, with no wasted words.

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

  Completeness4/5

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

  Given the tool's moderate complexity (3 optional params, no output schema), the description is complete enough. It explains the two detail levels and the validation use case. The lack of output schema means the description doesn't need to explain return values, and the annotations cover safety. A small gap is not mentioning pagination or performance, but that's not critical for a listing tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the default behavior (summary, or full if component is given) and the purpose of the full detail (field names, defaultProps, variants), which adds some value beyond the schema but doesn't significantly expand parameter semantics.

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

  Purpose5/5

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

  The description clearly states the tool reads section and element components from the theme repository, with a specific verb ('reads from disk') and resource ('theme repo components'). It distinguishes from siblings by focusing on component listing rather than pages or site context.

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

  Usage Guidelines4/5

  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, especially the instruction to validate field names with full detail before writing sections. It doesn't explicitly mention alternatives, but the sibling tools are distinct enough that this is not a major gap.

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

• list_pagesA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which fully describe the safety profile. The description adds that it lists pages in the 'active theme', which is a useful context about scope. It doesn't detail behavior like pagination or sorting, but with annotations covering the read-only and non-destructive nature, this is sufficient.

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

  Conciseness5/5

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

  The description is a single, concise sentence that packs all essential information: what it does, the scope (active theme), and what fields are returned. No fluff, no redundancy. It is front-loaded with the verb 'listes' and the resource 'pages'.

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

  Completeness4/5

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

  Given that this is a simple list operation with only one optional parameter and no output schema, the description is fairly complete. It covers the purpose, the scope, and the return fields (id, slug, title, status, dates). The lack of explicit return format (array vs. object) is a minor gap, but for a list tool without a complex output schema, this is acceptable. It doesn't mention filtering by status, but that's a feature not promised.

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

  Parameters3/5

  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 (includeTemplates). The description does not add any additional meaning about the parameter beyond what the schema says ('include template pages (read-only)'). Since the schema fully documents the parameter, the baseline of 3 is appropriate; the description adds no extra value here.

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

  Purpose5/5

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

  The description explicitly states the tool's purpose: 'list pages in the active theme' with specific fields (id, slug, title, status: draft/published/changed, dates). The verb 'listes' (Turkish for 'list') clearly indicates a read-only operation, distinguishing it from siblings like 'create_page', 'update_page', 'delete_page', and 'get_page'.

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

  Usage Guidelines4/5

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

  The description makes clear the context: it lists pages in the active theme, which is a distinct context from 'get_site_context' or 'list_components'. It doesn't explicitly state when not to use it or alternative tools, but the context of listing all pages vs. getting a specific page is implied. A slight gap is the lack of mention that this tool is the right choice for overview tasks vs. 'get_page' for details.

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

• update_pageA
  4.2/5.0
  Behavior4/5

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

  The description explicitly mentions the `dryRun:true` test mode and the restriction that Header/Footer children cannot be modified. It also notes that operations require IDs from get_page and that insert without anchor places new section before Footer. These are non-obvious behaviors that add value beyond any annotations.

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

  Conciseness3/5

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

  The description is a single dense paragraph with many clauses separated by semicolons and em dashes. While it contains high-value info, the run-on structure makes it hard to parse quickly. Breaking it into a few bullet points or sentences would improve scannability.

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

  Completeness4/5

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

  The description covers the three update paths (operations, document, meta), key constraints, and the dryRun flag. It does not mention error handling or return values, but given that the tool is an update operation, the absence of output description is acceptable. The description is largely complete for the tool's complexity.

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

  Parameters4/5

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

  The schema already describes the operations array structure and prop formats in detail cliffhanger. The description adds semantic value by explaining the meaning of each operation type (append, insert, replace, remove, move_section, set_props, etc.) and the rule about Footer placement for insert_section. It also clarifies the meta vs operations vs document distinction.

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

  Purpose5/5

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

  The description clearly states the tool updates a page draftlying, then specifies the three modes: operations, document, or meta. It uses specific verbs (append, insert, replace, remove, move_section) and names the resource (page), making the purpose unambiguous.

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

  Usage Guidelines4/5

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

  Provides explicit guidance on when to use operations vs document vs meta, and explains how to obtain IDs (from get_page outline) and where new sections are placed (before Footer). This goes beyond basic context, though it doesn't compare to sibling tools like `create_page` or `publish_page`.

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

• get_site_contextA
  4.3/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which already convey safety. The description adds behavioral context by listing what data is returned (languages, theme, API key scope/expiry, page count), which is not fully captured by annotations. It doesn't mention any side effects, but given the read-only hints, the bar is lower. The description adds value by detailing the content of the context.

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

  Conciseness5/5

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

  The description is a single, compact sentence in Turkish, listing exactly the key information: what is retrieved (store, theme, API key scope, page count) and the usage guidance. Every word earns its place; no fluff. Front-loaded with the core content and ends with the directive.

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

  Completeness4/5

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

  The tool has no parameters, no output schema, but annotations are comprehensive (read-only, idempotent, non-destructive). The description explains what data is returned and when to call it. Given the simplicity of a zero-parameter tool, the description is complete enough. It doesn't describe return format, but without an output schema, that's acceptable for such a simple tool. The 'call before others' guidance is the key contextual information.

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

  Parameters4/5

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

  The tool has 0 parameters, so no parameter documentation is needed. The schema is empty and coverage is 100%, which is trivially satisfied. The description adds value by explaining what the tool retrieves, which isn't parameter-related but still useful for understanding the output. Baseline for 0 params is 4, and the description does not detract.

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

  Purpose4/5

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

  The description clearly states the tool retrieves site context: store languages, active theme data (themeId/merchantThemeId/domain), API key scope/expiry, and page count. It distinguishes from siblings by explicitly covering site-level context, whereas siblings focus on specific components/pages. However, the title is in Turkish (Site bağlamını getir) while description is in Turkish as well, which is coherent but not in English.

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

  Usage Guidelines5/5

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

  Explicitly instructs 'Diğer araçlardan önce çağırın' (Call before other tools), providing clear when-to-use guidance. This is a strong usage directive, distinguishing it as a prerequisite step. No alternatives are named, but the instruction is unambiguous.

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

• create_pageA
  4.4/5.0
  Behavior4/5

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

  Discloses that header/footer are auto-copied from layoutFrom and that this creates a draft. The dryRun tip reveals how the tool behaves during validation. Annotations already signal write and non-destructive, so the description adds context without contradicting them.

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

  Conciseness5/5

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

  Three sentences, front-loaded with the core action, then critical constraints and prerequisites. Every sentence earns its place; no fluff.

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

  Completeness4/5

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

  Given the tool's complexity (nested sections, 6 params, no output schema), the description covers essential behaviors: draft creation, auto-copy, field validation, and dryRun workflow. It omits return format for non-dry-run saves, but that is a minor gap for a create operation.

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

  Parameters4/5

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

  Schema covers 83% of parameters, and the description adds key semantic meaning: do not include layout-sourced header/footer in sections, and use dryRun to avoid saving. It also reinforces the layoutFrom default. This enriches the schema without redundant restating.

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

  Purpose5/5

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

  The description opens with a specific verb-object pair: 'yeni bir TASLAK sayfa oluşturur' (creates a new DRAFT page), clearly distinguishing it from update_page and delete_page. The 'TASLAK' qualifier adds precise scope.

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

  Usage Guidelines4/5

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

  Provides explicit guidance: validate fields with list_components first, use dryRun:true to test without saving, and warns against including header/footer in sections. It does not explicitly state when to use update_page for existing pages, but the context is clear enough.

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

• get_pageA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral detail about what each mode returns (outline summary with IDs/types/slots vs full draftData JSON), which is useful beyond the annotations.

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

  Conciseness5/5

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

  Two sentences with clear structure. The description front-loads the purpose and immediately explains modes, including a practical hint for update_page. No fluff.

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

  Completeness5/5

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

  Without an output schema, the description clearly explains what each mode returns (outline with IDs and short text; full with complete JSON). It also notes the default mode and the use case for update_page, making the behavior fully transparent despite the absence of an output schema.

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

  Parameters4/5

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

  Schema describes 'page' with format (hex or slug), and description explains the 'mode' parameter including its default and meaning of both values. Since schema coverage is 50% (only 'page' described), the description effectively compensates and adds semantic value.

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

  Purpose5/5

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

  Description clearly states it returns a page draft, distinguishes two modes (outline vs full) and explicitly connects to update_page for ID retrieval. This goes beyond the tool name and clarifies the exact resource and behavior.

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

  Usage Guidelines4/5

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

  It explains when to use mode=outline (to get IDs for update_page) and mode=full for complete JSONapis. While it doesn't explicitly say when not to use this tool vs siblings, the context is clear from the mode explanations and the sibling list (update_page, delete_page, etc.).

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

• delete_pageA
  4.7/5.0
  Behavior4/5

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

  Annotations indicate destructiveHint:true, and the description adds that it's a soft delete, reversible from the panel. This adds value beyond annotations by explaining the reversibility, which is critical for an AI agent to avoid unnecessary caution. However, it doesn't detail other behaviors like idempotency effects, but that's not required.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the primary action and critical caveats. No fluff; every sentence adds essential context. Highly concise and well-structured.

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

  Completeness5/5

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

  Given the tool's complexity (soft delete, confirmation requirement, template restriction) and the absence of an output schema, the description covers all necessary operational details. It is complete for safe, correct use.

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

  Parameters4/5

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

  Schema covers both parameters fully (page with format examples, confirm with const true). The description adds the meaning of confirm as explicit approval, which is important context beyond the schema. It doesn't repeat schema details, so credit for supplementary clarification.

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

  Purpose5/5

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

  The description clearly states the tool deletes a page ('Sayfayı siler') and immediately clarifies it is a soft delete that can be undone from the panel. This distinguishes it from a hard delete and aligns with the sibling tools like create_page and update_page.

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

  Usage Guidelines5/5

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

  Explicitly instructs not to call without user consent, defines the 'confirm:true' parameter as representing explicit user approval, and mentions restriction on template pages. This provides strong guidance on when to invoke and when not to.

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

• validate_documentA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnly and idempotent annotations, the description details behavior that is not visible in the schema: errors include a path and explanation, and an `ok=true` result indicates a saveable normalizedDocument. This adds genuinely useful behavioral context.

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

  Conciseness5/5

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

  Two short, front-loaded sentences deliver all necessary information: non-saving behavior, input alternatives, and output semantics. No redundant filler; every phrase adds value.

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

  Completeness5/5

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

  For a validation tool with nested inputs and no output schema, the description covers the input contract, the non-destructive nature, the error shape, and the conditions for a saveable result. It is sufficient for an agent to invoke it correctly.

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

  Parameters4/5

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

  The description directly supplements the schema by explaining that the caller must provide either `sections` in authorship format or a full `document` with `{root, content, zones}`. It also highlights relevant inner fields like type/props/variant/slots, compensating for the top-level schema coverage gap.

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

  Purpose5/5

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

  The description clearly identifies a specific action: validate a document without saving it. It defines the two accepted input forms (`sections` and `document`) and distinguishes the tool from page-management siblings by emphasizing it does not persist.

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

  Usage Guidelines4/5

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

  The phrase 'without saving' and the kirjeld of the two accepted input formats provide clear context that validation is meant to be a pre-save check. Explicit alternative tools are not named, but the functional boundary is clear enough for an agent to select it.

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