swatgenx

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

Adds key details: short-lived (24h), requires authentication, no email needed. Annotations already provide destructiveness and idempotency hints, but description adds expiration and ownership context.

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 verb and resource, no wasted words. Efficiently conveys purpose, usage, and parameter source.

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?

Covers tool purpose, preconditions (ownership, authentication), parameter sources, and agent action (fetch ZIP). Lacks explicit return format (though implied as URL) and error handling, but sufficient for typical use.

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?

Despite 0% schema description coverage, the description only mentions that site_no/vpuid/level come from other responses, but does not explain each parameter individually, nor does it mention the api_key parameter.

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 generates a short-lived download link for a model the caller owns, and mentions that parameters come from specific sibling responses, distinguishing it from order/request tools.

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?

It explains the pull-based delivery mechanism and that the agent should fetch the ZIP, providing context on when to use (after obtaining model info from get_order_status/list_my_models).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable context: returns ladder, reports subscription status, works without key. No contradictions.

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?

Two sentences, first sentence clearly states purpose, second provides usage guidance. 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?

For a simple info tool with one optional param and no output schema, description covers what it does, when to use, and behavior conditions. Complete.

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 coverage is 0% but description explains that api_key is optional and personalizes response. Adds meaning beyond schema by describing conditional behavior.

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?

Clearly states the tool explains the SWATGenX access ladder and reports caller's tier/status with an API key. Specific verb-resource pair, distinct from sibling tools which focus on models, orders, etc.

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?

Explicitly says agents should use this to tell users what they can do and how to unlock more. Also explains behavior with and without a key, providing clear context.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds value by explaining the empty case for uncalibrated models and specifying the returned metrics. No contradictions.

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?

Two sentences, no filler. The first sentence lists the output, the second explains the parameter and edge case. Information is front-loaded and every sentence is essential.

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 simple one-parameter tool with no output schema, the description sufficiently explains the return value (including fields and empty case) and provides parameter context by referencing sibling tool search_swat_models.

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 has 0% description coverage for site_no. The description compensates by defining site_no as 'the USGS gauge or HUC outlet id from search_swat_models', providing essential context. Additional details like format or validation are not needed.

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?

Clearly states the tool returns 'full recorded calibration' for one model, listing specific metrics (method, NSE, PBIAS, etc.). The verb 'Return' is precise, and the tool is well-differentiated from sibling tools like download_model or search_swat_models.

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 mentions that site_no comes from search_swat_models, hinting at a prerequisite. However, it does not explicitly state when to use this tool versus alternatives (e.g., for checking calibration results vs. downloading model files) nor when not to use it.

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

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

Annotations declare readOnlyHint and idempotentHint as true, aligning with the description's 'check' verb. The description adds detail about the return values (state, stage, timing) and mentions authentication, which goes beyond annotation info. No contradictions.

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?

Two brief sentences that are front-loaded with the main purpose, followed by essential detail on the parameter. No unnecessary words.

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?

Despite lacking an output schema, the description provides enough high-level information for a status check tool. The sibling context includes related tools (order_model, download_model), but the description is sufficient given the simplicity.

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 parameter 'order_id' is explained as the return from 'order_model', which adds context beyond the schema. However, the 'api_key' parameter (with default null) is not mentioned, and schema description coverage is 0%, so the description partially compensates but not fully.

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 checks a model build order, listing specific return fields (state, stage, timing) and the required parameter. However, it does not explicitly differentiate from sibling tools like 'order_model', though the verb 'check' implies read-only behavior.

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 mentions that 'order_id is what order_model returned', which implies this tool is used after ordering, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it state when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds ordering and state information, and emphasizes authentication, adding value beyond structured fields.

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?

Single sentence front-loads key information; no wasted words.

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?

With no output schema, the description only hints at response order and state field but lacks details on return structure (e.g., fields, pagination). Incomplete for a list tool.

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 coverage is 0% and the description does not mention the api_key parameter or explain its purpose, leaving the agent with no guidance for the optional parameter.

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 the caller's own model build orders, newest first with states. It distinguishes from siblings like order_model or get_order_status by specifying authentication and personal scope.

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 use for viewing personal orders but does not explicitly state when not to use or provide alternatives among siblings.

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

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

Annotations already set readOnlyHint=false and destructiveHint=false, but the description adds key behavioral details: authenticated usage, quota consumption, and typical build time (20 min - 2 h). It does not mention idempotency or error states, but the additional context is valuable beyond annotations.

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 concise with three sentences, each adding distinct value: purpose, input options, output and timing, and authentication source. No redundant information, and the most critical information is 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 complexity (4 parameters, no nested objects, no output schema), the description covers the main inputs, output, and flow. It explains the return type (order_id) and follow-up (polling). However, it omits the force_rebuild parameter and does not discuss error handling or quota limits, leaving minor 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?

