Server Quality Checklist

Tool Scores

• list_appointmentsB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does state that the operation lists appointments, defaults date_from to today, and returns a list of dicts with known keys, which establishes a read-only intent. However, it does not define 'recent,' describe ordering, pagination, or status filtering, and the 'and more' tail is vague.

  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 short and front-loaded with the core purpose, followed by a compact Args section and a Returns line. It has no filler, though the ambiguous 'recent appointments' phrasing could be made more precise without much extra length.

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

  Completeness3/5

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

  For a single optional parameter and a tool with an output schema, the description is mostly sufficient: it documents the parameter and the shape of results. The main completeness gap is the lack of guidance around the sibling list_past_appointments, which leaves an agent unsure whether 'recent' overlaps with past appointments.

  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 0%, but the description compensates by specifying that date_from is an ISO date string (YYYY-MM-DD), acts as the starting point, and defaults to today. This adds real meaning beyond the bare nullable string in the schema, though it does not clarify null handling explicitly.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a clear verb and resource: 'List upcoming and recent appointments.' It identifies the domain and time scope, but it does not distinguish this tool from the sibling list_past_appointments, and 'recent' is left undefined.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  There is no guidance on when to use list_appointments versus its sibling list_past_appointments, nor any exclusion criteria such as 'past appointments should be fetched with list_past_appointments.' The parameter note about starting from today implies a temporal usage, but the choice between tools is left entirely to inference.

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

• get_patient_infoA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It does disclose the return shape ('Returns a dict with keys: fullName, title, contacts, identity'), which is useful. However, it omits access requirements, error behavior, and whether fields may be missing or null, so transparency is incomplete.

  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 lean sentences: the first states purpose and scope, the second lists the return keys. Every sentence carries information and no filler is present.

  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 parameterless read of a profile, the description documents the returned fields directly, compensating for the lack of an output schema. Minor gaps remain around usage selection and behavioral caveats, but the tool's simplicity keeps these from being critical.

  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 has zero parameters and full schema coverage, which is the baseline case for 0 params. The description adds no parameter detail because none is required; the schema already communicates that no arguments are needed.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Get') and a specific resource ('basic patient profile information') and enumerates its contents (name, contacts, identity numbers). That is clear and implicitly distinguishes it from siblings like get_clinical_document or list_invoices, though it does not explicitly call out any sibling.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance is provided on when to use this tool instead of an alternative. The word 'basic' implies a scope limitation, but no exclusions or conditions are stated, leaving the agent without criteria for tool selection.

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

• list_clinical_documentsA
  4/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 behavioral burden. It usefully discloses the return shape (list of dicts with specific keys) and the scope (all clinical documents), but it does not mention edge cases like empty results, pagination, ordering, or whether the list is system-wide.

  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 sentences, both informative: the first states purpose and scope, the second describes the return value. No filler or redundant information.

  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 zero-parameter list tool, the description covers the essential context: what is listed, examples of document types, and the returned fields. The presence of an output schema reduces the need to elaborate return values further, though a note about bulk output or pagination would make it 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?

  The input schema has zero parameters, so there is nothing for the description to add about parameters. The baseline of 4 applies; no ambiguity exists.

  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 a specific verb ('List') and resource ('clinical documents') with concrete examples of included types (imaging, cardiology, pathology). The 'List all' phrasing clearly differentiates it from the sibling tool get_clinical_document, which implies retrieving a single document.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies its usage: use it to enumerate all clinical documents. However, it does not explicitly mention when not to use it, such as 'use get_clinical_document for a specific document,' nor does it address potential overlap with list_exam_results or list_prescriptions.

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

• list_invoicesA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden. It discloses that the operation returns a list of dicts with specific keys, but does not mention pagination, errors, or auth requirements. For a read-only list operation this is adequate but not rich

  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 short sentences: the first states the action, the second lists return keys. Every sentence provides value, with 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 zero-parameter list tool, the description is nearly complete: action, scope, and return shape are present. Having an output schema already covers detailed return types, so the only minor gap is operational context like pagination or empty-result behavior, which is less critical for a simple list

  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?

  There are zero parameters, so the schema and descrition have nothing to explain. The baseline for 0 param is 4, and the description correctly adds no unnecessary parameter 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?

  The description clearly states the verb 'List' and the resource 'all invoices from the CUF portal', making the action and scope explicit. It is distinguishable from siblings like get_invoice (singular) and list_clinical_documents (different resource).

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies use when all invoices are needed, but does not explicitly say when to avoid it or prefer a sibling such as get_invoice for a single invoice. No alternatives or exclusions are mentioned, so usage context is only implied

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

