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

Annotations already declare readOnly, idempotent, open-world, non-destructive. With no output schema, the description usefully discloses the return shape (amended_by/amends with id, title, approval date; articles with section id, label, change count, latest change). It does not mention ordering or whether limit applies to both lists 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 three questions answered, then the return contents, then the sibling pointer. No filler, though the middle sentence is densely packed with field lists that border on schema recap.

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?

Since there is no output schema, the description's enumeration of returned fields is exactly what an agent needs to consume the result. Combined with the routing hint and full schema coverage, nothing material is missing for calling 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% – both ids and limit are documented in the schema, including the IDS source and the digits-only pattern. The description adds no parameter-level detail beyond that, 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 subject (amendments of a law) and enumerates exactly the three relationships it answers: which laws amended this one, which it amends, and which articles were amended. The reference to qv_article_history for a different granularity cleanly separates it from 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?

Explicitly routes the agent to qv_article_history(section_id) when a single article's full history is wanted, which is a real alternative. It gives no guidance on when this tool is unnecessary (e.g. if only law metadata is needed, qv_law_info may suffice), so it stops just short of full when/when-not coverage.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context that annotations cannot: ordering ('oldest change first') and the empty-result contract for unamended articles.

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 plus a sentence fragment, front-loaded with what is returned and followed by the usage condition. The Persian '(اصلاحی...)' gloss with a trailing ellipsis is slightly opaque but does not cost much space.

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 return-value burden and does so reasonably: it names the fields, the ordering, and the empty case. It does not specify the exact response shape (list vs wrapped object) or any pagination, leaving a small gap for a history-list 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 one parameter with 100% schema description coverage, and the schema already explains the pattern and where the section_id comes from. The description adds no syntax or sourcing 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 verb+resource ('Every amendment of one article') and enumerates the returned fields (type, date, amending law, replacing text), so the agent can distinguish it from qv_amendments and qv_law 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 trigger and prerequisite chain: use after qv_law or qv_amendments when asked how an article changed, and notes the empty-list case for never-amended articles. It does not state a when-not condition or an exclusion against other siblings, 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 cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds material context beyond them: first-call latency (~15 s) and scale (~1,500 sections in the civil code), pagination semantics via offset/next_offset bounded by max_chars, and the per-section field structure (`id`, `label`, `text`, `status`, `history`). With no output schema, this is exactly the burden the description should carry.

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 core purpose, then layers return structure, paging/perf, and sourcing in descending priority. Every sentence carries actionable information; no filler or restatement of the name.

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 tool with six parameters, no output schema, and rich annotations, the description covers purpose, sourcing, pagination, latency, and return shape. An agent has everything needed to call it correctly and interpret the result.

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 would be 3, but the description earns extra value: it explains the paging contract between `offset` and `next_offset` within `max_chars`, and ties `article` to the 'what does article N say' question, and shows example labels ('ماده 10', 'تبصره 1') that clarify the label format the id must match.

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?

Names a specific verb and resource ('Read the full text of a law, regulation, court vote or opinion') and immediately scopes the output shape ('as sections'). It is distinguishable from siblings: qv_search supplies the id, qv_article_history supplies amendments, and qv_law supplies the text itself.

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 routing ('Get the id from qv_search') and a concrete use case for the `article` parameter ('to answer "what does article N say"'), plus points at qv_article_history via the `history: true` flag. It lacks an explicit statement of when NOT to use this tool versus qv_law_info or qv_lookup, so it stops short of full when/when-not 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 declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real context beyond that: dates are Jalali (affects how the agent reads every returned value) and metadata is sparse for court votes/opinions. It does not cover failure modes for unknown IDs or any 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?

