Server Quality Checklist

Tool Scores

• get_clarity_insightsA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description bears full responsibility for behavioral disclosure. It extensively discloses rate limits, API lookback restrictions, urlFilter being post-processing only, the 1,000-row cap, auto-adding a URL dimension, and the failure mode when dimension slots are full. This is highly transparent.

  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?

  Every sentence in the description earns its place, covering purpose, constraints, rate limits, and edge cases in a logical order (purpose → important limitations → urlFilter specifics). It is dense but not verbose, and front-loaded with the core purpose.

  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?

  No output schema exists, but the description gives a reasonable sense of return content ('traffic, scroll depth, ...') and thoroughly covers operational caveats (rate limits, filtering, dimension slots). It does not detail response structure, but for a dashboard insights fetch, the provided context is nearly complete.

  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 coverage is 100% (all 5 parameters documented), so the baseline is 3. The description adds significant value by explaining urlFilter's post-processing behavior and the auto-add/failure interplay with dimensions, which the schema alone does not convey.

  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 ('Fetch') and a named resource ('Microsoft Clarity dashboard insights'), enumerating sample metrics (traffic, scroll depth, etc.) and explicitly scoping to 'last 1-3 days' with 'up to 3 dimensions'. This clearly distinguishes the tool's function from sibling tools like get_clarity_historical_insights.

  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 usage context: rolling 1-3 day lookback, a 10-requests/day project limit, and explicit advice to 'batch dimensions thoughtfully rather than making repeated calls'. It implies the tool is for recent data only but does not explicitly name sibling tools as alternatives.

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

• capture_clarity_snapshotA
  4.7/5.0
  Behavior5/5

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

  No annotations are provided, so the description fully discloses key behaviors: fixed numOfDays=1, output file path and naming with UTC date, overwrite semantics, daily request consumption, and manual trigger requirement. This goes well beyond a simple verb+object description and provides the agent with complete operational 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 concise but information-dense, covering purpose, file path, trigger, cost, and safety in two sentences. Every sentence contributes operational context with no filler or redundancy.

  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 zero-parameter, no-output-schema tool with no annotations, this description is remarkably complete: it states the exact file output, preservation rationale, manual trigger, API usage cost, and idempotent re-run behavior. The only potential gap is the lack of an explicit return value, but given no output schema and the nature of a file-writing tool, it is sufficient.

  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 and the schema is empty (100% coverage). The description explains the fixed configuration (numOfDays=1, URL breakdown) and output side effects, which adds context beyond the empty schema. With no parameters to document, the description meets the baseline and provides no unnecessary detail.

  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?

  Clearly states it captures today's Clarity insights and saves to a local file, with the purpose of enabling future historical retrieval. Distinguishes itself from siblings by describing its snapshot/preservation role versus live/current retrieval.

  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?

  Explicitly states this must be triggered manually with no background schedule, telling the agent when to run it. Also clarifies it uses 1 of 10 daily API requests and is safe to re-run (overwrites rather than errors). However, it doesn't explicitly name alternatives for current data access or provide 'when not to use' scenarios.

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

• get_clarity_historical_insightsA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description fully discloses behavioral traits: it reads only local files, never calls the API, explicitly lists found/missing dates so gaps are visible, and states there is no backfill possibility. It also mentions the performance consideration of uncompressed days for wide ranges, which is beyond what any structured field could convey.

  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 front-loaded with the primary purpose and each subsequent sentence adds critical constraint or usage detail. Despite being six sentences long, there is no filler; every sentence reveals a non-obvious aspect of the tool's behavior or a practical tip.

  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—historical local data, API limitations, and gap reporting—the description covers all necessary context: it clarifies the source (local snapshots), the constraint (no API access), the gap behavior, the optional filter, and performance advice. Even without an output schema, it explains what the result will include (found/missing dates), making the tool fully understandable.

  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 coverage is 100%, so the baseline is 3. The description reinforces inclusive date handling and UTC, but its added value comes from clarifying that urlFilter 'post-filters each found day's rows' and advising its use for wide date ranges to avoid oversized responses. This goes beyond the schema's brief descriptions, though much of the core meaning is already in the structured definitions.

  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 and resource: 'Return locally-captured Clarity snapshots for each day from startDate to endDate.' It clearly distinguishes itself from siblings by emphasizing it reads local files only and never calls the Clarity API, contrasting with get_clarity_insights and capture_clarity_snapshot.

  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?

  The description explicitly explains when to use this tool versus alternatives: it can only retrieve previously captured days, cannot use the Clarity API due to its 1-3 day limitation, and cannot backfill missing dates. It also references get_clarity_insights for urlFilter semantics and recommends passing urlFilter for wide date ranges to reduce data volume.

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