• list_exam_resultsA
  4.1/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the burden. It discloses the return structure and the possibility of an empty list, which is useful. However, it does not explicitly state read-only behavior, error conditions, pagination, or ordering, leaving some behavioral gaps.

  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 compact, front-loaded with the main action, and each sentence adds value: the purpose, the return format, and the empty-list caveat. There is no redundancy or fluff.

  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 list tool, this is complete enough. The description states what is listed, describes the return shape, and warns about empty results. Even without an output schema shown, the agent has sufficient information to invoke and interpret the result.

  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 100% schema description coverage by default. There is nothing for the description to add about parameter meanings, so 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 uses a specific verb ('List') with a clear resource ('active lab/exam results available in the portal'). The resource is distinct from sibling tools like invoices, prescriptions, and clinical documents, so an agent can immediately know what this tool covers.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description clearly indicates when the tool is appropriate—when active lab/exam results are needed—but it does not mention alternatives or when not to use it. Sibling tools like list_clinical_documents exist, and no differentiation or exclusion is provided.

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

• list_prescriptionsA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does so well: it discloses that the tool scrapes a Drupal-rendered HTML page, uses a separate auth system, and returns a dict list with specific keys. It doesn't mention error handling or rate limits, but for a read-only list operation the key behavioral traits are disclosed.

  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?

  Compact and front-loaded: the purpose sentence comes first, followed by necessary behavioral context, output shape, and parameter details. Every sentence earns its place and there is no filler.

  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 single-parameter, read-only listing tool, the description covers purpose, scraping/auth context, return fields, and the default parameter behavior. An output schema exists, so return-value documentation is not a burden. It omits potential failure modes or rate-limit notes, but nothing is missing for correct basic invocation.

  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 provides no property descriptions (0% coverage), so the description must compensate, and it does: 'years: List of years to fetch (default: current year and 2 prior years)' defines the purpose and default for the only parameter. It could add accepted ranges or explicit behavior for null, but the essential semantics are clear.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a concrete operation: 'List exam prescriptions from the CUF portal (www.cuf.pt)', naming both the resource and source. The scraping detail hints at a distinction from GraphQL-based siblings, but it never names or contrasts an alternative such as get_prescription or list_clinical_documents, so it stops short of a 5.

  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?

  Provides clear context: this is the tool for listing CUF prescriptions, and it explicitly notes that prescriptions use a separate auth system from the GraphQL API, which steers an agent away from GraphQL-based alternatives. It doesn't state explicit when-not-to-use conditions or name sibling tools, but the intended usage is unambiguous.

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

• get_notificationsA
  4.2/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 burden of behavioral disclosure. It discloses the return type, the returned keys, and the effect of include_read. This is adequate for a simple read-only list operation, though it does not mention ordering, pagination, or whether read notifications are mutated.

  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 short, front-loaded with the core purpose, and structured into Args and Returns sections. Every sentence adds necessary information without 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?

  The tool is simple with one optional parameter, and the description explains both the parameter and the return shape. The presence of an output schema reduces the need for detailed return documentation. Minor missing details like sorting or pagination are not critical for this kind of list tool.

  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?

  Input schema coverage is 0%, but the description compensates by explaining include_read as 'Whether to include already-read notifications' and notes the default. For a single boolean parameter, this is sufficient semantic clarification.

  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 and resource: 'Get patient portal notifications.' This is specific and distinct from sibling tools like get_clinical_document, list_invoices, and list_appointments, so an agent can identify the right tool without confusion.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The resource name implies when to use the tool, but the description does not explicitly discuss usage context, exclusions, or alternatives. Sibling tools are unrelated enough that no conflict is likely, but there is no direct 'when to use' guidance beyond the name itself.

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

• get_invoiceA
  4.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It discloses the key side effect—the PDF is downloaded and saved—and the return value, but it omits possible auth requirements, overwrite behavior, file location, and error handling.

  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 compact, front-loaded, and uses a clear Args/Returns structure. Every sentence earns its place without 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 one-parameter download tool, it covers the input source, expected format, and return value. It could becomplete with error-case or file-location detail, but nothing critical is missing for normal use.

  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?

  The schema only provides a title and type, while the description adds crucial meaning: the parameter is the paymentNumber returned by list_invoices, with concrete examples. This makes correct invocation much easier.

  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 a specific verb and resource: 'Download a specific invoice PDF by payment number.' This clearly distinguishes it from list_invoices and other document-focused siblings like get_prescription.

  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 tells the agent that payment_number should come from list_invoices, effectively routing the workflow: call list_invoices first, then get_invoice. It does not explicitly state when not to use it, but the context is clear for this narrow task.

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

