Server Quality Checklist

Tool Scores

• search_benefitsA
  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 full responsibility for behavioral disclosure. It explains that the tool searches a dictionary and that it returns official service names, which implies a read-only list operation. However, it does not disclose any side effects, permissions needed, pagination behavior, or what happens on no matches. While safe to assume, the description is thin on behavioral detail.

  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, no filler. The first sentence defines the resource and purpose; the second provides usage context. Front-loaded with the key verb 'Search' and the specific resource. Every word 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 tool is simple (2 params, no output schema) and the description covers purpose and usage adequately. It implies the return value (a list of official names) but does not explicitly state the output format. Given the simplicity and the connection to `search_queues`, this is a minor gap, but the lack of an explicit return description slightly reduces completeness.

  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% – both `name` and `limit` are fully described in the schema (partial name, case-insensitive, default 25). The description adds no extra meaning about parameters; it only talks about the overall purpose. Baseline of 3 is appropriate since structured data already documents parameters.

  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 states the specific resource ('NFZ benefit dictionary') and that it provides official service names used by `search_queues`. This clearly distinguishes it from sibling tools like `search_queues` (which accepts these names) and `list_provinces` (which lists provinces, not benefits). The purpose is unambiguous.

  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 gives explicit instruction: 'Use this to discover the exact wording before searching queues.' This tells the agent when to invoke the tool (before using `search_queues`) and the rationale. It implicitly contrasts with `search_queues` by positioning this as a prerequisite lookup step.

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

• list_provincesA
  4.3/5.0
  Behavior3/5

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

  With no annotations, the description must bear the full burden of behavioral disclosure. It states only the return content, not whether the operation is read-only, cached, or has any side effects. For a simple lookup this is a minor gap, but it does not disclose any extra behavioral traits beyond the bare return statement.

  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?

  A single, compact sentence that conveys the complete purpose without any fluff. All information is front-loaded and no sentence is wasted.

  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 static mapping retrieval with no parameters and no output schema, the description is entirely sufficient. An agent knows exactly what to expect and there are no hidden complexities that need explaining.

  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 according to the rubric the baseline is 4. There is nothing for the description to add about parameter meanings, and the description does not attempt to invent any.

  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 action ('Return'), the resource ('mapping of 2-digit province codes to voivodeship names'), and the context ('used by NFZ'). It is instantly distinguishable from the sibling search tools, which are queries for benefits and queues, not static mappings.

  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 that this tool is for retrieving a fixed reference mapping, which contrasts with the search functionality of the siblings. However, it does not explicitly state 'use when you need province codes' or explicitly name alternatives, though the context makes it obvious.

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

• search_queuesA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure, and it delivers: it reveals the return payload (first-available date and average wait time per provider), the partial case-insensitive matching behavior of benefit, and the case semantics. It does not cover result ordering or no-results behavior, but the core behavioral traits an agent needs are disclosed upfront.

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

  Conciseness4/5

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

  Three sentences with the core purpose and payload front-loaded before parameter detail. The case explanation repeats schema-stated information, which is mild redundancy, but the prose remains compact and every sentence earns its place meaningfully.

  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 annotations and no output schema, the description compensates well by stating the return content (first-available date and avg wait time), matching behavior, and enum semantics. It could add result ordering or pagination notes for a provider-list search, which keeps it a notch below fully 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%, so the baseline is 3, but the description adds real value beyond the schema: it explains that benefit is a partial case-insensitive match against the official service name and routes uncertain agents to search_benefits. The case explanation duplicates the schema enum descriptions, but the partial-match clarification is no free value from the structured fields.

  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?

  States a specific action (search waiting lists) with a clear resource (NFZ kolejki), scope (by province) and outcome (returns first-available date and average wait time per provider). Differentiates cleanly from search_benefits (finds service names) and list_provinces (province codes), so an agent can tell them apart without opening schemas.

  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 advises 'use search_benefits first if unsure' about the service name, which is direct routing guidance to a sibling. It defines the case enum values clearly. It does not state when to prefer list_provinces or explicitly exclude alternatives, but given the siblings are narrow utility lookups, the guidance is adequate.

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