Doctor reviews

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.