Morocco communes

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds valuable behavioral context: the specific cities where arrondissements are included, and the known coverage gaps. This goes beyond the schema and helps an agent predict failures.

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 three sentences: the first defines purpose and output, the second gives a usage directive, and the third notes exceptions. It is efficient and front-loaded with the core definition. The third sentence is a useful aside but slightly tangential, so it isn't perfectly lean.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with two well-documented parameters and an existing output schema, the description covers everything an agent needs: core function, intended use, and known data gaps. The mention of specific cities and exceptions makes it exceptionally complete.

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?

Both parameters (lat, lng) are fully described in the schema with ranges and units ('Latitude, in degrees.'). The description only adds the generic term 'coordinates' and does not provide additional format details, bounds, or examples. With 100% schema coverage, 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 description clearly states the tool returns the commune containing a point, with specific fields (names, type, parents, population) and even city-specific arrondissements. It also distinguishes from siblings like communes_near and get_commune by focusing on point-to-commune mapping.

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 an explicit use case: 'Use it to turn coordinates, from a map or a device, into a commune.' It also highlights known edge cases where no commune exists (Sidi Mohamed Benmansour, 88 km² between Ifrane and Boulemane), which is useful for setting expectations. However, it does not explicitly contrast with alternatives like communes_near, so it misses the 'when-not-to-use' 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 readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: distance is measured to centroids, results are ordered nearest-first, and the nearest commune may not contain the point. This goes beyond the annotations and helps the agent interpret results correctly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The core behavior is front-loaded, and the caveat plus sibling alternative is packed into the second sentence. Every clause earns its place.

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?

The tool has an output schema, so return values are documented elsewhere. The description covers the key behavioral nuance (centroid distance) and the sibling distinction. A small gap is that it doesn't mention the default radius/limit, but those are already in the input schema, so the description is complete enough for an agent 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%, so the schema already documents all four parameters (lat, lng, limit, radius_km) with types, bounds, and defaults. The description adds the centroid-distance semantics but doesn't need to repeat parameter details. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Communes within a radius of a point') and resource, and explicitly distinguishes itself from the sibling commune_at by explaining the centroid-distance behavior. This makes the tool's purpose unmistakable and differentiates it from the sibling that returns the commune containing the point.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use this tool versus commune_at: use this for communes within a radius, and commune_at for the commune that contains the point. It also clarifies the nearest-first ordering and the centroid caveat, which is essential for correct selection.

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 idempotentHint=true, covering the safety profile. The description adds context about accepted ID formats and the scope of returned data, but it does not disclose error behavior, rate limits, or dependency on external factors. This is adequate but not beyond what annotations provide.

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 dense sentence enumerating all the returned data, followed by a clear identifier instruction. Every phrase adds information, and it is front-loaded with the core content. It is long but not verbose, though it could be broken into two sentences for easier scanning.

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?

Given an output schema exists and annotations cover read-only/idempotent behavior, the description is sufficient for an agent to know what it returns and how to call it. It does not mention failure modes or edge cases (e.g., codes not found), but the presence of an output schema fills in the return structure. Overall, the description is complete enough for correct invocation in the common case.

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

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

Schema coverage is 100% with a short description of the 'id' parameter. The tool description adds concrete examples ('01.511.01.0' and 'tanger') that clarify the accepted formats, providing extra value beyond the schema's generic wording. This nudges it above 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?

The description clearly states the tool returns a wide array of data for a single commune (names, type, populations, borders, arrondissements), and specifies the identifier types. It is unambiguous about the resource and scope, but it does not explicitly name sibling tools or contrast with them, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains how to identify the commune (HCP code, digits, or slug) but gives no guidance on when to use this tool versus alternatives like list_communes, commune_at, or get_unit. There is no mention of use cases, prerequisites, or exclusions, so the agent is left to infer situational appropriateness from the name alone.

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 it a safe, idempotent read; the description goes well beyond that by disclosing data-availability rules (figures only for douars of 30+ households, HCP withholds and returns null), naming conventions (Arabic only, Latin only when a source writes one), and coordinate provenance (GeoNames/OpenStreetMap). These are exactly the gotchas 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?

