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's enumeration of returned content is largely redundant with the existing output schema, so it adds little behavioral context 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 core purpose and then a compact routing paragraph; no filler. The returned-field list is slightly redundant against the output schema, keeping it just short of a 5.

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 full schema coverage, complete annotations, and an output schema, the description only needed to orient the agent and route to siblings, which it does. Nothing essential is missing, though it offers no edge-case or prerequisite notes.

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 slug origin, the specialty Persian-text filter, and the doctors_limit semantics are all documented in the schema with min/max and defaults. The description's mention of doctor fields does not add parameter-level meaning, 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 (hospital/clinic profile) and enumerates exactly what it returns: type, address, phone, website, map, about text, departments, and embedded doctors. It then names the sibling tools (pz_search_doctors, pz_doctor) so the agent can distinguish this profile fetch from the doctor-list and single-doctor tools.

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: for a paged doctor list sorted by nearest free time call pz_search_doctors with sort='earliest'; for a single doctor call pz_doctor(slug). This gives clear alternatives with conditions, though it never states when this profile tool is the wrong choice or any prerequisites.

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, so the bar is lower; the description nonetheless adds real behavioral context: what 'booking_off: true' means (call the phone), what 'booking_opens' means (slots open later), and that booking happens externally with SMS login. No contradictions.

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 payload are front-loaded in the first sentence, and the guidance sentences are short. However, the long parenthetical field enumeration and mid-sentence line breaks ('...pz_resolve_url. The center_id + user_center_id + service_id of a service feed...') add some density without much extra value.

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 need not explain return values, yet it does summarize them. It covers the mutation-free nature and downstream id chaining, leaving only minor ambiguity about how the returned center/service ids are meant to be threaded into the listed sibling tools.

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?

Only one parameter with 100% schema description coverage, including an example and the note that it accepts either a slug or a profile URL. The description adds no syntax or format detail beyond the schema, 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 and resource ('Full profile of one doctor') and enumerates the exact payload: specialties, council code, ratings, insurance, online visit channels/price, and every office with address, phone, map, first free slot and services. It is immediately distinguishable from list/search siblings like pz_search_doctors or pz_center.

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 to use it 'after pz_search_doctors or pz_resolve_url' and explains the booking flow ('Booking itself is done by the user on the returned url (it needs an SMS login)'). No explicit when-not-to-use condition is given, but the placement in the tool chain 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 declare readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description adds behavior beyond them: the empty-query browse mode and the fact that answers are drawn from an official FAQ corpus (authoritative, site-scoped). Minor gap: nothing about answer length or result limits beyond the schema's default.

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 plus a topic parenthetical, all front-loaded: purpose first, browse-mode caveat second, usage rule last. Nothing redundant with the 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?

Output schema exists, annotations are rich, and both parameters are fully documented, so the description need not explain returns. Remaining minor gap is that it does not hint at result-shape/limit interplay, but that is adequately handled by the 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 100% and the schema itself documents the Persian topic-word format and that empty query lists all questions, so the description only echoes the empty-query behavior. Baseline 3 applies when the schema carries the parameter semantics.

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 ('Answers from the official Paziresh24 FAQ') and enumerates the covered domains (booking, cancel/move appointment, online visits, payment/refunds). No sibling tool (doctor search, prices, slots, holidays) does FAQ answering, so the agent can route 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?

Explicitly scopes use to '"how do I ..." questions about the site', and adds the no-query browse mode ('Without a query it lists the questions only'). Clear usage context, though it never names a sibling alternative for overlapping informational queries.

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, open-world, so the safety profile is covered. The description adds real context beyond them: results are per center, cover both in-person and online visits, and are in Tehran time, which matters for interpreting slot times.

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, capability stated first, workflow routing second. The parenthetical center hint is slightly tangential for a one-parameter tool but still compact and useful for follow-up 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?

An output schema exists so return values need no prose, and the description supplies the time-zone and scope context needed to interpret results. Combined with 100% schema coverage on the sole parameter, the definition is largely 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?

Schema coverage is 100% and the single slug parameter is fully documented in the schema itself (Persian slug from pz_search_doctors or profile URL). The description adds no slug syntax or formatting beyond that, so this is a baseline 3; its extra center_id '$5532' note pertains to other tools' parameters, not this one's.

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 capability: whether a doctor is bookable now plus the nearest free slot, scoped to in-person/online and per center. It names its sibling relationship (pre-check before pz_free_days / pz_free_slots), so an agent can place it in the toolchain 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 positions itself as 'a quick check before pz_free_days / pz_free_slots', giving clear ordering relative to alternatives. No when-not or exclusion cases are stated, but the workflow role is unambiguous.

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/idempotent/destructive=false/openWorld, and the description reinforces this while adding real context: 'nothing is reserved' clarifies the call has no side effect on availability. It also discloses the result's temporal scope (6-8 weeks) and that weekly days off and holidays are included, which the annotations do not cover.

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?

