Server Quality Checklist

Tool Scores

• clinicaltrials_get_study_countA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds behavioral value by noting it is 'Fast and lightweight' and 'without fetching study data,' and by suggesting repeated calls with different filters, which reinforces safe, side-effect-free usage. No contradiction with 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?

  Three sentences with no filler. The core purpose is front-loaded, followed by concrete use cases. Every sentence earns its place, and the description is appropriately sized for the tool's simplicity.

  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 the tool's complexity (11 optional parameters), the rich schema descriptions, and the presence of an output schema, the description is largely complete. It covers the main use cases and distinguishes the tool from siblings. It does not explicitly mention that calling with no filters returns the overall total, but the schema's optional parameters and the phrase 'matching a query' make that inferable.

  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 already documents all 11 parameters in detail. The description adds only high-level examples of filters ('phase, status, condition') that map to existing parameters, but no new semantic meaning 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 states a specific verb and resource: 'Get total clinical trial study count from ClinicalTrials.gov matching a query.' It also distinguishes itself from sibling tools by explicitly saying 'without fetching study data,' which separates it from search/record tools. The use-case framing ('quick statistics', 'breakdowns') further clarifies its unique role.

  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 for when to use it: 'Use for quick statistics or to build breakdowns by calling multiple times with different filters.' It implies the alternative (fetching study data) is not this tool's purpose, but it does not explicitly name sibling tools or state when not to use it. This is clear guidance with no exclusions, but not fully explicit.

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