Dense but information-bearing; every clause carries a distinct fact and the identity/scoping sentence is front-loaded. It would read better split into short grouped sentences, but there is little removable waste.

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 an output schema present, return structure needn't be described, and the description still covers the domain model (fractions/mashyakha, douar kinds, conditional figures) and the town-vs-commune edge case. Nothing an agent needs 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 coverage is 100% and already documents all three params, so baseline is 3. The description adds real meaning on top: it explains what the response degrades to when 'figures' is left out (name, kind, households and people), which the schema only gestures at. It adds nothing beyond the schema for 'unit' or 'fraction'.

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 (the douars of a rural commune) plus its source scope (HCP 2024 census) and enumerates the fields each douar carries. An agent can tell this apart from get_commune or get_neighbourhoods without opening a schema, since it names the exact sub-unit and its contents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a partial when-not rule ('A town has no douars, though 21 communes counted as urban have some in their rural part'), which helps scope selection. But it never names an alternative tool (e.g. get_commune, get_neighbourhoods) or states when another sibling is the better choice, so routing must be inferred.

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 and idempotent annotations, the description discloses important behaviors: souks are counted separately and excluded from the total, agriculture is excluded, jobs are permanent, and cities with arrondissements are reported as arrondissement sums with basis: arrondissement_sum. These are exactly the non-obvious behaviors an agent needs before invoking the 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 description is long but every section earns its place: a clear inventory of counts, a 'Reading them' caveat block, a 'Ranking and comparing' routing block, and a specific arrondissement_sum warning. It is front-loaded with the core count definition and uses compact, structured paragraphs rather than repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only data retrieval tool with an output schema, the description covers all necessary context: granularity, exclusions, parameter behavior, comparison usage, and output semantics for arrondissement cities. An agent has enough information to select the tool, call it correctly, and interpret the result.

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

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

Schema coverage is 100%, but the description still adds meaning: it explains that a bare name defaults to the commune (e.g., Tiznit), that level without a unit returns every unit of that level, and that business splits correspond to sector, size, and founding period. This exceeds the baseline for fully covered schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb and resource: 'HCP's 2024 count of economic establishments for Morocco or any région, province or préfecture, cercle, commune or arrondissement.' It names the exact metrics returned (establishments, public services, associations, businesses, permanent jobs) and clearly separates this from siblings like get_housing and list_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?

The description gives explicit routing guidance: 'To order communes by one of these, call list_communes with sort set to its path' and 'To compare the régions, the provinces or the arrondissements, give level without a unit and get them all in one call.' This tells the agent when to use an alternative tool and when to use this tool differently.

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

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

Annotations already declare readOnly, idempotent and closed-world, but the description adds substantive semantics: every figure except the count is a percentage, and the data counts dwellings rather than households (a vacant flat appears here but in no census record). It does not cover pagination or response shape, though an output schema exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first sentence and nothing is padded with filler, but the remaining content is delivered as three very long, densely punctuated sentences that are harder to scan than they need 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?

