UpGrowth: business data for Algeria, Tunisia and Morocco

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

With readOnlyHint/openWorldHint already set, the description still adds real behavioral context: it discloses that results are estimates from public texts and not advice, flags an unresolved legal question (À VÉRIFIER), warns to read data.limitations before quoting, states that Tunisia requires an API key (key_required), and describes the return shape (yearly/monthly/quarterly with inputs and limitations). It stops short of noting rate limits or error behaviors beyond key_required/country_not_available.

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 enormous paragraph that mixes Algeria's full legislative history (decrees 22-121, 20-240, 26-257), Tunisia, and Morocco, with legal citations and figures that do not help an agent select or invoke the tool. Much of the Tunisia/Morocco content duplicates the already-100%-covered schema descriptions, and the front-loading dissolves after the first sentence.

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 14-parameter, three-country, 13-regime tool with no output schema, the description is largely complete: it substitutes for the missing output schema (yearly/monthly/quarterly plus the figures used and limitations) and covers regime selection, auth requirements, and per-country caveats. It is only mildly incomplete in that the name/scope mismatch and the legal-history digressions leave the agent to disentangle DZ/TN/MA behavior.

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 parameter descriptions are unusually thorough, so the baseline is 3. The description does add cross-parameter coupling (revenue needed for the three Algerian regimes, ignored for AUTO_ENTREPRENEUR/PREMIERE_ANNEE; income_class required with INDEPENDANT_NON_AGRICOLE), but most of that is already restated in the schema, so it does not materially exceed the structured data.

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 opening sentence gives a specific verb and resource (estimate the yearly CASNOS contribution for 2026) and names the sibling it is not (calculate_ifu handles the Tunisian flat tax). However, the name/title promise CASNOS (Algerian only) while the description silently expands scope to Tunisia (CNSS) and Morocco (AMO/pension), so the top-line framing understates what the tool actually does.

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 description lists which regime fits which country and notes that other Tunisian schemes are 'regimes of the same tool' while the Tunisian flat tax is calculate_ifu. That one explicit alternative-routing is useful, but there is no clear when-to-use/when-not framing, and the 'Give the regime and, for most regimes, the amount' instruction is buried mid-paragraph.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the return shape (inputs, base, rate, minimum-applied flag, result, limitations), instructs the agent to read data.limitations before quoting, flags 'estimate not tax advice', and explains key_required/country_not_available behavior per country.

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, which is good, but the body is a single dense paragraph interleaving Algeria, Tunisia and Morocco rules, with clauses that duplicate the schema's parameter descriptions. It is information-rich but poorly structured and longer than 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 an 11-parameter, no-output-schema tool spanning three countries and multiple regimes, the description supplies the output fields, the limitations caveat, country availability, auth requirements and currency behavior. An agent has everything needed to call it 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 description coverage is 100%, so the schema already documents every parameter's meaning, enums and defaults. The description adds some cross-cutting context (currency-by-country, activity required/ignored per regime) but largely restates what the schema carries, so the baseline 3 stands.

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 (Estimate) and resource (the IFU flat tax of Algerian micro-businesses) up front, and extends the scope explicitly to Tunisia and Morocco. It is clearly distinguishable from siblings such as calculate_casnos, which it names, and calculate_ifu's regimes make its role unambiguous.

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 country- and regime-specific conditions for use (regime ae/general/forfait, activity required, zone required, API key needed for TN/MA) and warns that Algeria eligibility is not tested. It does not explicitly route the agent to a sibling for eligibility checks, so it falls 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 cover only readOnlyHint and openWorldHint, yet the description adds substantial behavioral context beyond them: fees are State fees only and not a quote, unpriced steps are flagged rather than guessed, and Tunisia/Morocco require an API key. This is exactly the kind of disclosure an agent needs to avoid misrepresenting 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?

Purpose is front-loaded, but the body is very long and enumerates every form and every registration step for three countries, which is more inventory than an agent needs to select and call the tool. The State-fees-only constraint is restated, adding redundancy.

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 fully carries the burden of explaining what is returned: per-country form lists, partners, capital, and per-step official fees with currency. It also covers multi-country scoping and API-key prerequisites, leaving no material gap for correct invocation.

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% for both parameters, so the schema already documents lang and country semantics, including the country_not_available and key_required outcomes. The description reinforces the country behavior but adds no format or syntax detail beyond the schema, matching the baseline 3.

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 (lists legal forms to create a company) and enumerates the exact content returned: partners allowed, minimum capital, and official State fees per creation step. It also differentiates itself from the sibling search_jo_text by naming the boundary of its own coverage.

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 guidance: 'never say a form does not exist because it is missing here: check search_jo_text,' and explains that only DZ answers without an API key while TN/MA return key_required. It lacks an explicit 'use this when you need X vs Y' framing beyond the one alternative and the auth precondition.

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=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the DZ-default / TN-MA-key-required auth behavior and the failure modes (country_not_available, key_required). It does not, however, describe pagination or result-size behavior. Given annotations carry the safety burden, the added auth/error detail lands this at a solid but not exceptional level.

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 what the tool returns and who consumes it next. The country variants are packed densely but each clause is functional; no filler or tautology.

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 carries the return burden and does so reasonably: chapters with two-digit codes plus titles, in a chosen language. It also states dataset limits, which prevents wrong expectations. Pagination/ordering behavior is the only notable 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 lang, country, and section are all documented in the schema, including the enum, defaults, and per-country error behavior. The description restates the section format ('two-digit codes') and the section example but adds little syntax or format detail not already present. Baseline 3 applies when the schema does the heavy lifting.

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 (list) and resource (chapters of a customs tariff section) with the exact granularity ('two-digit codes ... with their titles'). It also implicitly separates itself from customs_tariff_sections, which it names as the prerequisite sibling, so an agent can tell the two apart 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?