Short and front-loaded: scope of the return value first, then a workflow/safety note. Sentence fragments (e.g. 'Next: pz_free_slots ...') are terse but readable and each clause carries 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, return-format explanation is unnecessary, and the description covers scope, provenance of ids, read-only nature, and next steps. It leaves minor gaps around volume/pagination of returned days, but nothing an agent needs 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% and each parameter already carries an example and a source hint. The description only adds provenance ('Get the ids from pz_doctor'), which is mild value over the schema; baseline 3 for high-coverage schemas 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?

States a precise verb+resource: days with at least one free appointment, scoped to one service, one doctor, one center, across the whole booking window. It also distinguishes itself from neighbors by naming pz_doctor as the id source and pz_free_slots as the follow-up for times.

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 when to call it (finding candidate days before picking times) and routing: ids from pz_doctor, then pz_free_slots, with booking happening on the doctor's profile URL. No explicit when-not-to-use or named exclusions, which keeps it just below 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 readOnlyHint/idempotentHint/non-destructive, but the description adds real value by clarifying it 'does not hold or book one' and that actual booking requires an SMS login outside this tool. It does not cover rate limits or pagination, so it falls short of a 5 given annotations carry the safety profile.

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 core purpose, then a compact paragraph covering read-only behavior, ID sourcing, and the booking path. Every sentence earns its place; slightly long but no 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, return fields needn't be explained, and the description still proactively mentions next_free_day behavior plus the booking hand-off. Complete enough for correct invocation, though it omits the 14-day range cap that lives in the 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 100%, so all five parameters are documented in the schema, including the 14-day cap and ID formats. The description adds only the 'Tehran HH:MM' time convention and date-range scoping, which is marginal 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+resource ('Free appointment start times ... per day for one service of a doctor at one center, for a date range'), including the scope dimensions that matter. It is clearly distinguishable from the sibling pz_free_days (day-level) versus this tool (slot-level).

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: get ids from pz_doctor or a search card, find days with pz_free_days, and send the user to the profile URL to book. It also states the edge case behavior (no free slot → next_free_day) so the agent knows how to interpret an empty result.

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 safety profile is covered. The description adds real behavioral context beyond that: the exclusion of Fridays (the weekly day off) and the shape of each returned record.

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 short sentences with zero filler; the coverage statement comes first and the actionable guidance ('use before suggesting appointment days') is front-loaded where an agent will read it.

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-value detail is unnecessary, and annotations cover the safety profile. The description supplies the essential scope, exclusion, and usage cue; the only missing niceties are the one-year span limit and any timezone caveat, both of which the schema already handles.

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%, including the formatexamples and the one-year maximum span, so the schema carries the parameter burden. The description adds only the phrase 'between two dates', which contributes no syntax or format detail 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?

States a specific resource ('Official Iranian public holidays and occasions') and scope ('between two dates'), plus what is returned (Persian occasion name, Hijri date). It is clearly distinguishable from scheduling siblings like pz_free_days or pz_free_slots, though it does not name a sibling explicitly.

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 before suggesting appointment days' gives a concrete when-to-use condition, and the note that Fridays are excluded prevents a common misinterpretation. No alternative tool is named for comparison, so it stops 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds a small amount of context (the classification outcome and the chained next tool) but nothing beyond what the output schema and annotations already establish.

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 short sentences, front-loaded with the transformation and followed by the trigger plus next-tool routing. 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?