• clinicaltrials_find_eligibleA
  4.3/5.0
  Behavior5/5

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

  Beyond the readOnlyHint/idempotentHint annotations, the description discloses substantial non-obvious behavior: the re-ranking so exact condition matches surface above fuzzy MeSH tangential matches, the site-level filtering capped by locationLimit (omitting a study's hundreds of other sites), the nearest-recruiting-site fallback so an enrollable site is never hidden, and the locationSummary counters. This is rich, candid behavioral disclosure that materially changes how an agent interprets results.

  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 purpose is front-loaded in sentence one, and every subsequent sentence earns its place (re-ranking, site capping, recruiting fallback, pointer to sibling). It runs slightly long and duplicates some locationLimit detail that already lives in the schema description, but the structure is logical and efficient overall.

  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 tool with 8 params, nested objects, and an output schema, the combination of description, schema, and annotations is thorough: purpose, eligibility behavior, site truncation, fallback logic, and the record-fetching alternative are all covered, while return values are delegated to the output schema. Few gaps remain, and none are critical to calling the tool correctly.

  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% with detailed descriptions for every parameter — location's nested object shape, conditions' phrase/OR semantics, locationLimit's cap and locationSummary behavior, recruitingOnly/healthyVolunteer defaults. The description reinforces the required params (age, sex, conditions, location) and echoes locationLimit behavior, but adds little parameter meaning beyond what the schema already delivers, matching the baseline 3.

  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 — 'Match patient demographics and conditions to eligible recruiting clinical trials' — and specifies scope: age, sex, conditions, location. It distinguishes itself from sibling clinicaltrials_search_studies (radius-based geo search) inside the location parameter and from clinicaltrials_get_study_record (full record fetch), so an agent can separate it from alternatives.

  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 clearly frames the tool as patient-to-trial eligibility matching and names two sibling alternatives with their selection conditions: fetching a complete record via clinicaltrials_get_study_record, and radius-based geographic search via clinicaltrials_search_studies with geoFilter. It doesn't spell out when-not-to-use scenarios versus every sibling, but the context and alternatives are explicit enough.

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

• clinicaltrials_get_field_valuesA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds behavioral context by noting that an empty list is rejected (not treated as 'every field'), which is a useful edge-case disclosure beyond the schema. It also implies the tool returns counts per value, which is behavioral information. No contradiction with 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 two sentences, front-loaded with the core purpose and immediately followed by a concrete use case. Every sentence earns its place: the first states what it does, the second explains when to use it and gives examples. No fluff or redundancy.

  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 the tool's simplicity (one parameter, no nested objects) and the presence of an output schema, the description is largely complete. It covers purpose, usage timing, and parameter semantics. The only minor gap is that it doesn't explicitly state the return format, but the output schema presumably covers that. For a read-only exploration tool, this 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?

  Schema description coverage is 100%, so the schema already documents the 'fields' parameter well, including examples and the rejection of empty lists. The description adds value by explaining the purpose of the parameter (exploring filter options) and reinforcing the PascalCase requirement. Since coverage is high, a baseline of 3 applies, but the description's extra context about usage and the empty-list rejection pushes it to 4.

  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 purpose: discovering valid values for ClinicalTrials.gov fields with study counts per value. It names specific example fields (OverallStatus, Phase, InterventionType, StudyType, LeadSponsorClass) and positions it as a pre-search exploration step, distinguishing it from sibling tools like clinicaltrials_get_field_definitions.

  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 says to use this tool 'before building a search' to explore filter options, which provides clear context. It doesn't explicitly state when not to use it or name alternatives, but the sibling list and the reference to clinicaltrials_get_field_definitions for finding more field names give some guidance. A clear usage context is present, though exclusions are not explicit.

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

• clinicaltrials_get_field_definitionsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate that. It adds behavioral context by explaining that search returns ranked matches, drill returns a section's fields, and overview gives a summary. This goes beyond the annotations without contradicting them. Minor omission: no mention of pagination or rate limits, but for a read-only helper that's acceptable.

  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 moderately long but every sentence carries information: purpose, examples, and mode breakdown. It is logically structured, starting with the core purpose, then detailing modes. No filler or repetition exists. It could be slightly tightened, but it remains efficient and front-loaded.

  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 the tool's moderate complexity (5 parameters, 3 modes) and the presence of an output schema, the description covers all necessary aspects: what the tool returns, which modes exist and when to use them, and how it fits into the broader toolset. It does not miss critical details for an agent to correctly invoke it. Slight gaps like not describing error behavior are negligible for a read-only helper.

  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 description coverage is 100%, so parameters are well-documented in the schema. The description adds value by providing concrete examples for query ('enrollment', 'sponsor'), clarifying which parameters apply to which mode, and giving a sample dot-notation path for drill. This supplements the schema without redundancy, justifying a score above the baseline 3.

  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 a specific purpose: resolving valid field names from the ClinicalTrials.gov data model, with concrete examples of PascalCase identifiers. It clearly explains that these names are used as inputs to other tools, distinguishing it from siblings that retrieve data or search studies. The verb 'resolve' and resource 'field definitions' are precise.

  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 says when to use this tool: to obtain field names for the 'fields', 'advancedFilter', and 'sort' parameters of other tools, and as input to clinicaltrials_get_field_values. It also details the three operational modes with conditions (e.g., search requires query, drill requires path, overview needs no args). This is clear, actionable guidance with no ambiguity.

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

• clinicaltrials_get_study_recordA
  4.5/5.0
  Behavior5/5

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

  Adds meaningfully beyond the readOnly/openWorld/idempotent annotations: explains that caps preserve original totals in filtersApplied only when a list is actually trimmed, that primary outcomes and seeAlsoLinks are never capped, and that nearLocation geocoding is city-centroid and drops locations without coordinates. This is exactly the kind of non-obvious runtime behavior an agent needs.

  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 front-loaded sentences with no filler: first states the primary purpose, second captures the one non-obvious behavioral subtlety about caps and filtersApplied. The prose is dense but every clause adds value.

  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 output schema handles return-value expectations, the param schema thoroughly documents behavior, annotations cover safety and idempotency, and the description adds scope, cap semantics, and geocoding limitations. For an agent deciding whether and how to call this tool, nothing meaningful is missing.

  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%, and every parameter already has a thorough description including ranges, defaults, and behavior. The tool description itself adds little beyond a concise summary of the trimming behavior, 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?

  Starts with a specific verb and resource: 'Fetch a single clinical trial study by NCT ID'. Unambiguously distinguishes this from sibling tools like the search/count tools, and the 'by NCT ID' identifier makes the invocation target crystal clear.

  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 makes clear this is the tool for fetching one study by NCT ID, and the nearLocation parameter description explicitly points to clinicaltrials_search_studies for broad geographic filtering. However, it does not directly contrast with all relevant siblings such as clinicaltrials_get_study_results, so the routing guidance is good but not exhaustive.

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

• clinicaltrials_get_study_resultsA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so no contradiction exists. The description adds meaningful behavioral context beyond annotations: full mode can exceed 500KB per study, results can be bounded with summary or caps, and trims are reported per study in filtersApplied. This is valuable operational disclosure not present in the 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 three sentences with no filler; it opens with the core action and resource, then states the critical prerequisite, then the performance caveat. Every sentence carries load-bearing information for correct invocation.

  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 rich input schema, output schema, and annotations, the description covers the remaining non-obvious context: the hasResults precondition, the upstream search step, and the large-payload risk with mitigation options. Nothing essential for an agent to select and invoke the tool correctly is missing.

  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 because the schema already documents every parameter, including defaults, enums, bounds, and per-parameter behaviors. The description body adds a useful cross-parameter guidance about using summary/caps to bound payloads, but it does not add meaning beyond what the schema already provides.

  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 names a specific verb and resource: 'Fetch clinical trial results data from ClinicalTrials.gov,' and enumerates the included categories (outcome measures, adverse events, participant flow, baseline, results metadata). It also scopes the tool with 'for completed studies' and 'Only available for studies where hasResults is true,' making its purpose distinguishable from siblings like clinicaltrials_get_study_record.

  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 an explicit when: use it for study results data, and an explicit when-not: only when hasResults is true. It also names the follow-on workflow: 'Use clinicaltrials_search_studies first to find studies with results,' which routes the agent away from calling this tool prematurely.

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

• clinicaltrials_search_studiesA
  4.6/5.0
  Behavior5/5

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

  The description goes well beyond the annotations by explaining nuanced behaviors: empty lists are rejected, the unknown-enrollment sentinel is excluded by default and pollutes RANGE queries, nctIds lift the exclusion, geoFilter re-sorts locations by proximity, and ancestor terms broaden results. It also clarifies syntax pitfalls (e.g., brackets, commas) and data-size concerns, making tool behavior highly predictable.

  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 main description is concise (three sentences) and front-loaded with the core purpose and key features. It then points to the fields parameter and the ~70KB record size, which are critical for efficient usage. This is appropriately sized for a tool with 18 parameters; the detailed parameter semantics are delegated to the schema, avoiding duplication.

  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 the tool's complexity and the richness of the schema (100% parameter coverage with detailed descriptions), the main description is sufficient to orient an agent. It explains the default return format and the purpose of the fields parameter, while edge cases and parameter-specific behaviors are covered in the schema. The presence of an output schema further fills any gaps, so overall context is adequate.

  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 descriptions for each parameter are already very detailed, covering syntax, matched fields, and defaults. The main description adds cross-cutting insights such as the relationship between nctIds and unknown-enrollment exclusion, the effect of ancestor terms on result breadth, and the sentinel's impact on sorting and ranges. This enriches understanding beyond the schema, though some details are redundant with individual parameter descriptions.

  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 purpose with a specific verb ('Search for clinical trial studies from ClinicalTrials.gov') and enumerates its capabilities (full-text and field-specific queries, filters, pagination, sorting, field selection). It effectively distinguishes this from sibling tools like clinicaltrials_get_study_record, making the purpose unambiguous.

  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 guidance on when to use this tool (e.g., for searching, with various filter options) and includes practical hints like calling clinicaltrials_get_field_definitions for field names and using the fields parameter for full fidelity. However, it does not explicitly contrast with sibling tools (e.g., 'use this instead of get_study_count when you need study details'), but the functional scope is evident from the description.

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