DoctoFam Medical Clinic

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered externally. The description adds the single-practice scope and enumerates return fields, but says nothing about failure modes, permissions, or behavior when the practice id is unknown.

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?

Three compact sentences, trigger condition front-loaded, no filler. The return-field enumeration is somewhat redundant given an output schema exists, so it is efficient but not perfectly trimmed.

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 single-parameter read tool with rich annotations and a declared output schema, the description covers when to use it and what it is not for. The remaining gap is un-named alternatives for the excluded case.

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% for the sole clinicId parameter, including its 24-hex-character pattern, so the schema carries full burden. The description adds no format or lookup guidance beyond what the schema states.

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 ('Get medical practice details') and scopes it to a single practice's setup, which separates it from list_clinics. The exclusion 'Not for free consultation times' gestures at get_clinic_availability but never names it, so sibling differentiation is partial.

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 a concrete trigger ('when someone asks about one medical practice's setup, such as its currency, language or timezone') plus one explicit negative case. It stops short of naming the alternative tool an agent should use instead.

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 the read-only/idempotent/non-destructive safety profile, so the description rightly focuses on behavior it alone can convey: day-grouped slots, the 7-day/100-slot caps, and the privacy guarantee that no patient or doctor details are returned. The only minor gap is that the caps are stated as fixed without noting what happens if openings exceed them.

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?

Three sentences, no filler, with the trigger condition front-loaded, the return shape and limits in the middle, and the exclusion last. Every sentence earns its place.

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?

An output schema exists so return-value internals need not be spelled out, yet the description still summarizes the shape (start/end per slot, grouped by day) and the caps. Combined with annotations, nothing needed to call the tool 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?

There is only one parameter (clinicId) and schema description coverage is 100%, so the schema already fully documents its format and pattern. The description adds no new meaning about the parameter, so the baseline of 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 and resource (find/return free appointment or consultation slots for a practice) and scopes it clearly as availability lookup. An agent can distinguish it from booking flows and the list_* siblings without opening the 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?

The opening clause gives an explicit trigger ('when someone asks when their doctor's practice has free appointment times') and the closing clause excludes the alternative action ('Not for booking a visit'). Both when-to-use and when-not are covered.

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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral detail the annotations cannot: UTC-day bucketing, status-agnostic counting, a 7-day default with a 31-day maximum, and a silent truncation cap at 100 counts. It does not, however, explain what happens when the cap is hit (partial day? error? omitted days).

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?

Three sentences, each doing distinct work: usage trigger first, then output/behavior bounds, then exclusions. No filler and the most decision-relevant information (when to reach for it) is front-loaded.

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?

An output schema exists, so return shape need not be described. For a three-parameter read with full schema coverage, the description supplies everything an agent needs to select and call it correctly: the trigger, the date-range bounds and the sibling-excluding boundaries.

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 startTime, endTime and clinicId are all documented in the schema itself; the baseline is 3. The description restates the default window and the 31-day ceiling, which is consistent with the schema but adds no syntax or format information beyond it.

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 ('Returns appointment counts per UTC day for one practice') and fixes the scope to a single practice and a bounded date window. It is readily distinguishable from siblings like list_calendar_events or show_clinic_overview, which return events or aggregate summaries rather than per-day counts.

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?

Opens with an explicit trigger ('Use this when someone asks how busy their medical practice is or how many patient visits are booked each day') and closes with an explicit exclusion ('Not for counting cancellations or seeing which patients are booked'). Both the when and the when-not are handed to the agent with no inference required.

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 declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuine behavioral context by stating the fallback: it returns the default Free plan when none is active, which an agent would not infer from annotations or schema.

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?

Three sentences, no waste, and the usage trigger is front-loaded before the return description and the exclusion. Every clause earns its place.

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?

An output schema exists so return values need not be enumerated, and the annotations cover the safety/idempotency profile. The description supplies the remaining missing piece (the Free-plan fallback), making the definition complete for a single-parameter read 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?

There is one parameter with 100% schema description coverage, including a hex pattern, so the schema fully documents it. The description adds no extra meaning about clinicId beyond what the schema provides, which is the expected baseline-3 case when structured data already carries the load.

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?

Specific verb+resource: retrieves a practice's DoctoFam plan, its status, billing frequency and plan caps. It also explicitly carves out sibling territory ('Not for invoices or amounts billed'), so the agent can distinguish it from billing-related tools 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?

Strong when-to-use triggers are given ('when someone asks which plan a practice is on, whether it is active, or how many appointments, patients, rooms or users it allows'), plus one exclusion for invoices. It does not name a specific alternative tool for the billing case, so it stops short of full routing 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?

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the safety profile is covered. The description adds useful substance beyond that: what fields come back (start, end, all-day flag, scope, type) and the notable absence of titles/notes. It does not mention pagination mechanics, though the cursor param implies it.

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?

Three sentences, front-loaded with the usage trigger, followed by return shape and the exclusion. No filler or restatement of the tool name.

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 0 required params, a 100%-documented schema, rich annotations and an output schema, the remaining burden on the description is trigger and scope — both supplied. An agent has everything needed to select and call it.

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 all five parameters (limit, cursor, startTime, endTime, clinicId) are already documented in the schema. The description adds no parameter-level syntax or defaults beyond that, so the 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 and resource (list calendar closures/holidays/blocked time) and names the sibling domain it is not for (patient appointments). The title and description together let an agent distinguish it from appointment-related siblings without opening the 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 trigger ('Use this when someone asks when their medical practice is closed, or when a doctor or room is blocked...') and an explicit exclusion ('Not for patient appointments'). Both when-to-use and when-not are stated outright.

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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the returned field set (id, name, currency, default language, timezone) and the default page size of 20.

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?

Three tightly packed sentences: trigger first, then return contents, then exclusion. No filler and nothing that could be cut without losing information.

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?

A read-only listing tool with a full output schema, complete parameter documentation, and an explicit sibling exclusion. Everything an agent needs to select and correctly invoke it is present.

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 both limit and cursor are already documented with ranges and meaning. The description only restates the 20-per-page default, adding nothing about cursor semantics or pagination chaining. 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 (list) and resource (medical practices/doctor's offices) and enumerates the returned fields. It also explicitly carves out what it is not for (finding a patient or a visit), so an agent can separate it from get_clinic and the other siblings 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.

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

Gives an explicit trigger ('Use this when someone asks which medical practices...or a practice's id is needed') and an explicit exclusion ('Not for finding a patient or a visit'). When-to-use and when-not-to-use are both present.

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 establish readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds real behavioral context beyond that: results are alphabetical, paginated at 50 per page by default, and each entry carries name, price and last edit time.

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?

Three tight sentences: trigger first, return shape and pagination second, exclusion third. Every sentence carries new information and there is no 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?

An output schema exists, so return details need not be enumerated, yet the description still characterizes the payload usefully. Pagination, ordering and scoping are all covered between the description and the schema, leaving no gap an agent would need to guess at.

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 limit, cursor and clinicId are already documented in the schema itself. The description restates the 50-per-page default but adds nothing about clinicId scoping or cursor semantics beyond what the schema says. Baseline 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 states a concrete resource (catalog service names with price and last edit time) and frames the trigger scenario ('what their medical practice charges for a consultation, check-up, vaccination or other service'). It also rules out the most likely confusion (patient medical history). It stops short of naming which sibling tool to use instead when the request is clinical rather than price-related.

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?

Explicit positive trigger ('Use this when someone asks what their medical practice charges...') plus an explicit exclusion ('Not for a patient's medical history or the care they received'). No alternative tool is named for the excluded case, so the routing is clear but not fully closed.

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 declare readOnly, idempotent, non-destructive, closed-world behavior, so the description only needs to add context beyond that. It usefully discloses the result cap (up to 100 names) and the deliberate omission of contact details and roles, which shapes how the agent should interpret the response.

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, zero filler, with the usage trigger front-loaded and the exclusion trailing. Every clause earns its place.

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?

Output schema exists, so return-value documentation is not required, yet the description still summarizes the shape (display names, no contact details or roles) and the 100-item cap. Nothing an agent needs to call this 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 clinicId format and required status are already documented in the schema. The description's 'for one practice' only loosely reinforces the scoping parameter, adding no syntax or format detail beyond the schema. 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 (list) and resource (doctors, nurses, assistants who take bookings), and scopes it to a single practice. An agent can distinguish this from sibling tools like list_rooms or get_clinic_availability without opening a 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 frames the trigger ('when someone asks which doctors, nurses or assistants patients can book') and adds a clear exclusion ('Not for staff holidays or sick days'). It does not name an alternative sibling tool for the excluded case, so it stops just short of full routing 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?

Annotations already declare read-only, idempotent, non-destructive behavior, so the description's added value is the result shape and ordering: alphabetical results, 50-per-page default paging, and last-edit-time metadata. It does not discuss auth requirements or what happens on an invalid/stale cursor, which is a minor remaining gap.

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?

Three tight sentences: use-case first, result/paging behavior second, exclusions last. No filler and the routing constraint is front-loaded.

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 an output schema present, return values needn't be detailed, and the description still summarizes them. For a simple read-only list tool with full schema coverage and safety annotations, nothing an agent needs to call 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 limit, cursor, and clinicId are already documented in the schema. The description only restates the page-size default ('50 per page by default'), adding nothing beyond the schema's own parameter descriptions. 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?

The description names a specific verb and resource (list consultation/exam rooms for a practice) and further specifies the payload ('room names with last edit time'). The closing exclusion clause separates it from schedule-oriented siblings such as get_clinic_schedule_summary.

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 states the triggering condition explicitly ('Use this when someone asks which consultation or exam rooms their medical practice has') and gives negative guidance ('Not for room schedules or which patient uses a room'), routing the agent away from the schedule and patient-assignment tools.

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 declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the exact scope of the returned card (7-day window, cap of 12 service prices) and the important caveat 'no patient or clinical data', which bounds what an agent may claim from the result.

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 tight sentences, front-loaded with the trigger and then the return scope; no filler. The enumerated return list is somewhat long given an output schema exists, keeping it just short of maximal conciseness.

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 single-parameter read tool with full schema coverage, annotations and an output schema, the description supplies everything an agent needs: when to reach for it, what the card contains, how far ahead it looks, and the explicit exclusion of patient/clinical data. No material gap remains.

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% and the single clinicId parameter is fully documented with its hex pattern, so the schema carries the burden. The description adds only the implicit notion of a single practice; it contributes no extra syntax or format meaning beyond the schema. Baseline 3.

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 names a specific verb and resource ('quick overview or dashboard of one medical practice') and enumerates the payload: practice details, 7-day appointment counts, staff/room counts, booking slots, up to 12 service prices, and plan. It also carves out its boundary ('Not for a single patient or visit'), so an agent can distinguish it from get_clinic_schedule_summary and list_clinics 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.

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

'Use this when someone wants a quick overview or dashboard of one medical practice' gives an explicit trigger, and 'Not for a single patient or visit' supplies an exclusion. It stops short of naming which sibling to use for those adjacent needs, so it is strong but not fully prescriptive.

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