mayotte_list_communes

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

No annotations are provided, so the description carries the burden. It discloses that the tool accesses geo.api.gouv.fr and returns specific fields, implying a read-only operation. However, it does not mention data freshness, potential API limitations, or whether this is a simple static listing. It adds some context but lacks depth.

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 concise sentence that packs all necessary information: the action, the data source, and the returned fields. No fluff, perfectly front-loaded.

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

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

Given the tool has no parameters and no output schema, the description provides sufficient detail about the return values. It doesn't mention pagination or bulk size, but for a simple listing of communes with known fields, this is adequate. No serious 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?

The tool has zero parameters and the schema is empty. Since there is nothing for the schema to document, the description's text effectively defines the tool's behavior. It clearly states the output fields, which is the only meaningful semantic content needed for a no-parameter tool.

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 lists Mayotte communes from geo.api.gouv.fr and specifies the exact data fields returned (INSEE code, postal codes, population, center geometry). It distinguishes itself from sibling tools like mayotte_search_data_gouv or mayotte_find_commune by focusing on listing all 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 implies this is the go-to tool for retrieving a full list of communes with their reference data, but it does not explicitly state when to use it over alternatives like mayotte_find_commune for a single commune search. The context is clear enough for an agent to infer usage, but not fully explicit.

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