Server Quality Checklist

Tool Scores

• optiqra_ai_testA
  3.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description must fully disclose behavior. It only states the verification intent but omits any side effects, whether the operation is read-only, the meaning of 'working', or the response format. For a tool that likely performs network calls, this leaves important behavioral traits undisclosed.

  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, front-loaded sentence that immediately states the action and context. It contains zero filler or redundancy, making it highly efficient.

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

  Completeness3/5

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

  For a relatively simple verification tool, the description is adequate but incomplete. It lacks any mention of success/failure outcomes, whether the call is destructive, or how the result is returned. Given no output schema and no annotations, more detail would be valuable for the agent to set expectations.

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

  Parameters3/5

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

  The input schema has 100% description coverage, so the parameters are already well documented. The description adds minimal semantic value beyond listing the combination in prose; it does not introduce dependencies, constraints, or environment-specific details beyond what the schema already includes for apiKey.

  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 uses a specific verb 'verifies' with a clear resource ('AI provider + API key + model combination') and explicitly distinguishes the tool's role from the sibling tools by naming optiqra_ai_fix and optiqra_ai_insights. This makes the purpose unmistakable and contextually differentiated.

  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 explicitly states to use this tool 'before using optiqra_ai_fix or optiqra_ai_insights', providing clear timing guidance. It does not mention when to avoid using it or alternatives beyond the implied sequencing, but the primary usage context is well conveyed.

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

• optiqra_ai_insightsA
  4/5.0
  Behavior3/5

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

  No annotations exist, so the description carries the burden of disclosing behavior. It discloses API key handling (forwarded directly, never stored server-side), which is valuable. However, it does not mention failure behaviors, rate limits, or what happens if no API key is provided (though schema says optional via env var). This is 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.

  Conciseness5/5

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

  Two sentences, no fluff. The first sentence explains the core function and input constraint, the second addresses a crucial prerequisite. Every phrase earns its place.

  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 no output schema, the description sufficiently indicates the output is a strategic summary. It covers input (report), processing (across categories/pages), and a caveat (API key). Could be more explicit about return format or potential errors, but for the complexity shown, it is reasonably complete.

  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 all parameters are already documented. The description adds contextual meaning by stating the report must be a full OptiQra report from optiqra_analyze and that the API key is forwarded to the provider, but it does not elaborate further on individual parameters beyond the schema. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states a specific verb ('generate') and resource ('strategic, site-wide summary reasoning across all audit categories and pages'), and explicitly references optiqra_analyze as the producer of the input, distinguishing it from sibling tools that test or fix.

  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 sets clear context: it takes the report from optiqra_analyze and generates AI insights, implying it should be used after analysis. It does not explicitly list alternatives or when-not-to-use, but the sibling tool names (ai_test, ai_fix) provide implicit differentiation. The mention of API key requirements adds a practical precondition.

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

• optiqra_analyzeA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It clearly states the tool crawls the entire site and may take a considerable amount of time, which is a significant behavioral trait. It also explains that the output is a report with per-category scores and issue details, providing good transparency without contradicting 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.

  Conciseness5/5

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

  The description is concise and well-structured. It opens with the main action, lists the audit categories efficiently, states the return value, and ends with a practical warning about time. Every sentence earns its place, and there is 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?

  For a one-parameter tool with no output schema, the description is quite complete: it covers the tool's behavior, the audit scope, the return report format, and a performance caveat. It could optionally mention prerequisites like site ownership or robots.txt, but the core context is sufficiently provided.

  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?

  The input schema has 100% coverage, with the 'url' parameter already described as 'The URL of the website to analyze, e.g. https://example.com'. The description adds no additional parameter-specific detail beyond what the schema provides, so the baseline score of 3 is appropriate.

  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 explains the tool's purpose: it crawls a website and runs a comprehensive audit covering many specific categories (SEO, performance, accessibility, etc.). The verb 'crawls' plus the resource 'website' makes the action explicit, and the detailed list of audit areas distinguishes it from the vague sibling tool names.

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

  Usage Guidelines3/5

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

  The description gives context that the tool crawls the whole site and can take a while, implying it should be used when a full audit is needed. However, it does not explicitly mention when to use this tool versus the sibling tools (test, fix, insights) or any exclusions, leaving usage guidance mostly implicit.

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

• optiqra_ai_fixA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description discloses important behavioral traits: the API key is forwarded directly to the provider and never stored server-side. This addresses security/privacy behavior. However, it does not mention other behaviors like error handling, cost, or whether the fix is returned vs. persisted, which would add further transparency.

  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 includes critical context (input provenance, API key handling) without redundancy. Every sentence earns its place.

  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 purpose, input source, authentication, and privacy for a tool with no output schema or annotations. It could be more complete by outlining the expected response structure, but the essential context for invoking the tool is present.

  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 fully documents all four parameters. The description only states that an API key is required, which slightly overlaps with the schema's note that apiKey is optional if an environment variable is set. It adds no new semantic meaning beyond the schema.

  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 uses a specific verb ('generate a suggested fix') and identifies the resource (a single issue from an OptiQra report). It clearly distinguishes from siblings by specifying it operates on output from optiqra_analyze, while siblings like optiqra_ai_test and optiqra_ai_insights serve different purposes.

  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 provides clear context on when to use: after optiqra_analyze produces an issue, and mentions the API key prerequisite. It does not explicitly state when not to use or name alternatives, but the sibling list and the description's provenance reference imply appropriate usage.

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