Explicitly says 'Use it after customs_tariff_sections', giving ordering and prerequisite. It also gives negative scope ('holds no duty rates and no tariff lines below the chapter level') and per-country conditions (TN/MA need an API key), which tells the agent when this tool is and is not the right choice.

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 only cover readOnlyHint and openWorldHint, but the description discloses substantial behavioral detail: meta.sources attribution, meta.status_note marking titles as 'À VÉRIFIER', API key requirements (TN/MA need keys, only DZ answers otherwise), and the country_not_available/key_required error outcomes.

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 and returned fields, then per-country behavior and limitations. Some redundancy with the schema's country parameter description on API keys and error codes, but each sentence generally earns its place and no filler is present.

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 explains the returned fields and the boundaries of the dataset (no duty rates, no tariff lines below chapter level), plus attribution and verification metadata. An agent has enough to call and interpret the result 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 schema already documents lang and country fully, including defaults, enum values, ISO code format, and error behavior. The description largely restates the same country/key semantics rather than adding new meaning, 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 ('List the sections of the Algerian customs tariff, the first level of the harmonized system classification of goods') and enumerates the returned fields (Roman numeral, title, chapter range). This clearly distinguishes it from the sibling customs_tariff_chapters tool.

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: 'Use it to locate a family of products before listing the chapters of a section,' naming the downstream alternative. Adds when-not guidance ('This dataset holds no duty rates and no tariff lines below the chapter level') and per-country conditions for TN/MA versus DZ.

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 only declare readOnlyHint/openWorldHint; the description adds real behavior: it errors when the code does not exist, it returns country_not_available for unsupported datasets, and it requires an API key for TN/MA (key_required). It also flags that details.jo_check must be read before quoting an authority or legal text — substantive operational guidance not derivable from annotations.

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, but the description is a single dense block that mixes return-field enumeration, jo_check caveats, and three countries' parameter rules. Much of the return-value detail is useful, yet the lack of any structural separation makes it hard to scan for a fairly simple lookup.

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 the return-value burden and discharges it fully: status, trilingual labels, sector/group, URL, published French text, plus the jo_check correction fields. Error and auth conditions are also covered, so an agent has everything needed 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 description coverage is 100% and the parameter docs already spell out the per-country code formats, the lang enum and the country default/error behavior. The prose largely restates this, so it adds little beyond the schema; 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 activity of the Algerian CNRC nomenclature by its six-digit code') and then enumerates exactly what the record contains. It is clearly distinguished from search_activity_codes, which is named as the upstream sibling.

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?

Explicit routing: 'Use it when the user already gives a code, or after search_activity_codes.' It also gives per-country invocation rules (TN four-digit NAT 2009 or A1-/A2- authorisation codes; MA four-digit NMA 2010 code), so the agent knows which form to pass in each case.

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 readOnly annotation, it discloses error behavior for non-existent codes, country availability rules (only live countries answer; without an API key only DZ answers), and key_required/country_not_available outcomes. It also warns against misapplying the ordinary 5 million DZD ceiling to micro-importation and directs the reader to regime.note, adding substantial behavioral context.

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 purpose is front-loaded in the first sentence, but the remainder is a very dense, parenthetical block mixing Algerian, Tunisian, and Moroccan rules. While most details are potentially useful, the description is far longer than needed and would benefit from tighter grouping and shorter 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?

With no output schema and three parameters, the description does the heavy lifting by describing what is returned (labels, domain, optional regime object), error cases, country-specific behavior, and legal caveats. It is complete enough for an agent to invoke and interpret the tool correctly across all supported countries.

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 structured parameter descriptions already carry the detailed semantics for code, lang, and country. The description mostly repeats the schema's code examples and adds no parameter-level detail beyond what is already there, so the baseline of 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?

The first sentence states the exact verb and resource: get one ANAE activity by six-digit code, returning labels in French, Arabic, and English. It clearly distinguishes this from search_anae_activities and explains its broader country-specific uses for TN and MA, so an agent can identify the tool without ambiguity.

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 says to use it when the user gives a code or after search_anae_activities, and gives precise conditions for Tunisia (pass the key regime) and Morocco (pass a profession key or regime). It also warns about cases where the official list is not loaded and about not treating absence as exclusion, covering when-not-to-use implications.

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?

With readOnlyHint and openWorldHint already declaring the safety profile, the description adds genuine non-obvious context: the data is refreshed from Algérie Poste daily, it covers Algeria only, and it discloses geospatial and address fields returned. It doesn't cover rate limits or auth, but the freshness and scope notes are real added value.

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?

One front-loaded sentence that leads with the core action and then unpacks the return payload; the parenthetical field lists are long but each item earns its place by pre-empting a schema lookup. Slightly dense, but 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?

