render_map

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

With no annotations supplied, the description carries the full burden and does disclose key behavior: it always saves the PNG to disk, optionally writes a Leaflet HTML file, and degrades to a plain background when the OSM basemap is unavailable offline. It does not state the save location/filename or the shape of the returned payload, which matters for a tool that writes files.

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

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

Three sentences, front-loaded with the core action and return format, then the input-source enumeration, then the usage trigger. The parenthetical sibling list is long but each item is functional and there is no filler.

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

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

For a 10-parameter tool with no annotations and no output schema, the description covers input sources, side effects and offline fallback well. The remaining gaps are how sql/geojson/result_ids interact when multiple are supplied, and where saved files land or what the response contains.

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 80%, so the schema already explains sql, geojson, basemap, save_html, result_ids, label_property and value_property. The description mostly restates those (result_ids as coloured layers, grouped rendering order) and the 'right_count from spatial_join' hint duplicates the schema's choropleth note, adding little new meaning.

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 ('Draw a MAP and return it as a PNG image') plus the supported input modes. It reads nothing like its analysis-oriented siblings (find_features, spatial_join, run_sql), so an agent can distinguish it 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?

Gives a clear trigger ('Use this whenever the answer is spatial') and enumerates which sibling tools produce inputs (find_features, within_distance, nearest, buffer, spatial_join, bbox_of, run_sql), which is highly actionable. It stops short of stating when not to use it, or whether result_ids, geojson and sql are mutually exclusive or combinable.

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