Server Quality Checklist

Tool Scores

• geoparquet_summarize_h3A
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral burden and exceeds it: it discloses remote computation, bounded result size, bounding-box-center binning versus true geometry, DuckDB H3 extension dependency, and the explicit failure behavior if the extension cannot be loaded. This gives an agent strong insight into side effects and limitations.

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

  Conciseness5/5

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

  The description is structured into clear sections - usage, parameters, return values, and caveats - and every sentence adds information. Even the H3 extension note earns its place by preventing the agent from assuming a silent fallback exists.

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

  Completeness5/5

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

  Despite the absence of annotations and schema-level parameter descriptions, the description fully equips an agent to select and invoke this tool correctly. It covers input semantics, output structure (cells, feature_count, centre, features_binned, truncated, scan), and edge-case behavior around resolution and extension loading.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must fully compensate, and it does. Every parameter is explained: source, the four rectangle coordinates in WGS84 with requiredness, resolution with real-world scale examples and tuning guidance, limit with ordering semantics, and include_cell_centre with its plotting purpose.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: "Bin the features inside a rectangle into H3 hexagonal cells and return the count per cell." It further distinguishes the tool by labeling it "A density map, computed remotely," separating it from sibling aggregation and filtering tools.

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

  Usage Guidelines4/5

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

  The description provides an explicit "WHEN TO USE IT" section with concrete queries like "where are these densest" and "how is this spread across the city," plus the heatmap heuristic. It does not explicitly name alternative sibling tools or state when not to use this tool, but the use cases and efficiency rationale are clear.

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

• geoparquet_aggregate_attributeA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and excels. It discloses that grouping executes server-side ('only the group rows cross the network'), that a non-numeric measure is 'refused before any byte is fetched', that omitting the rectangle reads the full dataset, and that results are 'ordered by the aggregate descending'. It even lists the complete return payload (groups, rows_aggregated, truncated, sql, scan), which is behavioral disclosure beyond the structured schema.

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

  Conciseness5/5

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

  The description is long but densely organized into four labeled sections (overview, WHEN TO USE IT, PARAMETERS, WHAT COMES BACK) with one semantic fact per parameter line. No sentence is filler — even asides like 'which counts rows' clarify a conditional rule. The length is proportionate to the tool's genuine complexity (9 params, 5 aggregate modes, spatial constraints).

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

  Completeness5/5

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

  For a complex 9-parameter tool with zero schema descriptions and zero annotations, the description covers everything needed to invoke it correctly: operation, selection criteria, per-parameter semantics, relational constraints between parameters, performance trade-offs, and return shape. The output schema exists and is also described in prose, which is belt-and-suspenders completeness.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must fully compensate, and it does: every one of the 9 parameters gets semantic meaning beyond type/default. It explains the conditional relationship between aggregate and measure ('Required for sum, avg, min and max, and rejected for count'), the 'Pass all four or none' invariant for the lon/lat box, and the ordering semantics of limit.

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

  Purpose5/5

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

  The opening sentence states a specific verb and resource: 'Group the rows of a dataset by one column and aggregate them', with the distinctive detail that grouping runs remotely. It is explicitly differentiated from the sibling geoparquet_filter_spatial ('Reach for it before geoparquet_filter_spatial whenever counting would do'), so an agent can tell them apart without opening schemas.

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

  Usage Guidelines5/5

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

  A dedicated 'WHEN TO USE IT' section gives concrete query shapes ('how many of each', 'what is the average', 'which is the most common') and states the decision rule against a named alternative: 'Reach for it before geoparquet_filter_spatial whenever counting would do.' It also warns about the expensive full-dataset path ('slow and expensive on a multi-gigabyte source'), which implicitly tells the agent when to add a bounding box.

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