No output schema exists, so the description carries the full burden of describing return values, and it does so exhaustively (post office names in French and Arabic, class, address, postal codes, GPS; ATM name, status, postal code, GPS). Combined with the schema's error-code documentation, an agent has what it needs to call and interpret the 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 both optional parameters (lang, country) and the code are fully documented in the schema, including enum values and the country_not_available/key_required behaviors. The description adds the 'four-digit, from list_communes' framing for the code but does not extend the optional parameters, 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 ('Get'), resource ('one commune of Algeria'), and lookup key ('by its four-digit code'), then enumerates exactly what is returned (names, wilaya, postal codes, post offices, ATMs). This clearly separates it from siblings list_communes and get_wilaya.

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 parenthetical '(from list_communes)' tells the agent where the required code comes from, and 'Algeria only' plus the notes about TN/MA availability set scope. It gives clear usage context but no explicit when-not guidance or alternative tool routing.

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 only say readOnly/openWorld=false; the description adds the auth tier (no key = current year plus two), the country gating, the 20,000-character part chunking with part/parts/chars continuation, the 50-item truncation on named_in_titles with a truncated flag, null semantics for missing fields, and the [[? ... ?]] scan-uncertainty convention. It also explicitly warns that status_hint is read from titles alone and is never a statement of whether the act is in force or repealed.

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?

Purpose is front-loaded correctly, but the body is one dense run-on paragraph with deeply nested parentheticals that enumerate return fields. With no output schema the information is necessary, yet the packing makes it hard to scan and the output-field inventory competes with the calling instructions.

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 9-parameter, zero-required, output-schema-less tool, the description covers the return shape (type, number, title, page, links, text parts, named_in_titles, amends, status_hint), error cases, pagination, and access tiers. An agent has everything needed to call it 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 already 100%, so the baseline is 3; the description earns above that by explaining the part-chaining loop ('ask the next part to read on') and the number-plus-type disambiguation as a coherent lookup recipe rather than a field list. Much of the rest restates what the schema already documents.

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 full text of one act of the Algerian Journal Officiel'), plus scope ('published since 1962') and jurisdiction ('Algeria only'). It also distinguishes itself from the retrieval path by naming the sibling that supplies the identifiers ('as search_jo_text returns them').

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 preconditions: obtain identifiers via search_jo_text, supply type when a law and decree share a number, and check named_in_titles before quoting since the text is not consolidated. It also states the no-API-key restriction and the country_not_available outcome. What it never does is contrast itself with the closest unmentioned alternative, get_jo_issue, for issue-level reading.

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 only say the call is read-only and closed-world; the description adds real behavioral detail: data.sommaire may be null with a reason in data.note, pre-2002 summaries come from scanned issues (source, titles_held_back, complete), Morocco returns supplements with no summary, Tunisia gives no PDF link, and older Algerian years return key_required without a key. That is exactly the non-obvious failure and payload context an caller needs.

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?

Purpose is front-loaded and every block is informative, but the passage is long for a 4-parameter tool and repeats content already in the schema (the continuous Morocco series example 7522, the within-year Tunisia example 97, and the free-tier restriction on year). The country paragraphs also repeat 'data.sommaire is always null' twice, which could collapse into one clause.

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 carries the full return-shape burden, and it does: links, sommaire structure, note, source, titles_held_back, complete, supplements, and null-summary cases per country. Combined with existing annotations, an agent has everything needed to call it and interpret the response.

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 enum count is 1, so the schema already explains lang, year, number and country, including the same Morocco/Tunisia number conventions. The description largely restates those conventions rather than adding new semantics, so the baseline of 3 applies despite the added examples.

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 issue of the Algerian Journal Officiel by year and number') and immediately enumerates what it returns: edition links plus the summary of published texts. It is clearly separable from list_jo_issues (which finds numbers) and get_jo_act/search_jo_text (which look at texts).

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?

'Use it to find which texts an issue published' gives the operative context, and the description points at list_jo_years and list_jo_issues for the parameters, plus the free-tier rule (only Algeria, current year and two before). It stops short of an explicit 'use search_jo_text instead when you only know a keyword' exclusion, so not 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 only supply readOnlyHint and openWorldHint, so the description carries the real behavioral load and does so: it discloses the API-key gate for TN/MA, that the Algerian list is incomplete and which categories are excluded, and that missing entries must not be read as non-existence. That auth constraint plus data-coverage caveat is exactly the beyond-annotations context an agent needs.

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 purpose is front-loaded and the closing sentences carry the routing and auth guidance, but the middle is a dense per-country enumeration whose internal rate detail (34.5 % split, decree references) reads more like output documentation than definition. Effective but bloated for a two-parameter lookup tool.

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 multi-jurisdiction reference tool with no output schema, the description is complete: it summarizes the shape of the answer, names supported countries, flags the incompleteness of the Algerian dataset, and points to the estimate tools. An agent has everything needed to call it correctly and interpret 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% and both parameters (lang, country) are fully documented in the schema with defaults, enum and the country_not_available/key_required behavior. The description reinforces the DZ default and names the supported countries, but adds little the schema does not already state, so baseline 3 is right.

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 social contributions and payroll levies in a country in 2026') and enumerates exactly what is returned per jurisdiction (base, legal source, official page read on). An agent can distinguish this revenue/levy reference tool from calculate_casnos or get_tax_rates 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?