Schema description coverage is 0%, so the description must compensate. It clarifies that usgs_station and huc12_outlet are mutually exclusive alternatives, and that api_key can come from header or argument. However, it does not explain force_rebuild, leaving one out of four parameters undocumented. This partial coverage is adequate but not comprehensive.

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's purpose: 'Order a real SWAT+ model build'. It distinguishes from sibling tools by specifying that it returns an order_id to poll with get_order_status, and mentions authentication and quota consumption, differentiating from download_model and get_order_status.

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 provides explicit guidance on input alternatives ('Provide EITHER a USGS gauge id OR a 12-digit HUC12 outlet') and the follow-up action (poll with get_order_status). It implies when to use this tool (initiate a model build) but does not explicitly state when not to use it, such as when a model already exists.

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

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

Annotations already indicate read-only and non-destructive behavior. The description adds behavioral context such as coordinate system (EPSG:4326), radius limit (~50 km), and data scope (7.9M wells, 46 states), which aids understanding, though it could clarify performance or pagination.

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 concise with two sentences, front-loading the purpose. The detailed data statistics (28.8M intervals, 7.9M wells) are relevant but slightly lengthy; overall, minimal waste.

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 no output schema, the description covers core behavior and constraints but omits details about the response format and the 'limit' parameter, leaving some ambiguity for an agent.

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 has 0% description coverage. The description explains lat/lon in decimal degrees and radius_km up to ~50, but does not mention the 'limit' parameter or its default. Thus, it partially compensates for missing schema descriptions.

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 queries a specific national groundwater inventory near a point and returns nearest wells with lithology counts and total logged depth. It uses a specific verb and resource, distinguishing it from sibling tools like query_pfas.

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 usage for finding nearest wells at a location but does not explicitly state when to use or avoid this tool, nor does it reference sibling tools or prerequisites.

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

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

Annotations declare readOnlyHint and idempotentHint true, and destructiveHint false. The description adds context about returning latest concentration and including VLM-extracted records, which goes beyond the annotations. However, it lacks details on pagination or rate limits.

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 compact (two sentences) with no extraneous detail. It front-loads the purpose and data source, then covers filters and output concisely.

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 simple query tool with three optional parameters and no output schema, the description covers the key inputs, output behavior, and usage context (research only). It could mention the limit parameter's role or default, but overall it is sufficiently complete.

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. It explains the state and analyte parameters with examples and constraints (two-letter state, common analytes). The limit parameter is not described, leaving a minor gap.

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 queries the SWATGenX national PFAS inventory, specifying it returns stations with location and latest concentration. This distinguishes it from sibling tools like query_groundwater which deal with different data.

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 indicates when to use (research/screening) and provides a caveat that it is not regulatory. However, it does not explicitly mention when not to use or compare to alternatives, though siblings are different enough.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: it returns buildability, existence, and ordering endpoint, and explicitly states it does NOT place an order, which requires an authenticated account. No contradictions.

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 three sentences, each serving a distinct purpose: stating the action, specifying inputs, and clarifying behavior. No fluff, though it could be slightly more compact.

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 low parameter count and absence of output schema, the description covers purpose, inputs, return values, and limitations. It lacks explicit handling of missing or invalid inputs (e.g., if both provided), but is otherwise complete.

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?

With 0% schema description coverage, the description fully compensates by explaining both parameters ('EITHER a USGS gauge id (usgs_station) OR a 12-digit HUC12 outlet (huc12_outlet)'), their formats, and mutual exclusivity.

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's purpose: previewing a SWATGenX model build for a CONUS catchment. It uses specific verbs ('preview', 'returns') and distinguishes from sibling tools like 'order_model' by emphasizing it does not place an order.

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 provides clear context on when to use the tool (as the entry point for requesting a model) and specifies the input options (usgs_station or huc12_outlet). It implies when not to use (when placing an order), but does not explicitly list alternatives or exclusions.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds that returns include model id, state, size, and headline NSE when present, supplementing annotations without contradiction.

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 purpose, each sentence adds unique value. No redundant or extraneous content.

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?

No output schema, but description covers return fields. Missing 'limit' parameter explanation is a minor gap. References sibling for deeper metrics. Adequate for the complexity.

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 coverage is 0%, so description must compensate. It explains 'state' (two-letter), 'calibrated_only', and channel-count bounds, but does not mention 'limit' parameter. Adds moderate value over bare schema.

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 states 'Search the public SWATGenX example-model catalog' with specific verb and resource, and differentiates from sibling 'get_model_calibration' by directing to it for full metrics.

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 lists filterable parameters (state, calibrated_only, channel-count bounds) and guides to use 'get_model_calibration' for full metrics, providing clear context for usage without explicit when-not-to-use scenarios.

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