Server Quality Checklist

Tool Scores

• pirsch_query_statisticsA
  3.5/5.0
  Behavior2/5

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

  With no annotations provided, the description must carry the burden of behavioral disclosure. It only states 'Read', indicating a non-mutating operation, but provides no details on authentication, rate limits, pagination, or output behavior. For a complex analytics tool, this is insufficient.

  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 long, front-loaded with the core purpose, and every clause adds value. It avoids redundancy and is efficiently structured for quick comprehension.

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

  Completeness2/5

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

  Given the tool's complexity (39 parameters, no output schema, no annotations), the description is far from complete. It does not explain return values, how the various filters interact, or what the 'scale' parameter controls. The description only provides a high-level overview, leaving important context missing.

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

  Parameters2/5

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

  Schema description coverage is only 23%, and the description adds little to compensate. It explains that domainId comes from pirsch_list_domains and lists high-level metric categories, but the 39 parameters, including many unannotated filters, remain unexplained. The description adds limited 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 clearly states it reads Pirsch Analytics v1 statistics for a domain and date range, with a specific verb ('Read') and resource. It also lists the supported metric categories (traffic, pages, events, etc.), which differentiates it from sibling tools like pirsch_list_domains and pirsch_get_domain.

  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 a clear prerequisite: 'Pass domainId from pirsch_list_domains to query a specific domain.' This establishes when the tool is used and how to obtain the required domain ID. It doesn't explicitly mention alternatives or exclusions, but the sibling tools are distinct enough that usage context is clear.

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

• pirsch_list_domainsA
  4.2/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. 'List' implies a read-only operation, but 'safe domain summaries' is vague and does not disclose details like rate limits, errors, or any side effects. The transparency is adequate but not rich, so a score of 3 is appropriate.

  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 concise sentences, front-loaded with the action ('List every Pirsch domain'), and every phrase adds value. No fluff or repetition.

  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 simple list tool with no parameters and no output schema, the description is fairly complete. It explains the purpose (domain selection for statistics queries) and the scope (domains available to the OAuth client). Some details about the return format are absent, but the simplicity keeps the bar low.

  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 zero parameters, so the baseline is 4. The description correctly provides no parameter information since none exists, and there is no gap to compensate for.

  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 the specific verb 'List' and names the resource 'every Pirsch domain', clearly showing the tool's purpose. It also adds context about the OAuth client and the intended use for selecting domainId in statistics queries, which distinguishes it from sibling tools like pirsch_get_domain and pirsch_query_statistics.

  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 the tool: before querying statistics, to obtain domainId values. It does not explicitly mention alternatives, but the context of the sibling tools and the stated purpose provide clear guidance on its usage without needing exclusions.

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

• pirsch_get_domainA
  4.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 behavioral disclosure burden. It reveals the key behavioral nuance: the default domain returned depends on client scope. It does not discuss edge cases or side effects, but for a read-only getter, the scope explanation adds meaningful 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 then adding scope context. Every sentence earns its place with no redundancy or 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 no-argument getter, the description is reasonably complete: it explains what is returned, how it varies by scope, and provides usage guidance. It could explicitly mention pirsch_list_domains for the account-scoped case, but the sibling tool list already provides that context.

  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 zero parameters, so the schema inherently covers everything. The description adds no parameter details because there are none to add; the baseline of 4 applies.

  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's function: 'Return the Pirsch SDK's default domain.' It also distinguishes scope-dependent behavior (dashboard-scoped vs account-scoped) and references statistics queries, separating it from siblings pirsch_list_domains and pirsch_query_statistics.

  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 gives clear context: dashboard-scoped clients can use this directly, while account-scoped clients 'should select one explicitly for statistics queries.' This implies when not to use it, though it does not explicitly name the alternative tool (pirsch_list_domains).

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