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?

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?

The annotations already mark the tool as read-only and idempotent, and the description adds valuable behavioral context beyond that: it explains that every figure except the count is a percentage of the unit's urban dwellings, that vacant dwellings are included even though they appear in no census household record, and that units without urban areas return nothing. No contradiction with annotations 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?

The description is long but every sentence carries essential information: the first sentence front-loads the full scope and metric list, the second clarifies percentage semantics, the third removes ambiguity about dwellings versus households and points to the sibling, and the fourth gives the no-data edge case. There is no filler or 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?

The description, combined with the complete schema, annotations, and output schema, fully equips an agent to call this tool correctly. It explains the data source, unit eligibility, metric semantics, sibling differentiation, and edge-case behavior, so no critical information is missing for selection or 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?

The schema already covers 100% of parameters with descriptions and enums, so the baseline is 3. The description adds meaningful parameter-level context by clarifying what 'unit' means here (must have an urban area) and by explaining that all values except the count are percentages of that unit's urban dwellings. This goes beyond the schema's syntactic descriptions.

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 (HCP 2024 urban dwellings), scope (Morocco or units with an urban area), and the concrete metrics returned (counts, occupancy, type, age, materials, networks, shortfall). It explicitly distinguishes itself from get_indicators by clarifying that it counts dwellings, not households, which prevents sibling confusion.

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 names the closest sibling, get_indicators, and explains the key difference: this tool counts dwellings while get_indicators describes the dwelling each household lives in. It also states a clear exclusion boundary: 'A unit with no urban area has nothing here,' telling the agent when not to expect results.

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 indicate read-only and idempotent hints, so the description builds on that by explaining the sampling methodology (20% long questionnaire) and the meaning of null values. It also discloses that some topics are estimates, adding important context beyond 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 long but packed with valuable information, and it is well-structured with clear sections. The first sentence lists the topics and scope, and subsequent paragraphs handle reading, ranking, and the 2014 comparison. No filler—every sentence adds critical detail, though it could be tightened slightly.

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 complexity of the tool with 6 optional parameters and an output schema, the description covers all necessary aspects: data sources, interpretation of percentages, sampling caveats, comparison methods, and cross-census compatibility. The output schema exists, so return values are not needed in the description. It is complete for an agent to use 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?

While schema coverage is 100% and parameters are well-described in the schema, the description adds crucial guidance for the topics parameter by explicitly distinguishing 'labour' from 'employmentStatus', reducing confusion. It also explains how unit and level interact for comparisons, which is not fully clear from the schema alone.

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 retrieves census indicators for Morocco and its administrative units, listing specific topics and the scope of data. It also differentiates from siblings by mentioning list_communes for ordering and comparing, and implies its role relative to other tools like get_commune and get_housing.

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 explains how to rank communes (use list_communes with sort) and compare regions (give level without unit), providing clear when-to-use guidance. It also clarifies the census parameter for comparing 2014 and 2024, and notes topics that changed, preventing misinterpretation.

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 indicate readOnlyHint and idempotentHint true, so it's a safe read operation. The description adds pagination behavior (50 per page), sorting defaults, and combination of filters, which are not in annotations. No contradiction.

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 front-loaded with the core purpose, and every sentence adds necessary detail about sorting and filtering options. No fluff; it's dense but organized.

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 high complexity (8 params, complex sort syntax), the description covers all essential usage patterns. Output schema exists, so return details are provided. Complete for agent to select and 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 coverage is 100%, so parameters are documented in schema. But description adds value by explaining how sort works with indicator paths (e.g., labour.unemploymentRate, change. prefix, per1000 counts) and that filters combine. This goes beyond schema.

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

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

The description clearly states it lists communes with various filters, sorting, and pagination. It distinguishes from siblings by mentioning sorting by indicators and establishment counts, which are unique to this tool. The verb 'list' and resource 'communes' are specific.

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 describes when to use it (e.g., no filter lists all communes, sort by -population for largest). It also implies when not to use it (e.g., for individual commune details, use get_commune or commune_at). It provides clear context for filtering and sorting.

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 safety. The description adds useful behavioral context beyond annotations: it supports multiple languages, slugs, and aliases (e.g., 'Fez finds Fès, Mogador finds Essaouira'), and clarifies that it returns codes. This enriches the agent's understanding of how the search behaves.

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 concise sentences with no filler. It front-loads the core purpose, gives concrete examples of alias handling, and ends with the actionable output (codes) and a pointer to get_commune. Every sentence serves a distinct purpose.

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 search tool with an output schema and rich annotations, the description covers the purpose, search behavior, and output routing. The parameters (limit, levels) are fully documented in the schema, and the output schema covers return structure. Nothing essential is missing 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%, and the description's mention of 'French or Arabic, a slug, or another name' essentially mirrors the query parameter's schema description. It adds no new parameter-level meaning beyond what the schema already provides, so the baseline score 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 states a specific verb ('Find') and resource ('régions, provinces and préfectures, cercles, communes and arrondissements of Morocco by name'), making the tool's function immediately clear. It also distinguishes itself from sibling tools by focusing on name-based search, as opposed to location or code-based tools like commune_at or get_commune.

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?

While it does not explicitly name alternatives or exclusions, it provides clear context: this is a search-by-name tool that returns codes, and it instructs the agent to pass a commune's code to get_commune for population and parents. This gives practical routing guidance without formal when-not-to-use statements.

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