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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description layers on non-obvious behavior: the auth/SMS requirement for booking, the fact that office-type doctors lack a center page, and that returned entries carry `consultation_id` and doctor hash ids that feed specific sibling tools.

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 resource's contents, then the practical routing notes. Dense and slightly telegraphic in the opening enumeration, but nearly every clause carries information the agent needs to chain calls.

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?

Although an output schema exists, the description still highlights the output fields that matter for orchestration (consultation_id, doctor hash ids, earliest free slot), plus the exclusions and prerequisite. Nothing needed to select or call 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% and both parameters are fully documented there, including the hash-or-URL format and the default/cap on `doctors`. The description adds only indirect cues (mentions of hash ids and consultation ids), 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?

The description names the resource (a center's page) and enumerates exactly what it returns: address, coordinates, departments, services, insurances, attributes, opening hours, lab admission rules, bookable services and doctors. It explicitly carves out what it is NOT for ('Doctor private offices (type office) have no center page: use dt_doctor'), cleanly separating it from the sibling.

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 alternatives and conditions: use dt_doctor for office-type practitioners, and the follow-up chain is spelled out ('Next: dt_free_slots, dt_doctor, dt_reviews(of="center")'). It also surfaces a prerequisite the agent must relay to the user (booking needs an SMS login).

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, open-world, non-destructive, so the safety profile is handled. The description adds genuinely new behavioral detail beyond them: default ordering ('main cities first'), that `speciality` mode returns doctor counts, and the important caveat that counts cover main cities only while searches may surface doctors elsewhere.

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 short sentences, front-loaded with the tool's core purpose and output meaning, followed by mode behavior and next steps. No filler; every clause carries actionable 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?

With an output schema present, the description needn't describe return values, and it still covers purpose, mode-dependent behavior, the key caveat, and chaining to sibling tools. 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 all three parameters are already documented and the baseline is 3. The description goes beyond the schema by explaining the semantics of `speciality` (returns only cities having such doctors, with counts, main cities only) and the default no-argument behavior of `limit`/`query`.

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 a city's slug ... and numeric id') and even names the downstream consumers of each output field (search filters, dt_suggest). This clearly distinguishes it from siblings like dt_suggest and dt_neighborhoods without needing to open 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 explicit behavioral modes (no arguments vs. with `speciality`) and an explicit follow-up path: 'Next: dt_search_doctors(city=slug) or dt_neighborhoods.' It also warns that the speciality filter is incomplete because 'a search may still find doctors elsewhere.' It lacks an explicit when-not-to-use statement, so it falls just short of a 5.

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 the safe read-only, idempotent, open-world profile, so the description does not need to restate safety. It adds real behavioral context instead: `pay_online_now` is charged at booking and is usually 0 for office visits, `fee` means different things for office vs online visits, and booking requires an SMS-authenticated login. That is meaningful value beyond the annotations.

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

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

Front-loaded with the one-line purpose, then dense but purposeful field-level detail. Every clause carries information (fee semantics, time zone, booking prerequisite); it is long but not padded.

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?