Explicitly routes usage: 'For an Algerian estimate use calculate_casnos and calculate_ifu' names the alternatives and the condition, and it states 'Tunisia and Morocco need an API key'. It also warns when not to conclude absence ('never say a contribution does not exist because it is missing here: search the Journal officiel'), which is unusually actionable routing 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 read-only and closed-world, and the description layers substantial extra context on top: explicit error codes (country_not_available, key_required without an API key), data-quality flags (À VÉRIFIER / TO VERIFY on open points), and a clear statement of what is deliberately omitted and must not be quoted. That is well beyond what the annotations 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 purpose is front-loaded, but the opening sentence runs roughly 300 words and packs exhaustive legal citation (article numbers, decree dates, fee amounts, tax articles) that belongs in the returned data, not the tool selector. The density actively harms scannability, so this is over-specification rather than conciseness.

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 four optional parameters, the description carries the full burden of saying what comes back, how items are annotated, which categories exist, and what happens on out-of-scope input or missing credentials. Nothing an agent needs in order to call this 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 description coverage is 100% and both enums are documented in the schema, so the description's restatement of q examples ('redevance, transfert, label') and the full treatment enum list is largely redundant. It adds no syntax, format or interaction detail beyond what the structured fields already provide, 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 concrete verb and resource ('Get the business support schemes and investment rules of Algeria as the Journal officiel sets them') and enumerates the exact domain it covers (law 22-18 and decrees, labels, NESDA, CNAC), which no sibling such as search_jo_text or get_jo_act duplicates. An agent can tell what this returns 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 operative guidance for querying (q and treatment filters, with examples) and dictates how to treat results ('do not quote figures' for micro-credit, NESDA and CNAC financing; country DZ only, others return country_not_available). However, it never names an alternative tool or the condition that should route the agent elsewhere.

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 readOnlyHint/openWorldHint annotations, the description discloses data provenance (2026 DGT codes, checked 20 October 2026), a behavioral rule (holidays shift deadlines to the next working day), completeness limits (not exhaustive; extensions absent), and error semantics (country_not_available, key_required without an API key). This is unusually rich behavioral disclosure.

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 is front-loaded and useful, but the body is a ~300-word enumeration of every individual obligation, article number and penalty percentage. That content belongs in the tool's returned data, not in a description whose job is selection and invocation; it buries the operational guidance.

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 the return shape, and it does: each item includes who must file, the deadline text, its article and the official source. Combined with filter semantics and error behavior, an agent has enough to call and interpret the result 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 all four parameters are already documented. The description adds a couple of q examples ('IFU', 'CNAS') but mostly restates the treatment enum verbatim, so it does not meaningfully extend the schema. 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 opening line names a specific verb and resource ('Get the legal filing and payment deadlines of businesses in Algeria') and immediately enumerates the categories it covers, so an agent can distinguish it from siblings like get_tax_rates or get_tax_code_article without reading 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 gives clear context: filter by q and treatment, Algeria only, with an explicit pointer to list_countries for other datasets. It also warns the list is not exhaustive and that DGI extensions are excluded. What's missing is explicit routing against the closest siblings (e.g., when to use get_tax_code_article instead for full article text).

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 only declare readOnlyHint and openWorldHint, so the description carries the rest and does so richly: the full response shape (title, edition, PDF link, id, heading, status, text with line-broken paragraphs, notes, prev/next ids, citation line), the fact that abrogated articles contain only the word 'Abrogé', and the not_found error that lists nearest article numbers.

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?

