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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description still adds real value beyond them by disclosing a data-quality trait the agent could not otherwise anticipate: national codes in the returned text are truncated to their first 6 digits as shown on the site. It does not describe text length, language, or pagination, but the core behavioral caveat is present.

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 resource and its content scope, followed by a single caveat. No filler, no repetition of the title.

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 one-parameter read-only lookup with full annotation coverage and no output schema, the description supplies enough: what is returned (full ad text), what topics it covers, and the redaction caveat. Minor gaps like output size or structure are not blocking for an agent deciding whether and how to 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% and the single ad_id parameter is fully documented in the schema, including where the id comes from. The description adds no additional meaning about the parameter, 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+resource ('Full text of one official gazette ad') and enumerates the content categories it covers (board changes, capital changes, founding, liquidation), which tells an agent exactly what kind of record it gets back. It does not explicitly contrast itself with sibling tools like rs_company or rs_person, which is the only thing keeping it from a 5.

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?

Usage is only implied: the framing 'one ad' signals a single-record lookup, and the routing hints (ad_id from rs_company recent_ads, board ad_id, or rs_person ads) live in the schema rather than the description. There is no explicit when-to-use/when-not statement or named alternative.

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, and the description layers on what they cannot: a per-IP anonymous quota, the fact that an explicit error is returned when exhausted, that search remains functional, and that dates are Persian (1404/06/26). That is exactly the kind of context an agent needs before calling.

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 identity sentence, then organized into Basics, cross-references, and quota warnings. Dense but nearly every clause carries information; the 'Basics:' inventory is slightly list-like but useful for an agent deciding whether this tool answers its question.

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 complex multi-section tool with no output schema, the description conveys section contents, id cross-references, date format, and access limits. It does not state what happens when sections is null versus empty, nor how max_rows affects which rows are chosen, which are the remaining gaps.

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%, with sections and max_rows already fully documented in the schema, so the baseline is 3. The description adds modest meaning by tying board rows to person_id/ad_id and framing 'ads' as gazette notices, but it does not explain the section mapping or the max_rows truncation trade-off beyond what the schema says.

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 ('Registry profile of one Iranian company') and then enumerates exactly what the profile contains: basics, board/CEO, shareholders, licenses, capital history, ads. It also distinguishes itself from siblings by naming rs_person and rs_ad as downstream lookups for the ids returned here.

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 real operational context: anonymous visitors are limited to a few profiles per IP every few days, a clear error signals the limit, and search still works at that point. The 'get company_id from rs_search_companies' routing lives in the schema rather than the description, so the when-to-use-vs-siblings guidance is present but split across fields.

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 operation is read-only, idempotent, non-destructive, and open-world. The description adds useful context about what registration details are returned (numbers, date, owner, description), but does not add behavioral details such as error behavior or rate limits.

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 description is a single compact sentence that front-loads the resource and lists key returned fields without waste. It is appropriately sized, though it functions more as a label than a full instruction.

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 simple two-parameter read-only lookup, the definition is largely complete: the schema covers both parameters and where ip_id comes from, annotations cover safety, and the description names the returned fields. The main missing piece is explicit usage routing relative to rs_search.

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 already explains ip_id's source and the kind enum values. The description's mention of trademark, patent, and industrial design loosely maps to kind but adds no syntax or usage meaning 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?

The description clearly identifies the resource as Iranian trademark, patent, or industrial design registration details and lists the record contents. It is specific enough to distinguish from sibling search/person/company tools, though it does not explicitly name alternatives.

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 description gives no explicit when-to-use guidance, prerequisites, or alternatives. It implies this is a detail lookup, but does not say to use rs_search first to obtain an ip_id or when to choose this over sibling 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 readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds one real behavioral fact beyond that – 'counts are how many companies or products carry each value' – which explains what the returned data actually means. It stops short of describing result shape, size, or anything about the 'needs query' constraint being enforced as an error versus a silent empty list.

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: the first states what is returned, the second states how to use it. The most important information is front-loaded and no sentence is 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 no output schema, the description correctly compensates by explaining that results carry ids, names, and counts. It is nearly complete for a small lookup tool, with the main omission being the provinces/cities list that the enum exposes but the prose never mentions.

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 in the schema and the baseline is 3. The description's mapping of returned ids onto concrete downstream search parameters adds some value, but it does not clarify the schema's weaker points, such as whether 'query' is strictly required for licenses or what happens when 'category' is supplied for a non-categories 'what' value.

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 specific verb and resource ('List the ids and names the search filters take') and enumerates the value families, which clearly separates it from the sibling search tools that consume those values. The only gap is that 'provinces' appears in the enum and in the downstream parameter list but is omitted from the opening enumeration.

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 explicitly routes the agent downstream, telling it to feed the returned id/slug into rs_search_companies (company_type, license_id, product_category, province, city) or rs_search (product_category, brand_class), which is genuinely useful selection guidance. There is no explicit 'when not to use' statement, but the intent of a lookup/enumeration tool 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 readOnly, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds real value beyond them: the meaning of current=false as a finished term, the cross-reference semantics of ad_id and company_id, and an explicit negative scope ('Contact details and national codes are not returned') that prevents wasted follow-up calls.

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 with no filler, front-loading what is returned and then following with field semantics and exclusions. The opening is a noun phrase without a verb, which costs a little immediate clarity, but the density of useful information per sentence is high.

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 no output schema, the description carries the burden of describing returns and does so: companies with role types, role dates, gazette ads, plus how to open ad_id and company_id. Missing details such as ordering, result caps, or pagination behavior are the only residual gaps for a single-parameter lookup 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 a single parameter with 100% schema description coverage, including format ('Hex person id') and a concrete example plus provenance. The description adds nothing further about person_id, so the baseline of 3 applies — the schema does all the work here.

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 concrete resource returned — companies a person manages, boards on, or audits, with role dates and latest gazette ads — which is far more specific than the bare name 'rs_person'. It lacks an explicit verb ('Returns ...') and never states that the person's own identity fields are included, but the substance distinguishes it clearly from rs_company and rs_search.

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?

