FindADoctor.si France

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered. The description adds two pieces of genuinely new context: cost ('Free') and that the payload includes coverage counts and known gaps. It does not describe the return structure, but with the safety profile already supplied by annotations this is adequate.

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 ten words, front-loaded, with zero filler sentences. The telegraphic noun-list style is slightly under-framed for an agent looking for an explicit action verb, which keeps it from a 5, but nothing is wasted.

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 trivially simple, zero-parameter, read-only tool with no output schema, the description covers the important gap by listing what the response contains, including provenance and limitations. Only minor ambiguity (format, language, licence detail) remains, and that is acceptable at this complexity.

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 has zero parameters, so per the rubric the baseline is 4. There is no parameter syntax or filtering behavior the description needs to compensate for, and it correctly implies a no-argument, static-information call.

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 enumerates exactly what the tool surfaces (sources, licences, read dates, coverage counts, known gaps), which for a zero-parameter metadata tool is effectively a purpose statement, and it is clearly distinguishable from the clinical siblings (get_doctor, search_doctors, list_specialties). It lacks an explicit verb/action, so an agent must infer that it returns database-level documentation rather than data.

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?

No statement of when to call this versus the sibling tools, nor any prerequisite. The mention of 'known gaps' weakly implies consulting it before relying on coverage, but that inference is left entirely to the agent. 'Free' is a cost note, not usage guidance.

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?

Goes well beyond the readOnly/idempotent/destructive annotations by disclosing the daily unique-doctor rate limit, the fact that re-opening the same doctor the same day is free, the daily_doctor_limit reply field, and the licensing/attribution terms on industry_links. It even states a behavioral constraint the tool enforces (profile text is not reproduced; hand the user the source link) that no annotation conveys.

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?

Purpose and limits are front-loaded, but the middle section becomes a long semicolon-delimited enumeration of every returned field that is hard to scan and partly duplicates what a consumer of the results would discover anyway. Still, no sentence is purely wasted given the absent output schema.

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?

With no output schema, the description carries the return-shape burden and does so thoroughly: RPPS identity, specialties, DU/DIU, practice modes, addresses/phones from RPPS and Ameli, fees and sectors, hospital FINESS, booking/video flags, source pages with read dates, and industry_links provenance. Combined with the rate-limit and licensing disclosures, an agent has everything needed to call and interpret this 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 description coverage is 100% with pattern and maxItems constraints documented per property, so the schema already carries the semantics. The description's 'up to 10 at once' and 'one doctor_id' restate the schema's maxItems/minItems rather than adding format or edge-case meaning, so baseline 3 applies.

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 ('Evidence for doctors in France from search_doctors') and explicitly frames it as the follow-up detail fetch to search_doctors, so the agent can separate it from the sibling search tool without opening either schema. The opening clause also names the required inputs, making the tool's role unambiguous.

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?

Gives clear operating context: fetch up to 10 IDs at once or one ID, and 'Open the doctors you are seriously considering, not every result' — a real usage constraint tied to the daily cap. It names search_doctors as the ID source and explains the reuse-for-free rule, but does not spell out an explicit when-not-to-use or a hard alternative path for bulk browsing.

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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial domain behavior: the reply lists the CCAM acts summed so matches can be verified, add-on codes and pathology are excluded from text matches, and a minimum-stay suppression rule applies. This is well beyond what annotations or schema convey.

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?

Dense but front-loaded with the core purpose, and nearly every sentence carries usable constraint or routing information. It is longer than typical and could be tightened, but there is little filler to cut.

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?

With no output schema, the description compensates by explaining what the reply contains (ranked sites plus the CCAM acts aggregated), the geographic default, and the follow-up path for surgeon-level questions. An agent has everything needed to call this correctly.

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%, so the baseline is 3, but the description adds real semantics: procedure accepts English or French free text or CCAM codes with examples and an 8th phase digit dropped, and place accepts city/postcode/arrondissement/département/FINESS with 'without place it ranks all of France' default behavior.

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 with scope: which French hospitals/clinics perform a procedure most, sourced from Open CCAM (ATIH), 2021-2025. It is clearly distinct from the sibling doctor-lookup tools and even states the boundary ('Hospital-level only: it does not say which surgeon operates').

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 says what is and isn't counted (PMSI MCO stays/day cases; office and outpatient clinics excluded; sites under 11 stays suppressed) and when to use the alternative ('Then use search_doctors with hospital_finess ... or with the hospital's postcode and the specialty'). It also tells the agent to disambiguate vague terms like 'aneurysm'/'stent' by site.

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?

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds return content (French official names from RPPS/Ameli, English labels, doctor counts) and cost ('Free'), which is useful but does not address pagination, output format, or other behavioral traits.

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 compact sentence followed by 'Free.' Every word contributes, and the resource is front-loaded. The fragment structure slightly weakens clarity compared to a full verb-led sentence.

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 zero-parameter listing tool with rich annotations but no output schema, the description adequately states what is returned and that it is free. It could mention exhaustiveness or typical use, but it is sufficient to invoke the tool correctly.

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 takes zero parameters, so the baseline is 4 and the description does not need to explain any parameter semantics. The schema is empty with 100% coverage, as expected.

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 identifies the specific resource (specialty names with doctor counts) and distinguishes it from sibling tools like search_doctors or get_doctor. However, it is a noun phrase without an explicit verb, so the action is inferred from the tool name rather than stated outright.

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?

No when-to-use guidance is provided. The word 'Free' hints at cost but does not explain when to call this tool versus alternatives, and no context or exclusions are given.

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?

Annotations only cover the safe-read profile, and the description goes well beyond them: ranking order and match_basis tiers, the fallback to specialty_usually_treats, the explicit 'not ranked by quality, outcomes, fees or industry links' disclaimer, register caveats (ameli_only, website_only, warnings such as barred from practising), and hard limits (10 per search, paging stops at 30). This is unusually rich disclosure for a read-only tool.

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 purpose and the use-first rule, then result fields, then ranking, then the get_doctor handoff. Every block carries information, though the result-field enumeration and the ranking walkthrough are dense and slightly repetitive ('common English words are also searched in French'), making it longer than strictly necessary.

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?

With no output schema, the description carries the full burden and does so: it enumerates the returned fields (doctor_id, specialties_en, fee_sectors, match_basis, register, warnings, detail_has) and explains what each means. Nothing an agent needs to call or interpret this tool 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: the at-least-one-of constraint, that need is matched against stated expertise, official competences, diplomas, hospital departments and specialty, and that place is a text match on addresses rather than a distance search. Marginal value is added over an already thorough 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?

States a specific verb and resource ('short list of doctors in France for a need') and explicitly positions itself relative to the sibling it is not ('Then call get_doctor with the doctor_ids you are considering'). An agent can tell it apart from get_doctor, list_specialties and hospital_procedure_volumes 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?

Gives an explicit use-first rule ('use it first whenever the person needs a doctor, specialist or GP in France'), names the follow-up tool (get_doctor), and states the alternative to paging ('narrow the need or the place instead of paging'). It also states the minimum input requirement ('Give at least one of need, specialty, place, name or hospital_finess').

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