With an output schema handling return values and annotations covering the safety profile, the description covers everything else an agent needs: scope, exclusions, sibling routing, and the dwellings-vs-households caveat. Nothing material 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 adds real meaning: the unit must have an urban area to return data, the default is Morocco as a whole, and the topic list is described in prose (occupancy split, building materials, network hookups). This goes beyond restating the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (HCP's 2024 count of urban dwellings) and enumerates exactly what is measured – count, occupancy, type, age, walls, roofs, networks, shortfall. It explicitly separates itself from get_indicators, so an agent can distinguish the two without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternatives and the conditions that select them: get_indicators' amenities topic for household-level water/electricity (rural included), its wastewater topic for public sewers, and list_communes for sorting. It also states the negative case – a unit with no urban area has nothing here.

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/idempotent/closed-world; the description adds far more: the 20% long-questionnaire sample and that results are estimates in communes of 2,000+ households, the meaning of null, and the five 2014 topics whose definitions changed and therefore cannot be subtracted. It even explains that 2014 units not counted (Casablanca and 5 other arrondissement cities) return null. That is exactly the behavioral context an agent cannot get from 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?

Long but deliberately sectioned into purpose, reading rules, comparison guidance and 2014 comparability, which keeps it navigable. The prose topic enumeration in the first sentence largely duplicates the topics enum, which is the main source of waste. Front-loading is reasonable, though the core action is buried inside a long topic list.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values need no explanation. Between the comparability caveats, the sample-weight warning, the null semantics, the sibling routing and full parameter coverage, an agent has everything needed to call this correctly on the first attempt.

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 most parameter meaning is already documented (the Tiznit name-collision note and the labour-vs-employmentStatus distinction appear in the schema itself). The description still adds value by linking parameters to behavior, e.g. passing level without a unit returns every unit of that level in one call, and by tying census=2014 to the null-unit caveat. Slight redundancy with the schema keeps it below 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 opening sentence names the exact resource (HCP census figures) and the full set of geographic units it covers, then enumerates the topic space, so an agent knows precisely what data comes back. It earns differentiation by naming list_communes as the alternative for ordered comparisons. The only weakness is that the purpose is expressed as a headless noun phrase rather than an explicit verb+resource statement, but the intent is unmistakable.

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 explicit when-to-use-this-vs-siblings guidance: for ranking use list_communes with sort rather than calling this once per commune, and to compare régions/provinces/arrondissements pass level without a unit to get them all in one call. It also states usage for reading results (shares/rates are 0-100, null means unpublished) and when to add census=both. Nothing is left to inference.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavioral traits: whole categories of exclusions (disagreeing censuses, sex-share figures, likely errors, economy/housing on <100 businesses or dwellings), a 'sampled' marking for communes of 2,000+ households, and the fact that nothing is model-generated. This is exactly the kind of context an agent cannot infer from annotations alone.

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 output is front-loaded in the first sentence, and subsequent sentences each carry a distinct exclusion or caveat rather than filler. It is long for a two-parameter read tool and some of the return-content detail overlaps the output schema, but nothing is padding.

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 annotations covering the safety profile and an output schema present, the description need not explain return values; it nonetheless covers scope, exclusions, sampling caveats, and the commune-only limitation. An agent has everything needed to invoke it correctly and interpret empty or 'sampled' responses.

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 documented with type, enum, and a name-collision note, so the baseline is 3. The description adds only a weak signal ('for a commune', 'only communes have these') that usefully implies which values of 'unit'/'level' actually yield results, but it does not deepen the parameter contract materially.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource: up to 3 standout 2024 census figures for a commune, with the types of standout (highest/lowest, biggest change since 2014, far from province figure) spelled out. This is clearly distinguishable from data-listing siblings like get_indicators or get_commune, though it never names an alternative explicitly. Purpose is unambiguous, so 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Only communes have these, and most have none' gives a real usage precondition and warns that empty results are common. However, no alternative tool is named for when a caller wants raw figures rather than outliers, and no explicit when-to-use guidance versus get_indicators/get_commune is offered. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description usefully adds the data provenance (OSM + Poste Maroc) and the granularity limitation (census publishes nothing by neighbourhood), which is genuine added context. However it says nothing about the large result sets implied by the limit param (Casablanca has 1,400+), page behavior, or cost. Output schema covers the return shape, so this is a solid-but-not-rich 3-4; I settle at 3 given the behavioral gaps around bulk 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?

Every sentence carries information (sources, granularity caveat, reverse-lookup routing), but the first sentence is an overstuffed clause chain that buries the primary purpose. The key resource statement should be front-loaded as its own sentence rather than wrapped in subordinate clauses, so structure is adequate but not efficient.

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?

An output schema exists, so return structure needn't be explained, and annotations carry the safety profile. The description supplies provenance, the census granularity caveat, and reverse-lookup routing — enough for a 2-param read tool. Minor gap: no guidance on handling the very large result sets the limit parameter implies.

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%: `unit` is documented as a commune by code or slug, and `limit` documents its default (200) and max (2000) plus the ordering (alphabetical). The description adds no parameter-level detail beyond what the schema already provides, 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 resource (neighbourhoods and postcodes of a commune) with named sources (OpenStreetMap, Poste Maroc) and included sub-entities (arrondissements, name origins). It distinguishes itself from the sibling `search` for the reverse lookup, though the dense run-on opening sentence makes the core purpose slower to extract than it should be.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the reverse case away: 'To find which commune a neighbourhood is in, call search with its name instead.' It also clarifies via the census note that figures are not available at neighbourhood granularity, implying when this data is and isn't the right source. No exclusion vs. commune_at/get_douars, but the primary alternative is named.

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 idempotentHint=true, so safety is covered. The description adds useful behavioral context about hierarchical resolution, including which child units are returned for which level, and the shared-name disambiguation behavior involving level. It does not contradict 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 description is dense but efficient: it front-loads the return contents, then states when to use it, then names alternatives. Every sentence 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?

Given the rich schema, output schema, and read-only annotations, the description is largely complete for invocation and selection. It clearly explains what is returned and routes to siblings. A minor gap is that 'préfecture' is mentioned as a supported unit type but does not appear in the level enum, which could leave an agent uncertain how to disambiguate a préfecture when a name is shared.

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

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

Schema coverage is 100% and the schema already explains code/slug usage and the shared-name level disambiguation. The description reinforces the unit hierarchy and maps it to typical questions, but it adds little parameter-level detail beyond what the schema already provides, so the 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?

The description names a specific resource type (région, province, préfecture, cercle) and enumerates exactly what is returned: names in French/Arabic, 2024 population, households, ancestors, and children. It also differentiates itself from sibling tools by naming get_commune for lower-level units and list_communes for listing 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?

The description explicitly states the tool's target: 'This is the tool for a question about a unit above the commune, such as how many cercles a province has.' It also gives clear alternatives: call get_commune for a commune or arrondissement, and list_communes to list a unit's communes. The routing guidance is unambiguous.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds genuinely new operational facts: page size of 50, code order as the default, that filters combine, and that identifiers may be codes or slugs. It does not mention total counts or a max-page cap, but the paging behavior is disclosed.

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 rhetorical opening ("Which commune has the most or the least of something is one call here") and the re-explanation of count-ranking rules consume space already spent in the schema's sort field. Reorganizing it into a short "what it does / how to filter / how to sort" structure would carry the same content in fewer 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 an output schema present, return values need no explanation, and the description covers what matters for correct invocation: filter dimensions, combinability, sort syntax, default ordering, and pagination. Only edge details (page bounds, total result handling) are absent, which is acceptable against the structured fields.

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's own sort description already documents the minus prefix, 2014./change. prefixes, and the per1000 ranking subtlety, so the description's long sort passage is largely a restatement. The notes that filters combine and that code or slug is accepted are marginal additions over the schema, keeping this at the baseline.

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 makes the verb+resource concrete: it returns every commune matching a filter, ordered by any figure, and it frames the primary use case (finding the largest/smallest place in one call). It implicitly contrasts with one-by-one lookup (get_commune) but never names a sibling, so differentiation from search/get_unit is left to the agent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clear context is given: use this to rank communes by any indicator or establishment count, and "With no filter it lists every commune, so sort: \"-population\" alone gives the largest in the country" supplies a concrete invocation pattern. It stops short of explicit when-not-to-use guidance or naming alternatives like search.

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

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

Annotations already declare readOnly, idempotent, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: alias/fuzzy matching (Mogador→Essaouira), the fact that a neighbourhood query resolves to its parent arrondissement/commune, and that results are codes rather than data.

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?

Dense but front-loaded: purpose first, then input forms, then edge cases and the handoff to get_commune. Every sentence carries information, though the run of worked examples is slightly long.

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?

An output schema exists, so return structure needn't be explained, yet the description still tells the agent that codes come back and how to use them. Combined with the alias/postcode/neighbourhood rules, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description meaningfully enriches the query parameter beyond the schema's form list by documenting alias resolution and postcode lookup behavior, and by naming the returned codes as the input to get_commune.

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 (find) and a precisely enumerated resource (régions, provinces/préfectures, cercles, communes, arrondissements of Morocco) with concrete examples (Fez→Fès). An agent can distinguish this from siblings like get_commune or list_communes 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 covers what inputs work (French, Arabic, slug, alias, postcode, neighbourhood name) and routes the agent onward: 'pass a commune's code to get_commune for its population and parents.' It also flags a boundary case — the census has no figures for a neighbourhood itself.

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