An output schema exists and annotations cover safety, so return values and side effects need no further explanation here. The only small gap is behavior on an unrecognized or malformed link, which is not stated anywhere.

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 at 100% schema description coverage, and the schema already spells out the accepted path forms (/dr/, /center/, /factor/v2/) and encoding tolerance. The description only restates that the input is a paziresh24.com link, 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 (turn a paziresh24.com link into kind + slug + clean URL) with an explicit output shape, so the agent knows exactly what comes back. It is clearly distinguishable from the sibling lookup tools (pz_doctor, pz_center) which it feeds into.

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 when the user pastes a link" gives the trigger condition, and the second sentence names the two follow-up alternatives (pz_doctor for a doctor, pz_center for a hospital/clinic) with the condition that selects each. Routing guidance is explicit rather than inferred.

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 readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds non-obvious behavior: reviewer names and ids are never returned (a privacy guarantee an agent couldn't infer) and online-visit reviews carry the sentinel center_id '5532'. It also notes the summary appears only on the first page, which is a real paging gotcha.

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 and a short fragment, front-loaded with what the tool returns and how it pages. The parenthetical field list is dense but each item carries information; nothing is wasted, though it could be slightly tighter.

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 a full input schema, an output schema, and rich annotations, the description only needs to cover behavior those structures can't express, and it does so via the privacy note, the sentinel center_id, and the first-page-only summary. Minor gaps (e.g. explicit no-results or auth behavior) keep it from being fully 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?

Schema description coverage is 100%, so slug, sort, limit and offset are fully documented in the schema itself. The description adds no syntax, range or format detail 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 resource (patient reviews of a doctor) and enumerates the concrete content returned (star ratings for behaviour/explanation/treatment, text, visit reason, center, verified visit), plus the paging model. An agent can distinguish this from sibling profile tools like pz_doctor or pz_center 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?

It implies the workflow by telling the agent where the slug comes from (pz_search_doctors or a paziresh24.com profile URL), which is useful prerequisite context. However, it never states when to prefer this tool over an alternative or when reviews are unavailable, so usage is only implied.

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 bar is covered. The description adds genuine behavioral context beyond them: what each result card contains, that online_visit price is only present when offered, and that a null service_id originates from pz_doctor. It stops short of discussing paging limits or result-count behavior, but the added detail is substantive.

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 filter list, then a second paragraph on result contents and routing. Dense but every sentence carries information; the result-card inventory is somewhat long and partly overlaps the output schema, keeping it from a 5.

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 12-param, zero-required search tool with annotations and an output schema present, the description covers purpose, filter semantics, a known limitation, handoff ids for downstream slot tools, and next-step routing. 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 coverage is 100%, so the schema already documents all 12 params and the baseline is 3. The description adds meaning by summarizing the filterable dimensions and explicitly recording a negative constraint (no insurance filter) plus the null service_id provenance note, which goes 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?

Opens with a specific verb and resource ('Search Paziresh24 doctors (or hospitals and clinics)') and enumerates the filter dimensions (city, specialty, name, online visit, gender, degree). The parenthetical covering hospitals/clinics and the explicit naming of sibling tools makes it easy to distinguish from pz_doctor and pz_center.

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: 'Next: pz_doctor for the full profile, pz_first_available, or pz_free_days / pz_free_slots with the ids of a card's center.' It also flags a real constraint exclusions-style ('There is no insurance filter: check insurances yourself'), so the agent knows what NOT to expect from this tool.

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, openWorld, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful context beyond that: the data is the site's type-ahead completions and is intended as a precursor resolution step. It stops short of describing the return structure, though an output schema exists.

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 core mapping and then the workflow guidance. Every clause carries information; no 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, return values need not be explained, and the description covers the resolution-then-search workflow an agent needs to use this 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?

Schema coverage is 100%, so the schema already documents query and limit. The description restates the kinds of input words but adds no format or syntax detail beyond the schema, 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?

States a specific verb+resource: turning words into pz_search_doctors arguments (city slug, specialty slug, type-ahead completions). It explicitly names the sibling it feeds into, so an agent distinguishes it from pz_search_doctors without opening 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?

Gives explicit when-to-use ('Call this first when you do not know the English city slug or the specialty slug') and the exact follow-up call with argument mapping (city=<slug>, specialty=<slug>, text=<completion>). The alternative path is fully specified.

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/open-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: what the total represents (what the online-visit invoice shows), the refund-on-cancel value included, and the important edge case where in-person visits return 0 and why.

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: the first front-loads what is returned, the second the applicability caveat. Every sentence earns its place and the most decision-relevant content (what the value means, when it is nonzero) comes first.

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 structure is documented, yet the description adds the interpretive layer that matters for this tool: what the payable total means and why in-person prices read as 0. Combined with annotations covering safety and 100% schema coverage, 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%, and each parameter is documented with format patterns, source tools (pz_doctor, pz_search_doctors cards), and examples. The description's only parameter-relevant note ('5532' = online visit) already appears in the schema, so it adds no meaning beyond structured data; 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 specific resource and result: the exact price of one service in Toman, enumerated as doctor's fee, VAT, payable total, plus the refund-on-cancel setting. This is precise enough that an agent immediately understands it returns a cost breakdown, not availability or profile data like its siblings.

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 clear usage context: 'Most useful for online visits (center_id \'5532\')' and warns that in-person office visits usually return 0 because the fee is not published. This is strong when-to-use guidance, though it names no specific sibling alternative to prefer when this tool does not apply.

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