Server Quality Checklist

Tool Scores

• lookup_companyA
  4.6/5.0
  Behavior5/5

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

  Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses important behaviors: identifier normalization and zero-padding, country-specific register behavior, the requirement to read returned notes for caveats like bankruptcy or dissolution, and retry/error semantics including that upstream errors have already been retried once.

  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?

  The description is front-loaded with the core purpose and is information-dense, with country details and error handling clearly separated. It is somewhat long and partially duplicates the schema's parameter documentation, but the length is justified by the multi-country behavior and error guidance.

  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 tool with two well-documented parameters, rich annotations, an output schema, and sibling tools, the description is complete: it covers when to use it, country-specific identifier formats, error handling, retries, and warnings about the returned data. Nothing essential is missing for correct invocation.

  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 baseline is 3 even if the description adds no parameter info. The description does reinforce the schema's details about organisasjonsnummer, CRN, zero-padding, and accepted country codes, but it mostly duplicates what the input schema already states rather than adding substantial new parameter-level meaning.

  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: 'Look up a company by its national identifier and get the full CompanyReport'. It clearly distinguishes lookup from search by stating that lookup is used once the identifier is already known, and it names the sibling search_company as the source of an id.

  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?

  It explicitly states when to use the tool: 'Use it once you have the identifier — from the user, an invoice, a contract, or a search_company hit's id.' It also provides alternative routing on errors: use search_company for invalid_id/not_found and list_countries for unsupported_country.

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

• company_deadlinesA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare the tool read-only, idempotent, open-world, and non-destructive, and the description adds substantial behavioral detail beyond that: `due_date` must be quoted rather than `statutory_date`, `applies_because` explains date provenance, UK dates never roll off weekends, `days_until` can go negative, and an empty list is a real answer. It even documents error propagation from `lookup_company` with actionable hints.

  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 long but every sentence carries operational weight: country coverage, result-field guidance, edge-case meanings, and error handling are all present with no filler. The top-loaded purpose sentence immediately orients the agent, and the paragraphs follow a logical order from scope to output interpretation to failures.

  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 tool with three parameters, an output schema, and complex country-specific behavior, the description is unusually complete. It explains what each country's results mean, how to quote results, when an empty list is legitimate, how errors are structured, and how to recover from `bad_request`. Nothing an agent needs to call and interpret this tool correctly is left unaddressed.

  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 input schema already covers all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful extra semantics: it maps `country='NO'` to the Norwegian deadline calendar and `country='GB'` to the two Companies House obligations, and it links `today` to reproducibility and `bad_request` format errors. That is more than the schema alone provides, though not a full replacement for the schema's detailed `id` documentation.

  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 opening sentence states a specific verb and resource: 'Give the next occurrence of each statutory filing deadline a company faces.' It then distinguishes the two supported country scopes (Norway and the UK) and their registries and obligation types, so the agent can tell exactly what the tool covers and how it differs from sibling lookup/search/validation tools.

  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 on when this tool applies, including country-specific obligations, the meaning of an empty `deadlines` list, and the need to pass `today` for reproducible answers. It does not explicitly name alternatives or say 'use X instead when Y', so it falls just short of a 5, but the usage context is strong.

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

• validate_company_idA
  4.8/5.0
  Behavior5/5

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

  Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses meaningful behavior: no network call, checksum validation for Norway vs shape-only validation for the UK, normalisation rules, the guarantee that it never raises for malformed identifiers, and the unsupported_country error contract. No contradiction with annotations exists.

  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?

  The description is structured logically: purpose first, then per-country behavior, then usage recommendation, then return/error behavior. It is a bit verbose in places — such as repeating the 'cheap' idea — but every major sentence contributes useful operational detail.

  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-only tool with an output schema, the description covers all necessary operational aspects: what it validates, how each supported country behaves, the error contract, and when to use it versus lookup_company. Nothing an agent needs to invoke it correctly is missing.

  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 both parameters well (100% coverage), so the baseline is 3. The description adds extra semantic value by explaining the validation algorithms, the zero-padding and upper-casing behavior, and the meaning of a GB valid:true. This goes beyond what the schema provides, though not a huge margin.

  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: 'Check whether a national company identifier is well-formed — no network call.' It clearly separates this from lookup_company by framing it as a cheap pre-check, and from search_company by focusing on validation rather than search. The scope 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?

  It explicitly tells the agent when to use it: 'Use it on user input or a spreadsheet column before spending a real lookup_company call, since it is instant and free.' It also routes unsupported countries to list_countries. This gives clear contextual guidance for choosing the tool.

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

• list_countriesA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds genuinely valuable behavior beyond that: stub/example modules are hidden, the registry set grows dynamically without schema changes, and — most notably — 'This tool has no error mode; a failure here is a bug, not something to retry differently.' This last disclosure directly shapes agent behavior by preventing useless retry loops.

  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 tightly packed paragraphs with no filler. The first establishes the verb, resource, and return fields; the second delivers usage timing, a prohibition, a filtering behavior, and error semantics. Every sentence earns its place and the core purpose is front-loaded in the opening clause.

  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, read-only listing tool, this is complete. The output schema exists to document the return structure, annotations cover the safety profile, and the description covers everything else an agent needs: what is returned, when to call it, what is filtered out, and how to interpret failures. There are no gaps an agent would have to guess about.

  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 with an empty schema at 100% coverage, so there are no input semantics to clarify. Per the baseline for zero-parameter tools, a 4 is appropriate; the description correctly spends no space on inputs and instead uses that space for output contents and usage guidance.

  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 — 'List every national company registry this service can answer for right now' — and goes on to enumerate exactly what each entry contains (id_scheme, source URL, licence, credential requirements). This clearly differentiates it from the sibling tools (lookup_company, search_company, company_deadlines, validate_company_id), none of which list available registries.

  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 invocation conditions: 'Call this before your first lookup in a country you have not used here before, or whenever a user names a country you are unsure is supported.' It also provides a strong negative rule — 'never hard-code a country list of your own' — which prevents the agent from caching or assuming a static list. No alternative tool is relevant for this operation, so no exclusion is needed.

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

• search_companyA
  5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral detail beyond them: search hits are deliberately thin, order is the register's own relevance order, zero hits returns an empty array and hint, and errors have a structured shape with retry guidance. It also notes that 'UK' is rejected and country codes should not be hard-coded, reinforcing the openWorldHint.

  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 long but every sentence carries operational value. It is front-loaded with the core purpose and usage, then moves into edge cases and error handling in a logical order. No filler or tautological repetition; the length is justified by the tool's complexity.

  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?

  The description is complete for a search tool of this complexity. It covers return-value expectations (thin hits, confidence, relevance order), zero-hit semantics, error codes and retry policy, supported countries, and how to proceed to `lookup_company`. The presence of an output schema makes it unnecessary to document every return field, and the description still adds useful context about interpretation.

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

  Parameters5/5

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

  Even though schema coverage is 100%, the description adds meaning beyond the schema: it explains what each country code maps to, why `name` is free text rather than an identifier, the exact bounds and failure behavior for `limit`, and the presence of a `confidence` field on hits. This significantly improves the agent's ability to use the parameters correctly.

  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 verb, resource, and scope: "Search a national company register by name, when you have a name rather than an identifier." It explicitly contrasts with `lookup_company`, which is the sibling it must not be confused with, and explains the two supported country-specific registers.

  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 when-to-use guidance: use it when the user provides a company name, then call `lookup_company` with the `id` of the right hit. It also covers when NOT to treat zero hits as an error, how to handle invalid input, and when to call `list_countries` first, leaving no ambiguity about tool routing.

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