Purpose and name are front-loaded in the first clause, and the long return-field enumeration is justified because no output schema exists. It is a single dense run-on paragraph, however, and the field list could be tightened without losing 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 four parameters, no output schema and no destructive behavior, the description still covers return values, error semantics, language/country constraints, sibling routing and the authoritative-source caveat (DGI edition vs Journal officiel). Nothing an agent needs 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 the baseline is 3; the description adds the article-number syntax tolerance ('Art., accents and case are ignored') with concrete examples (150, 282 quater, 300-3, 2 bis). It slightly conflicts with the schema on country handling — the description says other countries return country_not_available while the schema says TN/MA return key_required — which costs a point but does not obscure the practical constraint.

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 article of one of the six tax codes of Algeria in full', and enumerates the exact code set (cidta, cpf, ctca, ce, cii, ct) with a pointer to search_tax_code for their meanings. An agent can distinguish it from search_tax_code and get_jo_act 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 explicit when-to-use ('read an article before quoting it, and name it by code and number') plus the alternative route for finance laws ('use get_jo_act to read a finance law that a note names'). It also states the tool is Algeria-only, so the caller knows when not to call it.

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 readOnlyHint/openWorldHint annotations, the description discloses the API-key requirement per country, the country_not_available and key_required failure modes, the null fields for Tunisia, and the 'reading of public texts, not tax advice' disclaimer. That is meaningful behavioral context an agent could not infer from the structured fields.

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 clause, but the rest is a single sprawling run-on sentence with deeply nested parentheses about Algeria and Morocco that is hard to parse. Detail is disproportionate to the simple two-parameter read operation.

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 carries the burden of describing return contents, and it does enumerate the returned rate categories, the per-entry legal article, effective date and source page. It is dense but covers what an agent needs for this lookup; only the exact response shape remains unspecified.

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 lang and country are already fully documented in the schema, including defaults, the ISO alpha-2 pattern, and the error behavior. The description adds no new parameter syntax or format detail beyond what the schema provides, 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 the business tax rates in force in 2026 for a country') and enumerates the exact contents returned (corporate income tax, VAT, withholding, plus country-specific personal_income_tax and flat_tax). An agent can distinguish this from siblings like get_vat_regimes or get_social_contributions 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 real operational context: DZ is the default, only DZ answers without an API key, TN and MA return key_required, and list_countries shows which countries/datasets are live. It also points to calculate_ifu for IFU eligibility. It stops short of an explicit 'use this instead of X when Y' routing statement against the tax siblings.

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=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful operational context beyond that: 'Algeria only (country DZ); other countries return country_not_available' and the key_required behaviour for TN/MA, plus the note that abrogated rules are excluded by default.

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 purpose is front-loaded, but the body is a sprawling wall of text that dumps the entire substantive VAT content — article numbers, abrogated points, individual exempt goods, historical changes — most of which is answer content rather than selection or invocation guidance. Much of it does not earn its place in a tool description.

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, and the description does compensate by describing what each item carries (legal basis, article, finance law, official text read in) and by covering scoping, error cases and default filtering. An agent has enough to call it correctly, though the sheer volume makes the operative guidance harder to extract.

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 q example and the treatment enum values. The description's 'Filters: q ..., treatment ..., in_force ...' paragraph largely restates that structured content, adding only a sample query word ('formation'), 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 the VAT (TVA) regimes of Algeria in force in 2026' — and immediately enumerates what a returned item contains (legal basis, article, finance law, official text). It is clearly distinct from siblings like get_tax_rates or get_tax_code_article, which cover rates or single articles rather than the full regime list.

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 decision rule: 'Use it before saying which VAT rate applies to an activity: an activity that is not in the 9 % list or the exemptions is taxed at 19 %, unless the business is under the IFU or the auto-entrepreneur status.' That is strong when-to-use guidance, but it never names the alternative tools (e.g. calculate_ifu, get_tax_rates) or states when this tool is the wrong choice.

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 only declare readOnlyHint and openWorldHint, but the description adds real behavioral context: unknown codes error out, only live countries answer, TN/MA require an API key, and specific failure codes (country_not_available, key_required) are named. That is material information an agent cannot get from the annotations.

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 action and code format, then branches by country. It is somewhat long and repeats per-country code examples already present in the schema, but with no output schema the field enumerations earn their 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 per country (names, capital, region, population, CNRC/CASNOS offices; ISO 3166-2, INS code, three-language names, chief town). Auth, error behavior and the code-discovery alternative are all 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 the schema already documents code, lang and country in detail including the same examples (16 for Alger, TN-11, MA-06). The description largely restates that per-country code semantics rather than adding new syntax or format meaning, 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 one Algerian wilaya by its two-digit code') and immediately scopes the tool across three countries with distinct semantics. It is clearly distinguishable from the sibling list_wilayas, which it names as the code-discovery route.

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 entry condition (a two-digit code, obtained via list_wilayas), states the failure mode ('returns an error when the code is unknown'), and notes that TN/MA need an API key. It routes to a sibling but does not state an explicit when-not-to-use case beyond 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?

Annotations only declare readOnlyHint and openWorldHint, so the description carries the operational burden and does so well: no-API-key truncation to 10 rows, offset must be 0 without a key (no paging), only DZ answers unauthenticated while TN/MA return key_required, non-covered datasets return country_not_available, and the data is refreshed daily. It also discloses the 1,540-vs-1,541 count discrepancy between the source and the law.

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 purpose is front-loaded, but the core sentence is a single run-on enumeration of every returned field, and domain trivia such as 'décret exécutif n° 91-306' does not help an agent select or invoke the tool. It is information-dense rather than concise, and harder to scan than it needs to be.

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 the return shape itself, and it enumerates every field (commune code, FR/AR names, wilaya, wilaya_2026, postal codes, post-office/ATM counts, daïra). Combined with filter semantics and the API-key/pagination caveats, an agent has everything needed for a 7-parameter, zero-required 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 baseline is 3, but the description adds real meaning: it ties wilaya numbers 59–69 to loi n° 26-06 and lists the 2026 slugs, explains that q ignores accents and accepts a postal-code prefix, and clarifies daïra includes Algiers' circonscriptions administratives. Some of this duplicates the schema, keeping it below a 5.

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 (List) and resource (communes/baladiyas of Algeria) and enumerates the fields returned, including the 2026-wilaya and daïra dimensions. An agent can tell this apart from get_commune (single lookup), list_wilayas and list_dairas 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?

Explicitly names three use cases: checking a commune exists, finding postal codes, and listing the communes a delivery zone covers, plus which filters to combine (daira, wilaya, q). It lacks an explicit contrast with the sibling get_commune for the single-record case, so it stops short of full when-to-use/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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses the status semantics (live = data served, planned = announced but not served) and the free_access flag semantics (true when no API key is needed, false when one is required, today Algeria only). This is exactly the kind of auth/availability context annotations cannot 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?

Purpose is front-loaded in the first clause, but the body is a very long enumeration of every country's datasets and mapped tools, and the critical 'Use it first...' guidance is buried at the end. The dataset inventory is relevant but oversized for a one-parameter list tool, so it reads as dense rather than wasteful.

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 explain the return shape — and it does, spelling out every field per country plus the status and free_access flags. Combined with the usage guidance and the note that no country argument is accepted, an agent has everything needed to call it 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 description coverage is 100% and the single optional 'lang' enum is fully documented in the schema (fr default, ar, en), so the schema carries the parameter burden. The description's only addition is 'It takes no country, only the optional lang', which is a mild restatement of what the schema already shows. 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?

