Skip to main content
Glama
Sign In

Usda Soil

by io.github.pipeworx-io
OverviewDiscussionsAdmin

Usda Soil Query

usda_soil_query
Read-onlyIdempotent

Run a read-only SQL SELECT against the USDA-NRCS Soil Data Access database (SSURGO) — the full US soil survey schema: legend, mapunit, component, chorizon, cointerp, plus the SDA_ spatial helper functions such as SDA_Get_Mukey_from_intersection_with_WktWgs84. Use for anything the point and component tools do not cover: soil series by county, prime farmland acreage, drainage class distributions, crop yield indices. Keyless.

Example tool call

This call uses example arguments supplied in the tool’s input schema.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "sql": "SELECT TOP 5 m.muname, m.muacres FROM mapunit m INNER JOIN legend l ON l.lkey = m.lkey WHERE l.areasymbol = 'IA153' ORDER BY m.muacres DESC"
    },
    "name": "usda_soil_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
sqlYesA T-SQL SELECT, e.g. "SELECT TOP 10 m.muname, m.muacres FROM mapunit m INNER JOIN legend l ON l.lkey = m.lkey WHERE l.areasymbol = 'IA153' ORDER BY m.muacres DESC". SELECT only. Use TOP n rather than LIMIT — this is SQL Server.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true. The description adds beyond them: 'Keyless' (no auth setup required) and 'read-only SQL SELECT' constraining the write surface, plus the names of the SDA_ spatial helper functions available. It doesn't mention row caps or error behavior, keeping it short of a 5.

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

Conciseness4/5

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

Purpose is front-loaded in the first clause, followed by scope, alternatives, and use cases in two compact sentences. The table/function enumeration is dense but load-bearing for writing SQL; nothing is wasted, though the em-dash list makes it slightly harder to scan than a 5 would require.

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

Completeness4/5

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

There is no output schema, so the description would ideally say what a result looks like, but as a read-only query tool whose safety profile is fully carried by annotations, an agent has enough to call it correctly: dialect, allowed statement type, auth posture, available schema, and sibling routing. The missing pieces (row limits, response shape) are minor for a keyless read.

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

Parameters4/5

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

Schema description coverage is 100% and the schema itself already documents the SELECT-only rule, the TOP-not-LIMIT dialect, and gives a full example query, so a baseline of 3 applies. The description goes further by enumerating the available tables/functions (legend, mapunit, component, chorizon, cointerp, SDA_ helpers), which is exactly the knowledge needed to author a valid value for the single SQL 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?

States a specific verb and resource: 'Run a read-only SQL SELECT against the USDA-NRCS Soil Data Access database (SSURGO)', then scopes the schema it exposes (legend, mapunit, component, chorizon, cointerp). It explicitly positions itself against the sibling tools: 'Use for anything the point and component tools do not cover', so an agent can distinguish it from usda_soil_components and usda_soil_mapunit_at_point without opening either schema.

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?

Names the alternatives (the point and component tools) and the condition that routes to this one, plus concrete use-case examples ('soil series by county, prime farmland acreage, drainage class distributions, crop yield indices'). When-to-use and the alternative are both explicit; only an explicit when-not clause is absent.

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

All Usda Soil toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources