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

Annotations already cover the read-only/idempotent safety profile, but the description adds real substance beyond them: `id` is only populated after publication (so the field is conditionally absent), the calendar is Jalali with month 1 = فروردین, and planned dates can shift. That last caveat is the kind of data-reliability trait annotations cannot express.

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 purpose, then the use case, then the item shape and caveats, in four tight sentences with no filler. Slightly dense with backtick and parenthetical asides, but every sentence 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 no output schema, the description accepts the burden of describing the returned item's fields and the conditional `id`, which it does. It leaves result volume, ordering and whether the whole-year default paginates unstated, a minor gap for a calendar lookup.

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 the schema already explains year, month (1-12 or Persian name, omit for whole year) and the all-terms-must-match `query`. The description adds only the Jalali convention note, which largely duplicates the schema's own 'Jalali year of the calendar' wording and never mentions the `query` filter at all, 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: 'Get the Statistical Centre of Iran's publishing calendar: which statistics come out on which day of a month.' It also enumerates what each item contains (product, responsible office, month/day, covered period), which is far more than the name 'am_calendar' alone conveys.

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 use case ('Use it to answer "when is the next inflation (or labour force, GDP...) release"') and routes the agent downstream ('`id` is set once the release is published: pass it to am_release'). Missing an explicit when-not or a contrast against am_search/am_news, but the scenario 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial domain context: base year 1400 = 2021, that growth_pct is a constant-price change on the same quarter a year earlier, what gdp_ex_oil_pct excludes, which activities sit under 'industry', and that levels are in billion rials. With no output schema, these field definitions and the 'latest first' ordering are exactly what the agent needs to interpret results.

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 purpose is front-loaded in the first sentence, with definitions and the am_table escape hatch following. It is dense and mostly earns its length, though the parenthetical listing of industry sub-sectors is slightly padded.

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 two-parameter read tool with no output schema, the description supplies the return-value semantics (measure definitions, units, sector coverage, ordering) and the fallback route for deeper data. Nothing an agent needs to call or interpret this tool 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 both parameters are already documented in structured data. The description reinforces the meaning of 'latest first' and the quarter-vs-year distinction but adds no format or constraint detail beyond the schema, so the baseline 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 ('Get Iran's official GDP growth by quarter or year') plus the content returned ('main sectors, latest first'). This clearly separates it from siblings like am_inflation, am_labour_force, and am_table, which cover different datasets.

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 elsewhere for detailed breakdowns: 'For the full tables (value added by activity, expenditure side) use am_table with the `source.release` id.' That is a concrete alternative with a condition, though it does not cover other plausible near-neighbours such as am_indicators.

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 safety is covered; the description adds genuinely new behavior: dash and '000' placeholders are returned as null, data ends at different dates per table, the release is exposed in `source`, and the newest file is located by title rather than id. It does not discuss truncation limits beyond the row/column parameters, which keeps it from a 5.

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 workbook purpose and the call sequence are front-loaded, and the two paragraphs earn most of their space with caveats about placeholders, per-table date ranges and output row shape. The Persian title and topic parentheticals add some bulk but carry real disambiguation 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?

There is no output schema, yet the description explains the return shape (combined header columns, rows as [label, values...]), the null encoding for placeholders, uneven date coverage across tables, and where provenance lives. For a 6-parameter read-only research tool that is enough for an agent to call it correctly in a single pass.

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 the schema already documents find, last, table, topic, max_cols and col_offset, establishing a baseline of 3. The description adds procedural meaning by linking topic and table into a drill-down and noting no id is needed because the newest file is found by title, but it does not deepen the filtering or slicing parameters further.

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 verb and resource: read the Centre's monthly macro-indicators workbook, and it spells out the 12 subject areas (trade, housing, money, budget, prices) plus the ~100 stacked tables. It does not explicitly name a sibling to distinguish itself from, e.g. am_table or am_inflation, so it stays at 4 rather than 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?

It gives a clear progressive call sequence: no arguments lists topics, `topic` returns the table list, and `topic` + `table` returns data. What is missing is any exclusion or alternative routing (when to use am_inflation or am_ppi instead of this workbook), so it is strong context without explicit 'when not to use'.

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 read-only, idempotent, non-destructive behavior; the description adds valuable return semantics such as monthly_pct, point_to_point_pct, and twelve_month_avg_pct, plus the newer_report edge case. It does not cover rate limits, error behavior, or data revision caveats, so it is useful but not fully rich.

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 retrieval purpose, then groups output measures and parameter guidance in a compact flow with no filler. The dense technical detail is warranted because no output schema is provided.

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?

No output schema exists, so the description carries return-value explanation and does so for all four per-month measures plus newer_report. With 100% schema coverage on inputs and annotations covering safety, an agent has enough information to invoke the 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 baseline is 3, but the description adds cross-parameter constraints: region and group enable breakdowns while province is a distinct all-items series with no index and no groups. The months parameter is only summarized as latest months and is not expanded beyond what the schema already 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?

Opens with a specific verb and resource — Iran's official CPI and inflation from the Statistical Centre of Iran — and names the exact per-month measures. This clearly distinguishes it from sibling price tools such as am_ppi and from the group-list helper am_inflation_groups.

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?

Explains how to choose region and group for a breakdown versus province for a single-province all-items series, including the limitation that province results have no index and no groups. It does not explicitly route the agent to or away from sibling tools like am_ppi or am_inflation_groups, 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the lower bar applies. The description adds genuine value by disclosing the returned metrics (index, monthly change, point_to_point_pct, 12-month average), which matters because there is no output schema. It stops short of noting units, group coverage, or ordering.

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 paragraphs, front-loaded with the action and scope, followed by a compact return-value summary and the routing note. Every clause carries information; there is no 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?

For a two-parameter, annotation-covered read tool with no output schema, the description supplies both the routing rule and the shape of the result, which is the main gap an agent would otherwise face. Minor omissions (units, whether all groups are always returned, default-month behavior already in schema) keep it from a 5.

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%, with both `period` (YYYY-MM format, omit for latest) and `region` (enum of national/urban/rural) fully documented in the schema. The description only reinforces the one-month scope and the `group` reference without adding syntax or edge-case detail, 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?

The description gives a specific verb and resource ('Compare official inflation across CPI groups') and enumerates the group examples (food, housing, transport, health). It also names the sibling that serves a different purpose (am_inflation with `group` for one group's multi-month history), so an agent can distinguish the two 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?

It states the intended use case ('see what drives inflation') and explicitly routes the alternative case to am_inflation with the `group` parameter. The single-month scope constraint versus multi-month history is spelled out rather than left to inference.

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 declare this a safe, idempotent, open-world read, so the bar is lower; the description nonetheless adds real context the annotations cannot: the Statistical Centre survey as provenance, what each rate is measured against (active population vs population 15+), full geographic coverage, and a two-to-three-month publication lag. It does not describe the returned record shape, which matters because no 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?

Three tight sentences, front-loaded with what/scope/ordering, then source and measurement definitions, then freshness and the alternative tool. Nothing is redundant and no sentence could be dropped without losing information an agent needs.

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 two-parameter, annotation-covered read tool with no output schema, the description supplies provenance, definitions, lag and routing to the right alternative. The remaining gap is the returned data shape and the undocumented 'youth_unemployment' option, both of which an agent must infer from the schema alone.

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 3 is the floor, but the description genuinely adds meaning by specifying the denominators behind each measure (percent of active population for unemployment, percent of population 15+ for participation) and by establishing the latest-first ordering that gives the 'quarters' count its direction. It never mentions the 'youth_unemployment' measure, leaving that enum value explained only by 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?

Names a specific verb and resource ('Get Iran's official unemployment and labour-force participation rates by quarter'), states scope (whole country, urban, rural), ordering (latest first), and explicitly separates itself from am_search. An agent can distinguish it from am_inflation, am_gdp or am_population 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?

Gives both a positive condition (labour-force rates) and a negative routing rule: other labour tables such as employment by sector, hours or wages belong to am_search. It does not cover the remaining siblings (e.g. am_population or am_indicators) that might also look plausible to an agent, so it stops 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 cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds real behavior on top: the exact fields returned per mode, all-words matching semantics for `query` on title or summary, and the 4000-character truncation on long item text. Truncation and filter semantics are exactly the kind of detail annotations cannot express.

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 mode split, then details per mode, then use-case routing; every sentence carries information. It is somewhat dense, packing field lists and limits into parenthetical clauses, but nothing 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?

There is no output schema, so the description must describe returns, and it does so for both modes (id, title, summary, GMT time, url; date, categories, text). For a 3-optional-parameter read tool with full annotation coverage, nothing an agent needs in order 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 baseline is 3, but the description adds cross-parameter semantics the schema does not: `id` switches the call from list to single-item mode, and `query` is scoped to list mode with conjunctive word matching. It does not add detail on `count` beyond what the schema's 'newest first' description already 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?

Names a specific verb and resource ('List the latest news and press releases of the Statistical Centre of Iran, or read one item') and explicitly splits the two operating modes by the presence of `id`. The closing clause routes numeric needs to the data siblings, so an agent can distinguish it from am_inflation/am_gdp/am_search 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 clear positive context ('announcements such as census news, interviews and release notes') and an explicit exclusion ('the numbers themselves are in the data tools'). It stops short of naming which sibling to call for data, so the routing is directional rather than precise, which keeps it at 4 rather than 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, and destructiveHint=false, so safety is covered. The description adds material context beyond them: the exact census vintage, the fact that a newer census exists but is not released, and the exact measures returned (total, urban, rural, male, female, households). It does not discuss return format or coverage gaps per province, which keeps it off a 5.

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 core capability, then the data vintage caveat, then the alternative-tool routing. Nothing is repeated from the schema 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 and only one parameter, the description appropriately compensates by enumerating the measures returned and the temporal boundary of the data. It stops short of stating units, count of provinces/counties, or what a county-level record looks like, which would fully close the loop.

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 is already described, so the baseline is 3. The description nonetheless restates the mode switch — omitting province lists all provinces, supplying one lists its counties — which confirms the default behavior an agent needs in order to decide whether to pass the argument.

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 concrete verb and resource ('Get population and households'), names the unit of analysis (province, or county within one province), and pins the source ('Iran's 1395 census'). The agent can distinguish this from am_search/am_table data tools 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 bounds the data to the latest published full census (Aban 1395 = 2016), warns that the 1405 census is unpublished, and routes projection/age-group needs to am_search ('پیش بینی جمعیت') and am_table. This is explicit when-to-use, when-not, and named alternatives.

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 access, so the safety profile is covered. The description adds real value beyond that by naming the returned fields (index with 100 = 1400 base, quarter-on-quarter change, point_to_point_pct, annual_pct) and the ordering guarantee, which matters since there is no output schema. It does not mention data lag or the 60-quarter cap, which would have pushed this to a 5.

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 alternatives — a logical order with no filler. The middle sentence is dense with field names but each one carries information the schema cannot.

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 two-parameter read tool with no output schema, the description covers purpose, return fields, ordering, and sibling routing, which is close to complete. Minor gaps remain around freshness/lag and the maximum quarter window, both of which affect how an agent interprets results.

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 both parameters (sector with its Persian enum-like values, quarters with min/max) are already fully documented in the schema. The description only restates 'by quarter and sector' and adds no format or naming guidance beyond it, 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 and resource ('Get Iran's producer price index (PPI, factory-gate prices)') plus the dimensions of retrieval (by quarter and sector, latest first). It also distinguishes itself from the detailed PPI releases that live in am_search/am_table, so an agent can tell which tool returns the headline series.

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 routing: use alongside am_inflation because producer prices lead consumer prices, and use am_search('شاخص قیمت تولید کننده') + am_table for sub-sector detail instead of this tool. Both the when-to-use and the when-to-use-something-else cases are covered.

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, so safety is covered. The description still adds real behavioral context: the mix of file formats returned, the need for the agent to fetch PDF links externally, and the error behavior for delisted releases. It stops short of describing pagination or field completeness, keeping it a 4 rather than a 5.

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 paragraphs with zero filler: the first states what is returned, the second states when to call it and what to do with the output. The most decision-relevant line ('Use it after am_search') is front-loaded.

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 one required parameter, no output schema, and read-only annotations, the remaining burden is telling the agent what a release contains and how to consume its files — and the description does exactly that. Nothing needed 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% and the schema already documents 'id' as a release id from am_search with an example, so the description cannot add much. Its only extra signal is that the same id is what you pass onward to am_table, which is a useful chaining hint but marginal. 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 ('Get one statistical release from amar.org.ir') and enumerates what comes back: title, topic path, period, downloadable files. That distinguishes it cleanly from am_search (which discovers releases) and am_table (which reads their Excel payloads).

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 sequences the tool: 'Use it after am_search,' and routes each file type to its consumer ('read an Excel file with am_table (passing this id), open the PDF link yourself'). It also flags a failure mode — a removed release returns an error — so the agent knows how to interpret that outcome.

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 and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: unfiltered calls return the newest releases, and every result carries an id that feeds am_release or am_table. It does not mention rate limits, auth, or result size beyond the schema's 25-per-page, which keeps it just short of a 5.

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 sentences, front-loaded with the verb and resource, then usage, then next steps. The enumeration of six ready-made tools is long but earns its place as a routing shortcut; otherwise there is no 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?

For an 8-parameter, all-optional search tool with no output schema, the description covers default behavior, the key result field (id), and the handoff to am_release and am_table. The shape of a result beyond its id is left implicit, which is the main remaining gap.

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 the schema already documents every parameter, including the Persian-language query hint and the enum meanings. The description restates the query language and explains that source and data_type narrow by the portal's own system and type, but it leaves the overlap between kind and data_type unresolved, adding little 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 verb and resource: search the Statistical Centre of Iran catalog of releases (tables, time series, reports). It also distinguishes itself from siblings by naming am_release and am_table as follow-ups and listing the ready-made tools (am_inflation, am_labour_force, etc.) that make searching unnecessary.

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 conditions (find a release by Persian title words, year, publication frequency, type) and an explicit alternative path: 'Ready tools need no search' followed by the concrete tool names. It also says what happens with no filters and which tool to call with the returned id, so routing is fully determined.

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?

Beyond the annotations (readOnly, idempotent, non-destructive, open-world), the description discloses the two-step discovery-then-read flow, the exact row shape including excel row numbers, that empty rows are removed, the 25 MB refusal limit, and that `cols` appears in the answer. That is a rich behavioural picture that the annotations alone would not 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 first sentence states what it does and the scope; the second paragraph walks the call sequence in order. No filler, and the discovery-first instruction 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 8 parameters and no output schema, the description still explains the return shape (arrays starting with the excel row number) and the `cols` field, plus the size ceiling. An agent has everything needed to make a correct first and second call.

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 already 100%, so the baseline is 3, but the description adds real meaning: `find` matches any cell text such as a province or group name, `offset` is for paging, and `col_offset` matters because newest values in wide monthly series sit at the right end. It does not explain `max_rows`/`max_cols` interplay 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?

"Read an Excel table of a statistical release as compact rows" gives a concrete verb and resource, and the parenthetical "works for any release with an xlsx/xls file" signals it is the generic reader. It stops short of naming the specialized siblings (am_gdp, am_inflation, am_labour_force) that could serve the same data, so an agent must infer the division of labour.

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?

Strong procedural guidance: call first with only `id` to get the sheet list, then pass `sheet`; use `find` for a province or group, `offset` to page, `col_offset` for wide monthly series, and files over 25 MB are refused. The only gap is that it never says when to prefer this generic reader over the topic-specific sibling tools.

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