Opens with a specific verb+resource ('List the countries this server has business data for') and enumerates exactly what each entry contains (ISO code, names, languages, currency, status, datasets). It is unmistakably distinct from every sibling (list_wilayas, list_jo_years, get_activity_code, etc.), which are country-specific lookups. An agent can route to it 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?

States explicitly when to call it: 'Use it first to see which countries and datasets exist before asking another tool for a country, or after a call came back country_not_available.' It further maps each dataset to the sibling tools that serve it (list_jo_years/get_jo_issue, search_activity_codes, calculate_ifu, etc.), giving concrete routing guidance rather than leaving alternatives implicit.

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 only declare readOnlyHint and openWorldHint; the description adds substantial beyond that: the unauthenticated 10-row cap, the requirement that offset be 0 when unauthenticated, the country gate where only DZ answers, the special Algiers circonscription administrative case, and the Larbaa no-post-office edge case.

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?

Purpose and return shape are front-loaded, but the definition is one long run-on sentence burdened with full legal citations (décret exécutif n° 91-306…, décret présidentiel n° 2000-45) that are hard for an agent to scan. The procedural detail is useful but packed rather than structured.

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 still conveys the return shape (daïras with communes, codes, names), the meta.sources and meta.total fields, pagination behavior, and the auth-dependent limits. For a filtered-list tool this is complete enough to invoke 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%, so the schema already documents every parameter including enums, defaults, and limits. The description restates wilaya (1 to 69) and q (accents ignored) but adds no new syntax or format 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?

States a specific verb+resource (list daïras of Algeria) and precisely what each row contains (communes with four-digit code and name). It is clearly distinguishable from siblings like list_communes, list_wilayas, and get_commune, and adds authoritative scope (553 daïras, 1,541 communes).

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 filtering guidance ('filter by wilaya (1 to 69) and q, accents ignored') and constraints ('Without an API key, at most 10 rows', 'Algeria only'). It does not, however, explicitly name an alternative tool or state when to prefer a different sibling such as list_communes.

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=true and openWorldHint=false, and the description adds genuinely useful behavior detail: TN and MA require an API key, unsupported countries error out, roles lacking a Journal officiel text are marked TO VERIFY, and each Algerian role cites its establishing act. The remaining gap is that it doesn't say what an error or empty response looks like for an unavailable country.

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 is well front-loaded, but the body then enumerates the actual answer contents — CNRC, AAPI, DGI, CNAS, CASNOS, ONS, decree numbers, Moroccan CRI/OMPIC/HCP — which an agent cannot use for selection or invocation. These enumerations constitute most of the description and crowd out the operational guidance.

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-optional-parameter read-only list with no output schema, the description covers supported countries, the default, the API-key constraint and the fact that no filter applies, which is everything needed to call it correctly. It does not describe the shape of a response entry, but that is minor given the enumerated contents.

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 `lang` and `country` are already fully documented with enum, default, pattern and the country_not_available/key_required behavior. The description restates the DZ-default and the per-country coverage but adds no syntax or semantics beyond the schema — 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 opening sentence gives a specific verb (List) and resource (key public bodies a company deals with in a country) plus what each entry contains (official website, one-line role, source page). It is clearly distinct from siblings such as list_countries, which enumerates available datasets rather than bodies.

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?

"Use it to find which body handles a formality" gives a concrete triggering scenario, and the closing note that the list takes no filter sets expectations. It does not explicitly state when to use list_countries instead, though the schema does; the description itself stops short of naming 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 only declare readOnlyHint/openWorldHint; the description adds genuinely new behavior: error on empty year, key_required responses for TN/MA and for older DZ years without a key, 10-issue cap signalled via meta.truncated, and pdf_url=null for Tunisia. These are operational traits the agent could not infer from annotations or 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?

Front-loaded with the core action and the per-country behavior is organized in parallel clauses, with the sibling routing and quota caveats at the end. It is long, and the API-key/paid-plan warning is repeated from the year parameter's own schema text, which is minor waste but the content is largely load-bearing.

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, and the description compensates by enumerating exactly what is returned per country (issue number, publication date, edition availability with pdf_url, supplement suffixes). Combined with the free-tier and truncation notes, an agent has everything needed to call and interpret 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 schema already documents country codes, the per-country start years (1912/1956/1962) and the lang enum. The description restates the same year ranges and country mapping rather than adding new parameter semantics, 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?

Specific verb plus resource ('List the issues of the Algerian Journal Officiel for one year') and it spells out exactly what each returned record contains. It also differentiates the three country datasets, so an agent can distinguish it from get_jo_issue, list_jo_years and search_jo_titles immediately.

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 usage: 'Use it to find the number of an issue, then get_jo_issue to see what the issue contains', and points to list_jo_years for discovering covered years. It also states failure conditions (error when no issue is indexed) and the free-tier limitation, which tells the agent when this tool will not serve the need.

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 give readOnlyHint=true and openWorldHint=false, and the description goes well beyond that: it discloses the free-tier limitation per country, the meta.free_years escape hatch, and the specific error codes (country_not_available, key_required). It also describes the return payload per country (issue counts, last issue number, French/Arabic edition coverage, summary counts).

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?