Front-loaded with the resource and its returned fields, then usage, then two caveats (sparse metadata for opinions, Jalali dates). Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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 field enumeration plus the Jalali and sparse-metadata caveats give the agent nearly everything needed to interpret the result. Minor gap: the parameter is named 'ids' (plural) but typed as a single-digit string, and behavior on non-existent IDs is unstated.

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 already documents its source (qv_search), digit-only pattern and an example value. The description adds nothing about the ID beyond implying provenance via 'Use after qv_search', so the schema carries the weight and a 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 resource (a law's metadata) and enumerates exactly which fields come back: type, approving body, approval/notification/gazette dates and numbers, status, effective date, executing bodies. It implicitly distinguishes itself from full-text siblings by noting that court votes and opinions carry almost no metadata, but it never explicitly contrasts with qv_law or qv_amendments.

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 trigger conditions: use after qv_search to cite a law, or to check its type. It also flags a de facto when-not case (court votes and opinions have almost no metadata, so this tool adds little there). No alternative sibling is named as an explicit substitute, which keeps it 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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral detail beyond them: return shape (items with `id` and name), that approver/executor/subject also carry `count`, and that those kinds are paged by 20. It does not disclose page limits for the unpaged kinds (type/status/list) or what an empty honest query returns precisely.

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 return shape, then a worked example. Every sentence carries information and there is no filler, though the enumeration of kinds slightly duplicates the schema's enum list.

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 takes on the burden of describing returns and does so (id, name, count, 20-per-page). An agent has enough to call it correctly, though the differing paging behavior across kinds and the query-matching semantics are only partially covered.

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 enum value plus page/query is already documented with Persian glosses in the schema. The description's example for kind='approver' adds a little applied meaning, but mostly restates the paging behavior already in the schema. 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 ('find the ids that qv_search filters take') and enumerates exactly which filter dimensions it resolves. It explicitly ties itself to sibling qv_search, so an agent can distinguish lookup from search 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?

The description makes the use case clear: resolve a human name (e.g. 'مجلس') into an id to pass as approver_id to qv_search. It gives a concrete example, but offers no explicit when-not-to-use or guidance on which kind to pick versus calling qv_search directly with a raw query.

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 safety, so the bar is lower. The description still adds real value: it discloses the result shape (two groups, laws and others), ordering (newest first), volume expectation (hundreds for the civil code), and that court votes/opinions come back as titles only.

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 return structure, then a pointer to qv_law for reading results. Two sentences, dense but no filler; the volume/ordering note is arguably extra but useful for expectation-setting.

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 compensates by describing the return groups and their fields, which is exactly what an agent needs to consume results. Safety is covered by annotations; only cross-sibling disambiguation is thin.

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 documented in-schema (ids format/source, limit bounds). The description adds no syntax 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 (documents related to a law) and enumerates exactly what kinds: other laws, regulations, court votes, legal opinions that cite or interpret it. An agent can immediately distinguish this from qv_law (which reads an individual document) and the other 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?

Usage is implied rather than stated: the agent infers it needs a law IDS from qv_search and uses this to find citing/interpretive material. No explicit when-to-use or when-not-to-use guidance versus qv_amendments or qv_article_history, which cover related but distinct relationships.

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/openWorld, yet the description adds non-obvious behavior: text search returns no snippets, and date sorting has many ties so paging a long list may repeat or skip rows, with a concrete remedy ('narrow the filters'). It also enumerates the return payload fields in the absence of an output 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?

Four sentences, front-loaded with purpose, then return contents, then use cases, then the pagination caveat. The return-field enumeration is slightly dense but earns its place because no output schema exists.

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 17-parameter, no-output-schema tool it covers what is returned, what the IDs feed into, and the one operational hazard (unstable date paging). It stops short of describing parameter interactions or behavior when no query is supplied, which a tool this complex could still benefit from.

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 every one of the 17 parameters is already documented with enums, defaults and cross-references to qv_lookup kinds. The description adds no per-parameter syntax or constraint detail beyond what the schema provides, 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 (search) and resource (Iranian law and regulation database, qavanin.ir, 168,000 documents) plus the output shape (matching titles). It is clearly distinguished from siblings: this is the discovery tool, while qv_law/qv_law_info/qv_amendments/qv_related consume the `id` values it returns.

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 use cases ('which law covers X', 'all regulations of body Y in a date range', 'latest laws') and routes the agent to the ID-consuming siblings. It does not spell out when to prefer another tool over this one (e.g. direct-ID retrieval), but the downstream routing makes the intent clear.

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