Usage is only implied: the schema's person_id note ('from rs_search(kind='people') or a board row of rs_company') indicates the entry path, and the description tells you which sibling to call next (rs_ad, rs_company). There is no explicit 'use this when ...' or 'do not use for ...' statement, and no guidance on when to prefer rs_search over 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 establish readOnly, idempotent, openWorld, and non-destructive behavior, so the bar is lower. The description still contributes by disclosing the shape of the payload (specs, category, comparable suppliers) and how similar_suppliers and category_slug connect to other tools, which annotations cannot convey.

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 content is front-loaded in the first sentence, and the second paragraph is devoted entirely to cross-tool linkage. Every sentence carries useful information with no filler or repetition of 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?

There is no output schema, so the description must carry the return-shape burden, and it does so by naming the main fields and the similar-suppliers table. It stops short of stating return format or ordering, but an agent has enough 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 both parameters are already documented, including that product_id comes from rs_search(kind='products') and that max_rows bounds the similar-suppliers table. The description reinforces that similar_suppliers is the row-limited section but adds no new syntax or semantics 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?

The description names the resource precisely (a single registered product) and enumerates its contents: HS/ISIC codes, brand, maker, country, category, and comparable suppliers. That is far more specific than a restatement of the title, though it phrases the action as a noun ('One registered product') rather than an explicit retrieve-by-id verb.

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 concrete routing help for two siblings: similar_suppliers entries carry a company_id for rs_company, and category_slug maps to product_category in rs_search_companies. It does not say when to prefer this over rs_search(kind='products') for discovery versus detail lookup, so a small gap remains.

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 behavior, so the safety profile is covered. The description's contribution is disclosing the shape of results per kind, which helps the agent plan the follow-up call. It says nothing about ranking, empty-result behavior, or the 200-page/60-per-page ceilings beyond what the schema states.

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 resource list, then result identifiers, then the sibling exclusion. Every clause carries information and nothing is 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?

With 8 parameters at full schema coverage but no output schema, the description compensates by describing the identifiers returned and which tool consumes them. It is nearly complete for the tool's complexity; only result ordering and volume expectations are left implicit.

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 a 3 is the baseline, but the description adds value by explaining what each `kind` yields — person_id for people, product_id plus supplier company_id for products, ip_id for brands and patents. That mapping is genuinely useful semantics the enum alone doesn't convey.

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 enumerates the exact resource types searched (people, products, registered brands, patents, industrial designs), and further maps each to the detail tool it feeds (rs_person, rs_product, rs_ip). It also names the sibling it is not for (rs_search_companies), so the agent can distinguish it 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?

Gives a clear routing rule: 'For companies use rs_search_companies (it has filters)' — an explicit exclusion with a reason. It also implies usage via the id-chaining guidance. It stops short of saying when to prefer 'everything' versus a specific kind, though the schema enum covers that.

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?

The annotations already carry the read-only, idempotent, non-destructive profile, and the description adds real value beyond them by disclosing the result shape: national id, name, age/capital summary, CEO, and up to 5 licenses. It does not mention pagination behavior or result-cap behavior (page max 200, page_size max 60), which is the 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 short paragraphs in a clear order: what it does, what it returns, what to do next. No redundant restatement of parameters and no filler sentences.

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 18-parameter search tool with no output schema, the description covers the return contents and the downstream workflow, which is the critical missing piece. It stops short of noting pagination or how many total results to expect, leaving a modest gap for a large filter surface.

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 genuine meaning: it explains that filters combine freely, shows a multi-filter example, and clarifies that company_id is the national id (شناسه ملی) that feeds rs_company. The cross-tool pointer for license_id/company_type sources is documented in the schema rather than the description.

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?

Uses a specific verb and resource ("Search Iranian companies by name or activity with filters") and immediately scopes the tool's role in a pipeline by naming the sibling rs_company as the follow-up for full profiles. An agent can distinguish it from rs_search, rs_company, and rs_person 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 an explicit combinatorial example ("active software companies in Isfahan with capital over 10 billion Rial") and a clear next-step directive, plus the note that an empty query means filters-only. It lacks an explicit when-not-to-use statement versus the generic rs_search 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.