Purpose and the 'use it first' directive are front-loaded, and the per-country paragraphs carry real information about differing coverage dates and return fields. However, the Morocco and Tunisia passages repeat country semantics that the schema's country parameter already states, making it longer than strictly needed.

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 enumerating the returned fields per year (issue count, last issue number, bilingual edition counts, summary coverage). Combined with the auth/error behavior, an agent has everything needed to call this 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% and both parameters are already fully documented with enums, defaults and country semantics. The description's 'Takes only the optional lang and country' restates the schema rather than adding new meaning, 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 ('List the years covered by the index of the Journal Officiel') and immediately scopes it to three named gazettes. It is clearly distinguishable from siblings like list_jo_issues and search_jo_titles, which operate at issue/title granularity rather than year granularity.

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?

Explicit sequencing: 'Use it first, to see which years exist before listing the issues of a year' names both the when and the downstream tool. It also documents the precondition that without an API key only Algeria answers and that TN/MA return key_required, which is actionable routing 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?

Beyond the readOnlyHint/openWorldHint annotations it discloses key operational traits: 'Tunisia and Morocco need an API key,' and no-key behavior (TN/MA return key_required), plus the country_not_available failure mode. This is meaningful behavioral 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?

Purpose is front-loaded, but the body is a dense wall of legal provenance (loi n° 26-06, décret présidentiel 26-206, Journal officiel numbers, in_place_by deadlines) that does not help an agent select or invoke the tool. Much of it fails the 'every sentence earns its place' test.

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 thoroughly by enumerating the returned fields per country (code, ISO/INS codes, trilingual names, capital/chief town, region, population, CNRC/CASNOS office details). An agent knows what to expect back and which auth is required.

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 lang and country are already documented in the schema. The prose largely restates country routing (DZ/TN/MA) and language choice rather than adding syntax or edge-case detail beyond it, 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?

The opening sentence names the specific resource and scope (wilayas/provinces of Algeria, plus TN governorates and MA regions) with a clear list verb. An agent can distinguish it from the singular get_wilaya and from list_communes/list_dairas 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?

It gives concrete use cases: 'turn a wilaya code into a name or the reverse, or to find the local offices for a company registration or a CASNOS affiliation,' and states the list takes no filter. It does not explicitly name get_wilaya as the single-record alternative, so the when-not is only implied.

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 only declare readOnlyHint and openWorldHint, but the description discloses a great deal beyond them: unauthenticated callers get at most 10 rows with meta.truncated, paging is impossible without a key (offset must be 0), TN and MA require a key, and status semantics differ per country with not_determined as a real state. It also warns that a truncated page can hide a regulated or blocked code.

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?

It is front-loaded with the core purpose, but the body sprawls into repeated status explanations across three country paragraphs plus a restatement of the truncation caveat. The density of legal citations and per-country caveats makes it hard to scan, and some sentences duplicate schema content.

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 eight-parameter, three-country, no-output-schema search tool, the description covers return shape (code, status, labels in three languages, sector, group, upgrowth.dz URL, meta.total), authentication effects, pagination, and per-country data caveats. Nothing an agent needs to invoke or interpret it responsibly 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 the schema already carries most parameter meaning; the description nonetheless adds value by tying parameters together, e.g. list=authorisations being Tunisia-only and ignored elsewhere, and country gating which datasets answer. It repeats some schema content (status definitions, sector codes), keeping it short of a 5.

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 (search) and resource (the CNRC nomenclature of commercial activities, six-digit codes) and scopes it across three datasets. It explicitly distinguishes itself from get_activity_code, which 'adds details.jo_check', so an agent can tell the two siblings apart 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 enumerates the concrete jobs the tool serves: find the code of an activity described in French, Arabic or English; read a code's CNRC status; browse a sector's activities. It also states when to escalate (get_activity_code) and how to avoid a false 'free' conclusion after a truncated result, which is explicit 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?