• geoparquet_count_in_polygonsA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral disclosure burden and does so thoroughly. It discloses that this is the most expensive tool, explains the rectangle pruning and geometry decode costs, refuses point datasets for polygon_source, and clarifies that counts are based on true containment rather than bounding-box overlap.

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

  Conciseness5/5

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

  The description is long but tightly organized into labeled sections: purpose, when-to-use, cost, parameters, and return value. Each section adds decision-relevant information that is not available in the schema, and the main purpose is front-loaded. No sentence feels redundant or filler.

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

  Completeness5/5

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

  Given the tool's complexity, zero annotations, and 0% schema description coverage, the description is remarkably complete. It covers selection criteria, cost/performance expectations, parameter behavior, output shape, and a key semantic caveat about containment versus bounding boxes, leaving the agent with everything needed to invoke it correctly.

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

  Parameters5/5

  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, and it does. Every parameter is explained with practical guidance: the rectangle is required and WGS 84, polygon_source must be polygonal, polygon_subtype prevents incomparable mixed granularity, and limit controls count-descending output.

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

  Purpose5/5

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

  The description opens with a specific verb-plus-resource statement: counting features from one dataset inside polygons of another via a point-in-polygon join. It further distinguishes itself from siblings by noting it is the only tool that reads two datasets at once and the only way to group by a shape rather than a column.

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

  Usage Guidelines5/5

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

  The 'WHEN TO USE IT' section gives concrete natural-language queries, explicitly names the cheaper alternative geoparquet_aggregate_attribute, and states the condition for choosing this tool instead: geographic grouping where boundaries live in a separate file. This gives an agent clear selection criteria rather than leaving the decision to inference.

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

• geoparquet_describe_sourceA
  5/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• geoparquet_filter_spatialA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure, and it exceeds expectations. It explains cost behavior, how rectangle pruning works in Parquet, how WKT envelope pruning plus exact filtering works, the effect of include_geometry, and the exact contents of the response including bytes_scanned as a diagnostic signal.

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

  Conciseness5/5

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

  The description is long but every section earns its place: purpose, when-to-use, cost rationale, parameter semantics, and return value explanation. Clear section headers and front-loaded main behavior make the length navigable, and there is no filler or repetition.

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

  Completeness5/5

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

  For a 12-parameter spatial filter tool with no annotations and no schema-level descriptions, the description is remarkably complete. It covers all inputs, output shape, behavioral nuances, cost implications, and alternatives, leaving no meaningful gap an agent would need to guess about when selecting or invoking the tool.

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

  Parameters5/5

  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 entirely for the parameter semantics. It does so thoroughly: every one of the 12 parameters is explained, including constraints like 'Pass all four, or none', the mutual exclusivity of rectangle vs wkt, the meaning of min_confidence, the columnar cost benefit of columns, and the limit cap of 1000.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Return the features of a dataset that fall inside an area, as a GeoJSON FeatureCollection.' It also clarifies the two possible area forms (rectangle or WKT), and the WHEN TO USE IT section names the exact sibling tools that cover other use cases, distinguishing this tool clearly.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use this tool ('when the answer is the features themselves') and when not to use it ('when you only need a count, a ranking or a distribution, use geoparquet_aggregate_attribute or geoparquet_summarize_h3 instead'). It also gives practical guidance on passing the tightest area, which directly informs tool invocation.

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

• geoparquet_find_nearestA
  5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral burden and does so richly: it explains the radius acts as a filter, not a hint; distances are great-circle in kilometres; results are ordered nearest first; the search_bbox is used for pruning; and cost characteristics are disclosed ('A large radius therefore costs a large read'). This goes far beyond basic operation.

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

  Conciseness5/5

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

  Though lengthy, the description is organized into clear labeled sections (purpose, when to use, cost behavior, parameters, return values) with no filler. Each sentence conveys essential operational information, such as the bounding-rectangle pruning strategy and the exact response shape.

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

  Completeness5/5

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

  Given 8 parameters, no annotations, and the presence of an output schema, this description is complete. It explains what to pass, how the tool behaves, what the output contains (rows with distance_km, search_bbox, scan block), and how to choose between this and sibling tools. Nothing critical for correct invocation is missing.

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

  Parameters5/5

  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 entirely. It does: every parameter is explained with added meaning — 'lon, lat' are WGS 84 degrees with longitude first, radius_km is capped at 500 and is a hard filter, limit is capped at 1000, and category/name_contains are stated to behave like the sibling filter tool.

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

  Purpose5/5

  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: 'Return the features closest to a point, nearest first, each with its great-circle distance in kilometres.' This clearly distinguishes it from sibling tools like geoparquet_filter_spatial, which returns everything in an area rather than the closest few.

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

  Usage Guidelines5/5

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

  An explicit 'WHEN TO USE IT' section states the suitable question types ('what is near here' and 'which is the closest') and names the exact alternative: 'Use geoparquet_filter_spatial instead when you want everything in an area rather than the closest few.' This gives the agent direct routing guidance.

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