• list_past_appointmentsA
  4.3/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the burder of behavioral disclosure. It does state that the tool returns a list of dicts with a set of keys, which is useful, but it does not disclose ordering, pagination, status filtering, or side-effect behavior. This is adequate but not rich.

  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 very short and front-loaded: it states the purpose and date range in the first sentence, then gives the output shape. Every sentence earns its place with no filler.

  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 list tool with an output schema present, the description is complete: it defines the time window and the key fields returned. The agent can decide whether to call the tool and know what to expect. No further details are necessary.

  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 has zero parameters, so the baseline is 4 and there is nothing for the description to add about parameter semantics. The no-parameter expectation is consistent with the simple list behavior.

  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 a specific verb and resource: 'List all past appointments' with an explicit date range. The word 'past' distinguishes it from the sibling list_appointments, so an agent can tell them apart even 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?

  The description gives a clear context for use: past appointments from 2000-01-01 to today. It does not explicitly name alternatives or state when-not-to-use, but the scope is unambiguous enough that an agent can infer when this tool is appropriate.

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

• get_prescriptionA
  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 burden. It discloses that the tool downloads a PDF, saves it, and returns the file path. It does not cover error cases, file overwrite behavior, or authentication, but the core behavior is clearly communicated.

  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 compact and front-loaded with the action, followed by a short parameter explanation and return value. Every sentence serves a clear purpose with no 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?

  For a one-parameter download tool, the description fully explains the input source and the output behavior. It could mention file naming or local persistence details, but the essential call is completely specified and the output schema likely covers return structure.

  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 only provides the parameter name and type string, with 0% description coverage. The description adds essential meaning by defining download_url as the field from list_prescriptions() output, effectively compensating for the schema gap.

  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 verb and resource: 'Download a prescription PDF', and ties it to the download_url from list_prescriptions(). This clearly differentiates it from listing prescriptions and from parse_prescription, so an agent can immediately identify its 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?

  Explicitly tells the agent that download_url comes from list_prescriptions() output, which provides clear usage context. It does not mention when not to use the tool or name alternatives, but the instruction is sufficient for a straightforward downloader.

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

• parse_prescriptionA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the internal process (extract text, send to Ollama, structured extraction) and the vision-mode fallback for image-based PDFs. It also explicitly lists the return structure, which is valuable since there is no output schema. Minor gaps remain, such as error handling or the need for Ollama to be running, but the core behavior is 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?

  The description opens with a concise summary, then uses clear Args and Returns sections. Every sentence earns its place—the workflow context, parameter details, and return fields are all directly useful. There is no redundancy or filler.

  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 there is no output schema, the detailed Returns section is essential and fully provided. The description also includes workflow context (downloaded PDF from get_prescription) and the fallback mechanism. It does not mention potential failure modes (e.g., Ollama unavailable, invalid file), but the essential information for invoking and interpreting the tool is present.

  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 only defines file_path as a required string and model as a string with default. The description adds meaning beyond the schema: file_path is the path from get_prescription, and model selection depends on the PDF type (default llama3.2, vision model for image-based PDFs). This gives an agent practical guidance for setting 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?

  States a specific verb ('Parse'), resource ('downloaded prescription PDF'), and method ('local Ollama model'). This clearly distinguishes it from sibling tools like get_prescription and list_prescriptions, which retrieve documents rather than extract structured data. The one-sentence summary is unambiguous and immediately conveys the tool's 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?

  Explicitly links file_path to 'get_prescription', establishing the intended workflow order. It also gives model-selection guidance, advising a vision model for image-based PDFs. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to decide correctly.

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

• get_clinical_documentA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden of behavioral disclosure. It states that the tool downloads a PDF and, importantly, returns the file path where it was saved—a side effect an agent needs to know. It doesn't cover error behavior or file cleanup, but the key download-and-save behavior is 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?

  The description is compact and front-loaded: purpose first, then parameter explanation, then return value. Every sentence earns its place, and there is no redundant boilerplate.

  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 single-parameter download tool, the description covers the necessary call context: what it does, where the ID comes from, and what it returns. The main omission is any mention of failure modes or authorization requirements, which are not critical for a straightforward download but would make it fully complete.

  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?

  Schema description coverage is 0%, so the description must fully explain the parameter. It does: doc_id is defined as 'The document ID from list_clinical_documents' with an example format ('12345'). This is exactly the kind of semantic enrichment the schema lacks.

  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 ('Download'), a specific resource ('clinical document PDF'), and a clear discriminator ('by its ID'). It immediately distinguishes this tool from list_clinical_documents (listing vs. downloading) and from other get_* siblings (prescriptions, invoices).

  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 the doc_id comes from list_clinical_documents, establishing the workflow prerequisite (list first, then download). It does not name alternative tools to avoid, but the source guidance and tool name make the intended context clear.

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