Far exceeds the annotations (readOnlyHint, openWorldHint). It discloses API-key gating, a 10-row cap without a key, meta.truncated/meta.total semantics, that offset must be 0 without a key, that Morocco returns excluded professions with no codes, and that Tunisia returns only a regime record and absences are never proof of ineligibility.

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 primary purpose before the per-country caveats. It is long and dense, but nearly every sentence carries operational information an agent needs; the volume is justified by the three-country branching, though paragraph form makes it heavier than ideal.

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 fully carries the return contract: code, labels, domain, key, status, legal basis, and the meta.total/truncated fields. The API-key and pagination behaviors are covered, leaving nothing an agent needs in order to call and interpret 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% and each parameter is thoroughly documented in the schema itself (q matching rules, limit/offset caps, domain pattern, country codes). The description reinforces a few constraints (10-row cap, offset=0 without key, domain unused for TN) but adds little beyond the schema, 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 (search) and resource (list of activities open to the auto-entrepreneur status in Algeria), plus the legal basis and exclusions that define the list. It clearly distinguishes the tool from get_anae_activity (which reads a single activity's regime) and from the generic code search 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 states the use case: 'check whether an activity can be practised as an auto-entrepreneur and to find its six-digit code', and routes the agent to get_anae_activity for the special micro-importation regime. It gives rich per-country conditions but does not explicitly contrast against sibling search_activity_codes, so it falls short of full alternative 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 only declare readOnlyHint=true and openWorldHint=false; the description adds a great deal beyond them: 1962–2001 scan vs 2002+ PDF provenance, [[? ... ?]] uncertainty markers, free-tier caps (current year + two, max 10 matches, meta.free_years/meta.truncated), Algeria-only with country_not_available/key_required errors. This goes well past the safety hints, so it earns more than the annotation baseline.

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?

Purpose and search syntax are front-loaded, followed by match fields, provenance caveats and limits. Dense but nearly every sentence earns its place; the parenthetical enumeration of act types is heavy but informative for this domain.

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 enumerating the returned fields (year, issue, ord, type, number, title, page, excerpt, links) and covering error/limit behavior and source-reliability caveats. An agent has everything needed to call and interpret 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%, so the baseline is 3, but the description adds query semantics the schema does not: plural folding, OR alternatives, and a leading minus to exclude. It also reinforces the country restriction in prose, adding meaning beyond the enum.

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 full text of the acts published in the Algerian Journal Officiel since 1962') and explicitly contrasts with the sibling search_jo_titles ('not only their titles'). An agent can immediately tell it apart from title-search and other JO tools.

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 concrete use case ('find which text sets a rule, a rate, an amount or a procedure') and names the follow-up tool explicitly ('then read that text with get_jo_act before quoting it'). The when-to-use path and the alternative for full text are both spelled out.

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?

Well beyond the readOnlyHint annotation, it discloses corpus coverage (1962–today), free-tier caps (current year + two prior, max 10 matches), the meta fields that report those caps, the two-of-three OCR arbitration rule behind 1962–2001 entries, and that those hits have url=null and a scan PDF. This is unusually rich behavioral context for a read tool.

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 key scoping facts (what is searched, coverage, caps, OCR caveat) are front-loaded and each sentence carries information. However, it is delivered as one very dense paragraph with some restatement of schema-level facts (country codes, year bounds), which makes it heavier than necessary.

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 the return shape (year, issue number, section heading, title, issue page and PDF links, meta.total) and the important edge cases (empty result ambiguity, null url for scanned years, country_not_available/key_required). Nothing an agent needs to interpret results 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 description coverage is 100%, so the schema already documents every parameter, and the description largely restates it. It does add modest semantic value by framing year as an optional narrowing ('Optionally restrict it to one year') and by surfacing meta.total as the pagination anchor, but does not supplement the q matching rules or limits 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 ('Search the official titles of the texts listed in the summaries of the Algerian Journal Officiel') and enumerates the text types covered. It is clearly distinguishable from siblings like search_jo_text (full text), get_jo_act and list_jo_issues.

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 ('find when and where a text was published') and an explicit alternative route: an empty result does not prove absence, so use search_jo_text for full text. It also states the country exclusion (MA/TN return country_not_available) rather than leaving it 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?

With readOnlyHint/openWorldHint already covering the safety profile, the description adds real behavioral context: data refreshed daily from Algérie Poste, the 10-row cap without an API key, the fact that paging requires a key, and the country_not_available / key_required error behaviors. It also discloses nearest-first ordering and the presence of distance_km in 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 search modes are front-loaded and each sentence carries information (matching modes, result fields, limits, region restriction). It is dense and long for a single block, but there is little 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 carries the burden of describing returns and does so: each post office comes with class, address, postal code, former postal code, GPS position and commune, each ATM with operational status. Together with the limit/key notes and country restriction, nothing essential for a correct call 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 the baseline is 3, but the description goes beyond the per-field schema text by explaining how parameters interact (lat/lng searched within radius_km, 10 by default, returned nearest-first with distance_km) and by clarifying that postal codes may be partial (all five digits or the first ones).

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 Algérie Poste's post offices ... or ATMs'), names the default kind, and covers the whole scope (Algeria only) in the opening sentence. No sibling tool touches postal data, so the agent can route to it unambiguously.

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 when-to-use scenarios ('find the post office of a postal code, the offices of a delivery zone, or the nearest office or ATM to an address'). It does not name alternative tools or state exclusions, but no sibling overlaps, so the guidance is clear without being exhaustive.

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?

With annotations only declaring readOnlyHint and openWorldHint, the description adds substantial behavioral context: French accent/case-insensitive matching, quoted-phrase behavior, English/Arabic translation through meta.query_terms, ranking rules, result fields, citation lines, and a 10-match cap without an API key. It also explains that offset cannot be used without a key and that non-live countries return country_not_available.

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 front-loaded with purpose and scope, and most sentences contribute operational detail about searching, ranking, reading results, and errors. It is lengthy and includes some repetition of the schema's enum descriptions for the six codes, which keeps it from being maximally concise, but it is dense rather than wasteful.

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 search tool with no output schema, the description is complete enough to call correctly: it explains result contents, ranking, citation behavior, pagination limits, API-key constraints, and country availability. It also names the follow-up tools needed to read a full article or the underlying Journal officiel law.

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 useful meaning beyond the schema: it explains that every word in q must appear, that quoted phrases are searched literally, and that English/Arabic terms are mapped to French equivalents shown in meta.query_terms. It also reinforces the country limitation and no-key paging constraint, though some parameter details are duplicated from the schema rather than extended.

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 precise verb and resource: searching the six Algerian tax codes article by article in their 2026 DGI editions. It enumerates all six codes and their scopes, which clearly distinguishes this tool from article-reading siblings like get_tax_code_article and from broader searches like search_jo_text.

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 states the intended workflow: use search to find which article sets a rate, deadline, penalty or condition, then read that article with get_tax_code_article before quoting it, and use get_jo_act for the underlying finance law. It also explains filtering by code and the country restriction, leaving little ambiguity about when to use this tool versus alternatives.

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