Brands

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: the corpus size (~2,400 brands), the domain (pharma, cosmetics, supplements) and the matching rule (case-of-script substring of Persian or English name), plus what the profile mode returns. It stops short of describing no-match or empty-result 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?

Front-loaded with the tool's dual purpose, then supporting detail; two short paragraphs with no filler. It is dense rather than wasteful, though the parenthetical brand-type list and the nested clause about categories could be tightened slightly.

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?

There is no output schema, so the description must carry return-shape information, and it does for both modes (search returns ids; profile returns about text, product count and categories). What is missing is edge-case behavior — no matches, missing id, and result ordering — which matters for an open-world search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema alone justifies a baseline of 3. The description goes further by explaining what `id` is for (profile mode) and constraining `query` semantically — a substring of the Persian or English name — with concrete examples, and it explains that the id must originate from a search here. `limit` is left entirely to the schema, which is fine.

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 ('Find a brand by name') and immediately states the two modes: search by name to get an id, or read a brand's profile by id. It also names the sibling tools that consume the returned id (dr_search, dr_cheapest), so an agent can distinguish it from dr_categories and dr_product 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?

Clear routing: pass `query` to look up a brand id and feed it to dr_search/dr_cheapest as `brand`, or pass `id` (obtained from a prior call here) to read the profile, whose categories are reusable as `category` in dr_search. The two-step chaining is spelled out well, but there is no when-not guidance (e.g., what to do when no brand matches, or when a category lookup via dr_categories is preferable).

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