VetClinic.info — Veterinary Specialty Directory

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

With no annotations, the description carries the full burden and does substantial work: it discloses the return shape (low–high range plus an 'assumptions' field), determinism on identical inputs, the defaulting behavior for omitted inputs, and that PII fields are actively rejected. Missing are error semantics for an unknown procedure_slug and confirmation of whether rejected PII fields error or are silently ignored.

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

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

Front-loaded with the one-line purpose, then behaviors in order of importance (return, requirements, defaults, determinism, exclusions). Every sentence carries information. The 'no zip → the state, else the national range' parenthetical is compressed but readable; no filler sentences.

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

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

For a 5-parameter tool with a nested object, no output schema, and no annotations, the description covers the result shape, defaulting rules, determinism, and the PII exclusion. Gaps are minor: failure behavior for an invalid slug and whether output is paginated/cached are unstated, but 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.

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, but the description adds real semantics beyond it: the fallback chain 'no zip → the state, else the national range' is a resolution order not spelled out in the schema, and it clarifies that required-only is sufficient. It adds value rather than restating field descriptions.

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

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

States a specific verb+resource ('cost estimate' returning a $low–$high range) and immediately scopes it as anonymous, computed from regional + case factors. This clearly separates it from quote_for_case, which is named as the non-anonymous path. An agent can route correctly without opening any schema.

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

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

Explicitly names the alternative and the condition that selects it: 'PII fields are rejected — use quote_for_case for the PII path.' It also clarifies that only procedure_slug is required and what happens to omitted fields. It does not, however, cover its relationship to the other siblings (e.g., when to look up a procedure first vs. just estimating).

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool returns a ranked list and is a convenience wrapper, which implies a read-only operation. However, it does not explicitly state that it has no side effects, nor does it mention pagination or other behavioral details that could be relevant.

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

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

The description is two concise sentences with no unnecessary words. It front-loads the key concept ('Convenience') and immediately explains the tool's behavior, making it easy to scan.

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

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

Given the simple schema (3 params, no output schema) and the presence of sibling tools, the description adequately explains the tool's purpose and relationship to get_procedure. It does not cover the limit parameter's behavior or return format, but those are inferable from the schema and the 'list' wording.

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

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

Schema description coverage is 67% (procedure and state have descriptions; limit does not). The description adds only marginal value by clarifying that the result is filtered by state, but it does not elaborate on the 'slug' format or explain the limit parameter beyond what the schema already provides.

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

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

The description clearly states the tool's function: it combines get_procedure with a state filter and returns a ranked specialist finder list. This specific verb ('Returns') and resource ('ranked specialist finder list') clearly distinguish it from sibling tools like get_procedure.

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

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

The 'Convenience' framing implies this tool should be used when you need both a procedure lookup and a state filter together, rather than calling get_procedure separately. However, it does not explicitly state when not to use this tool or mention alternative approaches, leaving some room for interpretation.

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

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

With no annotations, the description carries the transparency burden. It discloses the return contents ('credentials, inline reviews, procedures performed, contact action, canonical URL'), which is useful, but it does not explicitly state read-only behavior, error handling, authentication requirements, or any side effects. It is a mild positive but not a full disclosure.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource, followed by a concise list of contents. Every word earns its place; no filler or repetition.

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

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

For a simple fetch tool with 100% schema coverage and no output schema, the description adequately covers what the tool does and what it returns. It could explicitly mention error behavior or fallbacks, but given the tool's simplicity, the current description is sufficiently complete.

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

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

The schema already has 100% coverage, with each parameter described and the slug explanation calling out that slugs are unique per city. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Fetch') and resource ('a single clinic's full record'), clearly distinguishing it from sibling tools like search_clinics (which searches) and get_procedure (which fetches a procedure). It also enumerates the record's contents (credentials, reviews, procedures, contact action, canonical URL), making the purpose unmistakable.

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

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

The description implies the tool is for fetching a single clinic when you know its slug, but it does not explicitly state when to use this over alternatives like search_clinics, nor does it mention exclusions or prerequisites. The schema provides helpful disambiguation guidance (pairing slug with city and state), but the description itself lacks direct usage direction.

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

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

No annotations are provided, so the description carries the full burden. It discloses conditional behavior (state triggers a clinic finder) and the article's contents. However, it does not explicitly state whether the tool is read-only, error behavior, or any limitations. 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.

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

Two sentences, front-loaded with the main purpose. Every part is meaningful, no fluff. Excellent structure.

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

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

For a relatively simple fetch tool with two parameters, the description is complete enough: it lists the article sections and the conditional clinic finder. Minor gaps include error handling and invalid input behavior, but these are not critical for a read-only retrieval tool.

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

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

Schema coverage is 100% for both parameters. The description adds meaning by explaining that providing state triggers an additional 'ranked clinic finder' sub-component, which is not fully conveyed by the schema's 'pre-filter the finder.' This adds semantic value beyond the schema.

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

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

The description clearly identifies the tool's purpose: fetching a procedure article with specific sections (cost band, contraindications, emergency signals, FAQ, citations). It distinguishes itself from sibling tools like estimate_procedure_cost, get_clinic, and find_specialists_by_procedure by focusing on the article retrieval.

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

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

The description implies usage context: use when you need a procedure article. It mentions conditional behavior with state (clinic finder) but does not explicitly state when not to use it or mention alternatives like search_clinics. Clear context, but no exclusions.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the live-article filter and the exact returned fields, which adds meaningful context beyond a generic 'list procedures'. It does not mention pagination, ordering, or explicit read-only status, but for a no-parameter list tool the behavior is clear and non-destructive.

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

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

