geoparquet_describe_source

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that only Parquet footers are scanned, never data pages, that the call may cost about 26 MB of remote traffic on first use, that results are cached afterward, and that extent may be null when statistics are missing. These are exactly the behavioral traits 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 description is long but tightly organized with clear section labels: overview, when to use, parameters, and return shape. Every sentence adds operational value, and the key claim ('without reading any of its data') is front-loaded. The concrete scan-cost example earns its place by setting accurate expectations.

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 covers not only what the tool returns but also edge cases like null extent, CRS meanings, default vs stated CRS, and the physical file characteristics. Even though an output schema exists, the description enriches it with operational semantics and a clear usage narrative, leaving no significant gap for an agent deciding to call 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 0%, so the description must compensate for the single `source` parameter. It explains that `source` is the dataset name, where to obtain it (`geoparquet://sources` resource or the default), and that every other tool takes the same name — valuable cross-tool context beyond the bare schema declaration.

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 and resource — 'Describe one remote dataset without reading any data' — and enumerates the exact metadata returned: columns, geometry/bbox, CRS, row count, parts, row groups, size, extent. It is clearly distinguishable from sibling tools like geoparquet_preview_rows and geoparquet_filter_spatial.

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 'WHEN TO USE IT' section explicitly recommends calling this before the first filter against a dataset, explains it is how to learn real column names, and advises checking whether the region is inside extent before spending a query. This gives direct guidance with a concrete alternative behavior, satisfying both when and why to use it.

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