Covers the return shape (services[], reviews summary, waiting time, conditions), the Tehran-time convention, the input chain into dt_free_slots, and the booking auth hurdle. An output schema exists so return-field prose is partly redundant, but the description is complete enough for an agent to call and use it 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 description coverage is 100% and the single `doctor` parameter is already fully documented in the schema (hash id vs full page URL, slug not resolvable). The description adds no parameter-level detail, 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 resource (a doctor's profile) and enumerates exactly what it returns: bookable services, price in Toman, and next free time. This clearly separates it from siblings like dt_search_doctors (discovery) and dt_center (facility profiles).

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 routes the agent forward: 'Next: dt_free_slots, dt_reviews', and notes the prerequisite that booking needs an SMS login on the site and the user must be given `url`. It stops short of stating when NOT to call it (e.g. to just find a doctor, use dt_search_doctors), so it is strong but not complete.

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 declare the safe-read profile (readOnly, idempotent, non-destructive), and the description goes beyond them by disclosing filtering behavior (only days with free times are returned, past times today are dropped), the timezone of returned HH:MM values (Tehran local), and the meaning/bound of `bookable_until` (~30 days ahead). It stops short of describing pagination or failure modes when a service has no availability.

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 core purpose and return shape are front-loaded in the first two sentences, with caveats and the booking note trailing. It is tight overall, though the SMS-login/URL sentence is slightly tangential to invoking this read tool.

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 and annotations covering safety, the description only needs to add the non-structured context it does provide: which days are omitted, timezone, text-consultation caveat, and the booking prerequisite. What is missing is minimal, mostly failure/no-availability behavior.

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 days/start_date/consultation_id are already documented in the schema, including examples and formats. The description adds contextual framing about timezone and the fact that times are start times (for phone/video, the call start), but supplies no syntax or default behavior 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?

The description names a specific verb+resource: 'Free appointment times of one service', and enumerates the service kinds (office visit, phone/video call, clinic offer, lab admission). Combined with the sibling names (dt_doctor, dt_offer, dt_center), an agent can tell this is the availability-lookup tool rather than a listing tool.

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 useful operating context — text consultations usually have no slots, and booking requires an SMS login on doctoreto.com — but it never states when to call this versus dt_doctor/dt_offer, nor the prerequisites that must hold before calling (e.g. needing a consultation_id already fetched). Usage is implied rather than directed.

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/openWorld, so the safety profile is covered. The description adds genuinely useful context beyond them: the scope disclaimer that output is general information rather than medical advice, and a preview of returned fields (title, link, publish date, summary) plus how text_chars changes the response. It does not discuss rate limits or result-ranking behavior, so it stops 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?

Two tight sentences, front-loaded with the resource and its scope, followed by the return fields and the disclaimer/alternative routing. Every clause earns its place; nothing is redundant padding.

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 read-only search tool with a full output schema and 100% parameter documentation, the description supplies exactly the missing pieces: intended use, output preview, disclaimer, and sibling routing. An agent has everything needed to invoke it 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 and the schema already documents all three parameters. The description adds a modest but real point beyond the schema: that the default response is a summary and that text_chars is the switch that turns on full article text, linking the parameter to the output shape.

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 (Search) and resource (Doctoreto's health magazine, ~5,000 articles) plus the intended subject matter (condition, test, treatment). It also gestures at the sibling boundary by naming dt_search_doctors for the adjacent need, so an agent can distinguish it 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 explicit when-to-use ('background on a condition, test or treatment'), explicit when-not ('General information only, not medical advice'), and names the alternative tool (dt_search_doctors) with the condition that selects it (for a diagnosis). Nothing is left to inference.

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, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely useful non-obvious context: the dataset is small (~84 insurers) and sparse in doctor listings, which materially affects how an agent should use the result. It does not cover pagination or result ordering, but the output schema exists to carry return shape.

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 short sentences, front-loaded with the core purpose and the downstream consumer before the caveat. Every sentence carries information — the id linkage, the corpus size, and the doctor/center distinction — with 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?

With rich annotations, a fully described single-parameter schema, and an output schema present, the description supplies everything else an agent needs: the tool's role in the doctor-search workflow, the approximate result size, and the data-sparsity caveat. Nothing material is missing for correct invocation.

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% — the single 'query' parameter is fully documented in the schema, including a Persian example ('تامین' or 'آتیه'). The description adds no additional syntax or matching-semantics detail (e.g., substring vs prefix matching), 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 ('List basic and supplementary insurers') and goes further by naming the exact consumer of the returned ids: dt_search_doctors(insurance_ids=...). An agent can distinguish this from sibling lookup tools like dt_specialities or dt_cities purely from the description.

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 context for use: the returned ids feed dt_search_doctors, and it warns that 'few doctors list insurances, so an insurance filter narrows a search a lot' — an important behavioral caveat about filter aggressiveness. It also routes center insurance lookups to dt_center. It stops short of explicitly stating when not to use it (e.g., when to prefer dt_specialities instead), so it falls just short of a 5.

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/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: results are ordered most-doctors-first, some entries are district groupings that double as filters, and nearby cities are included. It doesn't mention auth or rate limits, but the added content is meaningful.

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 with the core purpose front-loaded; the parenthetical examples and the follow-up usage tip earn their place. Minor structural awkwardness from the mixed prose/semicolon construction, 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?

With an output schema covering return values and annotations covering the safety profile, the description supplies purpose, ordering, filter semantics, and a next-step hint. It is complete enough for an agent to call correctly, with only explicit alternative-tool guidance 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. The description reinforces that a slug is the expected identifier but adds little about city, limit, query, or speciality semantics beyond what the schema already documents.

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 resource and scope: neighborhoods of a city plus nearby cities, each with a doctor count. It implies its distinction from dt_cities (which returns cities, not neighborhoods) and from dt_specialities, but doesn't name a sibling explicitly, so it stops just short of the top band.

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 downstream usage (feed the slug into dt_search_doctors(city=..., neighborhood=slug)) and one conditional (suggest a nearby city when the user's city has few doctors). However it never states when to choose this tool over alternatives like dt_cities, leaving tool selection to inference.

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/openWorld/no-destructive, so the safety profile is covered. The description adds real context beyond that: the authentication requirement for booking/payment and the instruction to surface `url` to the user, which an agent needs for the downstream flow.

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: the first front-loads the returned payload, the second carries the operational caveat. The long field enumeration is dense but earns its space by telling the agent what detail is available without opening the 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?

An output schema exists, so return values need not be explained, and the description instead points at the one output value that matters downstream (`consultation_id` for dt_free_slots). For a single-parameter read tool this is nearly complete; only explicit sibling routing is absent.

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% and the single parameter is fully documented in the schema (hash id, numeric id, or URL). The description adds no parameter syntax of its own, so the schema does the heavy lifting — 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?

The description states a specific resource (one clinic offer) and enumerates the fields returned — price, discount, deposit, provider, location, terms, capacity, variants — which clearly separates it from dt_search_offers. It never names the sibling explicitly, so differentiation is inferred rather than stated.

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?

There is an actionable workflow hint (booking/payment requires SMS login, hand the user `url`) and a cross-tool pointer (`consultation_id` feeds dt_free_slots), but no explicit when-to-use-this-vs-dt_search_offers guidance or prerequisites for the call itself.

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 safety profile, yet the description adds substantive traits: reviewer names are never returned (privacy), ordering differs by entity type, no server-side sort or filter exists, and pagination must be computed manually. These are real behavioral constraints an agent cannot infer from the 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?

Front-loaded with the return shape and its ordering rule, followed by the operational note and the sibling pointer. Slightly dense mid-sentence field listing keeps it from being maximally tight, but there is little waste.

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, the field enumeration is partly redundant, but the ordering rule, privacy note, and pagination math fill in gaps the structured fields do not cover. Adequate for an agent to call it 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 semantics the schema cannot: the `of` enum changes ordering behavior, and pagination is described as total/limit. Page and limit semantics otherwise remain with 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?

States the exact resource (patient reviews) for three target types and enumerates the returned fields, including ordering semantics ('doctors and centers newest first, offers oldest first'). It explicitly routes the summary use case to the sibling dt_doctor, so an agent can separate it from other dt_* lookups 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 concrete operational guidance: 'There is no sort or filter upstream: to find low ratings, page through (pages = total / limit)' and points to dt_doctor for aggregates. It doesn't state explicit exclusions or prerequisites, but the when-to-use context is clear.

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 safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description still adds real behavioral context: map searches sort by distance, dense areas truncate results and report the remainder via `more_in_area`, and insurance filtering is a dead end. It omits pagination depth/limits and any rate-limit or throttling behavior.

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 paragraphs, front-loaded with what is returned before the mechanics. The card-field enumeration is dense but each item maps to a real decision an agent makes (e.g. `id` as the dt_center input, `more_in_area` for truncation), so the sentences earn their 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?

With 14 optional filters, fast-follow sibling routing, and an output schema present, the definition is nearly self-sufficient — return-shape details are correctly delegated to the output schema. The remaining gap is that no guidance is given on combining filters (e.g. neighborhood requires city) or on paging through dense-area 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?

Schema description coverage is 100%, so the schema already documents all 14 parameters and a 3 is the baseline. The description adds only marginal filter semantics (near_lat/near_lon trigger a distance-sorted square search) and actually references an 'insurance filter' that does not exist as a parameter, which could mildly mislead rather than clarify.

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?

Opens with a specific verb and an enumerated resource list ('Find hospitals, clinics, infirmaries, laboratories, imaging centers and pharmacies with filters'), which immediately distinguishes it from the doctor-oriented sibling dt_search_doctors. The agent knows exactly what entity set this tool returns 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 concrete workflow routing ('Next: dt_center, dt_reviews(of="center")') and a clear negative rule ('Insurance filters have no effect upstream: check `insurances` in dt_center'). It does not, however, contrast itself with dt_search_doctors or explain when a city/neighborhood filter should be preferred over the map (near_lat/near_lon) mode, so the alternative-selection guidance stops short of explicit.

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 safety profile (readOnly, idempotent, openWorld, non-destructive), yet the description still adds real value: it discloses what each card contains, flags that the list's phone price differs from the booking page, and warns that online consultation prices are absent from cards. That is meaningful behavioral context beyond the structured fields.

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 the first sentence and the remaining clauses carry functional information (card contents, price caveat, next steps) rather than filler. It is somewhat dense and wraps across many lines, but each 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?

For a 14-parameter search tool with an output schema present, the description supplies the workflow chain, the pricing caveat, and the output card semantics. An agent has everything needed to invoke it correctly and to know what to do next.

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 schema already documents every parameter including defaults, enums, and slug sourcing. The description only reiterates the filter list and adds a brief note that near_lat/near_lon narrow to a point, so the 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 opens with a precise verb+resource ('Search doctors on Doctoreto') and enumerates the full filter surface (city, speciality, neighborhood, service tag, name, gender, insurance, visit type). This clearly separates it from the sibling search tools (dt_search_centers, dt_search_offers) which target different resources.

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 provides a workflow trail ('Next: dt_doctor -> dt_free_slots') and routes the agent to dt_doctor for pricing, which is clear when-to-use-which guidance. It lacks an explicit statement of when not to use this tool or how to choose among sibling search tools, keeping it short of a 5.

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, open-world behavior, so the bar is lower; the description still adds real operational context — that the upstream sort order is unknown and prices must be compared client-side, and that pay_online represents only the deposit when payment=deposit_online (rest paid at the place). It does not discuss pagination limits beyond what the schema says.

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-loads the purpose before the card contents and next steps, with zero filler sentences. The card-field enumeration is dense but each field maps to a real downstream decision (price, deposit, consultation_id), so it earns its space despite being longer than typical.

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 an 11-param, zero-required search tool with an output schema and full annotation coverage, the description covers purpose, workflow, and a behavioral gotcha well. Return-value explanation is technically redundant given the output schema, and it omits any hint about how the many optional filters combine (e.g., can city and neighborhood be used together), a minor gap.

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 11 parameters (city slug, doctor hash/URL, price bounds, speciality/service_tag/neighborhood slugs) are already documented. The description adds no filter semantics beyond the schema; its pay_online and consultation_id mentions pertain to response cards, not inputs. 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 (search clinic offers) and immediately defines the domain object — fixed-price procedures and packages sold by doctors and centers — which separates it from dt_search_doctors and dt_search_centers. It also names the detailing sibling dt_offer, so an agent can route 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?

Gives a clear follow-up workflow (dt_offer for detail, dt_free_slots using the card's consultation_id, dt_reviews with of='offer') and an explicit caution to sort prices manually because upstream sort is unknown. It never states when to prefer this tool over the other search siblings (doctors/centers), so it stops short of full alternative 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 carry readOnly/idempotent/openWorld/no-destructive, so the bar is lower. The description adds useful scale ('About 100 entries') and domain semantics for level and parent values, which help the agent interpret results rather than just repeat annotation claims.

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 purpose and compact overall. The level/parent sentence is somewhat telegraphic ('interventional cardiology -> cardiologist') but earns its place by clarifying hierarchy semantics.

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, 100% schema coverage, and full annotations, the description only needs to add routing and domain context, which it does. Minor gap: no note on result ordering or whether the ~100 entries are always returned in full.

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% and the single query parameter is fully documented in the schema (Persian/slug, omit for all), so baseline is 3. The description's level/parent notes describe return values, not the parameter, so they add no parameter meaning.

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, paramedical and dental specialities) and ties the output purpose to a sibling (the slug dt_search_doctors needs), so an agent can distinguish it from dt_cities, dt_insurances, etc.

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 clear downstream workflow: 'Next: dt_search_doctors(speciality=slug)', which tells the agent when this tool belongs in a chain. It does not state explicit exclusions or when to reach for an alternative sibling, so it falls short of 5.

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 safety profile (readOnly, idempotent, non-destructive), so the description's added value is the matching behavior: doctors match by name text only, and results carry hash ids rather than raw ids. That is genuinely useful nuance beyond the annotations, though it doesn't discuss ranking when city_id is absent or result caps.

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 usage and mapping, then next steps — a sensible funnel with no filler sentences. The line-wrapping and mid-sentence example make it slightly harder to scan than it needs to be.

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 and the description still summarizes the four return categories (doctors with hash id, speciality slugs, service tags, centers), which is what the agent needs to route the result. With only three simple parameters and full schema coverage, nothing essential 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; the description adds meaning by framing 'query' as a free-phrase-to-slug translator and by clarifying the semantic difference between the doctor and speciality result sets. It doesn't add format detail beyond the schema's own examples for query and city_id.

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 and resource ('Search-box suggestions: matching doctors (with hash id), speciality slugs, service tags and centers') and enumerates exactly what kinds of entities come back. It also names downstream siblings, so an agent can distinguish this from dt_search_doctors or dt_center without reading either 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 an explicit when-to-use rule ('turn a free phrase into the slugs and ids the other tools need') plus a concrete workflow example mapping 'قلب' to the speciality slug. It also states a conditional preference — prefer the returned speciality slug over the doctor list for specialities — and names next-step tools.

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