The description is a single sentence that leads with the core concept ('Published procedure catalog') followed by the specific return fields and filtering condition. Every word earns its place with no redundancy or filler.

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

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

For a simple list tool with no parameters and no output schema, the description is complete. It specifies the scope (published, live articles), the exact fields returned, and the coverage ('every procedure'). It provides all necessary information for an agent to invoke the tool and interpret results.

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

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

The tool has zero parameters, so the description rightly focuses on output semantics. Baseline for zero-parameter tools is 4. No parameter explanations are needed, and the schema (empty) confirms no inputs.

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

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

The description clearly states the tool returns a published procedure catalog with specific fields (slug, display_name, also_known_as, specialty_slug) for every procedure with a live article. This is a specific verb+resource combination that is distinct from siblings like get_procedure (single procedure) and list_specialties (specialties).

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

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

The description implies the tool is for listing all procedures but doesn't explicitly compare to alternatives like get_procedure or search_clinics. It provides context (published catalog, live articles) but lacks explicit when-to-use or when-not-to-use guidance. Usage is implied rather than stated.

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

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

With no annotations, the description carries the burden and largely meets it by describing output fields and the 'when applicable' qualifier for sameAs. It implies a read-only operation via 'Returns' and defines the scope as a 'closed-set enum', but it does not explicitly confirm no side effects or other behavioral details.

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

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

Two sentences: the first defines the tool's essence and return structure; the second gives actionable usage context. Every phrase earns its place with no padding or redundancy.

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

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

For a no-parameter, no-output-schema tool, the description fully covers what the tool returns, the nature of the data ('closed-set enum'), and when to invoke it. It is self-sufficient and leaves no major gaps for an agent to misuse.

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

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

The tool has zero parameters, so by the rubric baseline is 4. The description adds no parameter explanation because none are needed.

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

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

The description states a specific verb ('Returns') and resource ('specialty slugs'), clearly identifying it as a reference list tool. It distinguishes itself from search_clinics by framing itself as a prerequisite mapping step, and it enumerates exact return fields (slug, display_name, credentialing_board.sameAs).

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

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

Provides explicit guidance: 'Always call this before search_clinics if uncertain about specialty mapping.' This gives a clear when-to-use scenario, though it does not mention alternatives beyond search_clinics or explicitly state when not to use it.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses the composite dual-mode behavior, the X-Agent-Attribution auth requirement when PII is supplied, the side effects (routing to a specialist, holding for matching, receipt email), and the returned status value. It omits error/rate-limit behavior and any statement about cost or reversibility of the submitted case.

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

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

Roughly four sentences, front-loaded with the always-true behavior before the conditional branch, so an agent skimming gets the core contract first. The prose is terse and jargon-heavy ('accepted on arrival', 'held while we match one'), but every clause conveys a distinct behavior.

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

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

For a 9-parameter composite tool with no annotations and no output schema, the description covers the essential decision logic and the one return value that matters (status='estimate_only'). It leaves the shape of the estimate payload and failure modes unstated, which is a modest gap given the missing output schema.

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

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

Schema description coverage is 89%, so the baseline is 3, but the description adds real semantic weight by framing owner_email as the switch between estimate-only and case-submission modes and by tying routing to locality fields. It also confirms case_factors mirrors the sibling tool's shape, giving the agent confidence the two are interchangeable.

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

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

The description opens with the specific nature of the tool ('Composite tool. Always computes an estimate') and then spells out the two distinct behaviors (estimate-only vs. full case submission with routing and receipt). It explicitly distinguishes itself from the sibling estimate_procedure_cost by stating the exact condition under which the two are identical.

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

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

It gives a clear conditional trigger: include owner_email to accept the case on arrival and get routing/receipt behavior; omit it and the tool collapses to estimate_procedure_cost. It names the alternative and the pivot parameter, though it never says outright 'use estimate_procedure_cost when you have no PII', leaving a small inference step.

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

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

With no annotations the description carries the full burden, and it does disclose real behavior: results are ranked with promoted listings first, and the ambiguous-city case returns needs_state: true with zero clinics plus a candidates array containing the exact next_call arguments. It omits auth requirements, rate limits, and pagination behavior tied to `limit`, which keeps it short of a 5.

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

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

The purpose is front-loaded in sentence one, and the denser final sentence is justified because it documents the non-obvious error path. It is slightly heavy for a four-parameter lookup, but no sentence is filler.

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

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

There is no output schema, so the description must describe return values, and it does: the ranked shortlist fields, the promoted-listing ordering, and the exact degraded-response shape when the city is ambiguous. An agent has everything needed to call it and recover from the one failure mode.

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

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

Schema coverage is 75%, so the baseline is around 3, but the description adds functional meaning the schema only hints at: the concrete consequence of omitting `state` (cross-state resolution, the needs_state contract, and the shape of the recovery payload). `limit` remains unexplained in both places, which is a minor gap.

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

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

The first sentence states a specific verb (find) plus the resource (veterinary specialty clinics) and the two required dimensions (city + specialty). It then enumerates the return payload, which cleanly separates it from siblings like get_clinic (single record) and find_specialists_by_procedure. An agent can route to it without opening any schema.

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

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

It gives explicit conditional guidance for the `state` parameter (omit it unless you know it; the result tells you when disambiguation is required) and even points at the follow-up call to make. It does not, however, contrast itself against siblings such as find_specialists_by_procedure or get_clinic, so the when-to-prefer-this-tool guidance is incomplete.

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