• geoparquet_preview_rowsA
  5/5.0
  Behavior5/5

  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 rows come in file order, are not ranked or spatially significant, that reads stop at the first row group for cost predictability, and what the response contains. This goes well beyond a basic one-line definition.

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

  Conciseness5/5

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

  The description is organized into clear labeled sections, front-loaded with the core purpose, and every sentence adds practical value. Even the cost rationale and non-spatial warning serve important decision-making purposes.

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

  Completeness5/5

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

  Given the tool's modest complexity, the description covers when to use it, how each parameter behaves, what the return payload includes, and the operational cost characteristics. Nothing an agent needs to correctly call and interpret this tool is missing.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description's PARAMETERS section explains each parameter meaning, provides a concrete example for columns, and advises on the limit range and typical values. It fully compensates for the schema's lack of descriptions.

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

  Purpose5/5

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

  States a specific verb and resource: 'Return the first few rows of a dataset'. It clearly differentiates itself from spatial sibling tools, explicitly saying this is NOT a spatial question and directing to geoparquet_filter_spatial or geoparquet_find_nearest for spatial queries.

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

  Usage Guidelines5/5

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

  Provides an explicit 'WHEN TO USE IT' section: after geoparquet_describe_source and before filtering, to inspect real values. It also states when NOT to use it and names the alternative tools, leaving no ambiguity about its intended role.

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

• geoparquet_run_sqlA
  5/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full burden, and it delivers extensively. It discloses that only a single SELECT is permitted, table functions are refused, read_parquet is blocked, and the 'perimeter' is intentional. It also explains that byte_budget_exceeded is a post-hoc verdict rather than a pre-emptive brake, and that max_rows is hard-enforced while max_bytes is not.

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

  Conciseness5/5

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

  The description is long but every section earns its place, and clear headers make it scannable: WHEN TO USE IT, WHAT YOU CAN QUERY, WRITING A FAST ONE, PARAMETERS, WHAT COMES BACK. It front-loads the most important guidance first and uses a concrete query example to illustrate the bbox pushdown point efficiently.

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

  Completeness5/5

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

  For a complex, flexible SQL tool with no annotations, the description is exceptionally complete. It covers query scope, performance optimization, filter pushdown mechanics, parameter semantics, and result fields including executed_sql, scan, and byte_budget_exceeded. Even though an output schema exists, the descriptive explanation of post-hoc byte budget behavior is necessary context that the schema alone would not convey.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the dedicated PARAMETERS section fully compensates. It explains sql as 'one SELECT statement,' max_rows as an outer LIMIT that is hard and capped at 1000, and max_bytes as a reported ceiling rather than pre-emptive. This goes far beyond the raw schema and gives an agent the operational meaning of each parameter.

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

  Purpose5/5

  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: 'Run one read-only SELECT against the datasets in scope.' It explicitly frames the tool as covering questions 'the other tools do not have a shape for,' distinguishing it from the typed sibling tools. It also clarifies that datasets are the only queryable tables, removing ambiguity about the tool's scope.

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

  Usage Guidelines5/5

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

  The 'WHEN TO USE IT' section is explicit and actionable: 'Last, not first,' with concrete examples of genuine gaps such as joins, HAVING, window functions, and self-joins. It warns against using ad-hoc queries when a typed tool would push filters down efficiently, naming the tradeoff explicitly and thereby guiding selection among siblings.

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