fema-mcp-server

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false. Description adds value by stating the canvas holds the full NFIP claims result set and row count equals total available, which helps the agent understand the data scope. 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 states purpose, second gives usage guidance and additional context. No filler, every sentence serves a clear role.

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 tool has an output schema (though not displayed), the description covers purpose, prerequisite relationship, and data scope. No critical missing info; the agent knows exactly when and why 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?

Single parameter canvas_id has schema description 'Canvas ID from the fema_search_nfip response.' The description adds context by linking the ID source, which is beyond the schema. With 100% coverage baseline 3, this extra context merits a 4.

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?

Description uses specific verb 'list' and resources 'tables and column schemas' on a DataCanvas. It clearly differentiates from sibling tools like fema_dataframe_query by stating its prerequisite role.

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 states 'Call this before fema_dataframe_query' and explains what it discovers (table name, column names, DuckDB data types). Lacks explicit when-not-to-use, but context implies it's only needed for query preparation.

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 idempotentHint. The description adds value by specifying that only SELECT statements are allowed and that DDL/DML/file-reading functions are blocked, providing concrete constraints beyond the 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 value. It is front-loaded with purpose, followed by usage guidelines, and ends with constraints. 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?

Given the tool's complexity (SQL query) and the availability of an output schema, the description provides complete guidance: workflow (describe first), query constraints, example, and parameter meaning. It covers all necessary context.

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 100%, so the schema already describes parameters. The description adds meaningful context by including an example SQL query and mentioning the need to use the table name from fema_dataframe_describe, which aids correct invocation.

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 it runs read-only SQL SELECT against a staged DataCanvas table, specifying the verb (query), resource (DataCanvas table), and scope (full NFIP claims). It distinguishes from siblings like fema_search_nfip and fema_query_dataset.

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 explicitly instructs to call fema_dataframe_describe first to get table/column names, and notes that only SELECT is allowed. However, it does not explicitly mention when not to use or provide alternative tools for non-SELECT operations.

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?

The description confirms the read-only nature hinted by annotations and adds behavioral context about the return schema (counties, municipalities, programs, incident period, state info) and chaining, 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 with no redundancy: purpose, usage guidance, chaining. Each sentence is essential and 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 an output schema exists, the description covers the key return aspects and the chaining relationship. For a single-parameter read-only tool, this is 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 already describes disaster_number; the description adds context with an example (4781) and the source (fema_search_disasters). This adds value beyond the schema and compensates for any lack of enum or deeper semantics.

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 fetches designated-area rows for a specific disaster by number, including the return content (county, programs, incident period, state info). It distinguishes from sibling tools by naming them explicitly.

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?

Provides explicit guidance: use fema_search_disasters to find the number first, and explains that the returned disaster_number chains to fema_get_public_assistance and fema_get_housing_assistance. This tells both when to use and what not to use.

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 openWorldHint=true. The description adds context about data availability (only when ia_declared: true), which is 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?

Three sentences, each carrying essential information: what it does, what it returns, and prerequisites. No redundancy or fluff.

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 return data types, prerequisite condition, and cross-references to sibling tools. With an output schema present, description 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 coverage is 100% (baseline 3). The description adds value by explaining how to obtain disaster_number from another tool and the purpose of the 'type' parameter, going beyond 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 retrieves IA housing data by disaster number, listing specific data fields (valid registrations, IHP amounts, etc.) and distinguishes it from siblings like fema_get_public_assistance.

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 explicitly tells when to use (when ia_declared is true) and how to obtain parameters (disaster_number from fema_search_disasters, check via fema_get_disaster). It lacks explicit when-not alternatives but implies usage constraints.

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 and openWorldHint. Description adds PA-specific context (obligation amounts, status, program requirement) which aids understanding, but does not cover rate limits or data freshness.

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, no wasted words. Front-loaded with purpose, then constraints, then prerequisite. Each sentence adds value.

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 output schema present, description covers purpose, parameter usage, prerequisite, and scope alternatives. Complete for a retrieval tool with clear annotations.

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 100%, so baseline 3. Description adds meaning by stating mutual exclusivity of disaster_number and state, and hints for county filter and sourcing disaster_number from sister tool.

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?

Clear verb+resource: 'Retrieve Public Assistance (PA) funded project records'. Mentions specific returned fields and distinguishes from siblings by referencing disaster_number from fema_search_disasters and PA program declaration.

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 states when to use disaster_number vs state, and mentions prerequisite (PA program declared). Does not explicitly state when not to use, but context is clear.

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 and openWorldHint=true. Description adds behavioral context: potential timeout on large datasets without proper filters, unknown dataset error behavior, and that parameters are raw OData expressions. No contradiction with 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?

Description is front-loaded with main purpose, then examples, then specific usage tips. Each sentence adds value, though some length could be trimmed. Overall well-structured for quick comprehension.

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 tool's generic nature and the presence of an output schema, the description covers error conditions, performance considerations, and dataset-specific quirks. It doesn't detail return format, but that's standard OData and known from the schema. Adequate for complex generic query 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 100%, so baseline is 3. Description adds value beyond schema: specifies single quotes for string values in filter, mentions case-sensitivity for dataset, clarifies select is comma-separated, and explains orderby expression format. This enriches semantic understanding without repetition.

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?

Description clearly states it's a generic OData query for any OpenFEMA v2 dataset, explicitly positioning it as an escape hatch for datasets not covered by convenience tools. Provides concrete dataset examples (FimaNfipPolicies, etc.), distinguishing it from specialized sibling 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?

Explicitly says 'the escape hatch for datasets the convenience tools do not cover' and gives specific when-to-use guidance. Includes critical tips: for NFIP Policies use propertyState, always include a county or ZIP filter to avoid timeout, and notes that unknown dataset names return an error.

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?

Discloses deduplication behavior (each disaster number appears once), return of designatedAreaCount, and date filter application. Annotations (readOnlyHint, openWorldHint) are consistent and complemented by behavioral details. No 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?

Concise: two sentences plus additional usage notes. Every sentence adds value—no fluff. Front-loaded with main purpose and key details.

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 8 parameters, output schema exists, and no required params, the description is complete. It explains result format, deduplication, and cross-tool references. Covers all necessary context for correct usage.

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 100%, yet description adds value: explains declaration_type filter options, that date filters apply to declaration date, and that disaster number is the chain key for related tools. Enriches parameter understanding beyond 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 searches federal disaster declarations with specific filters (state, incident type, declaration type, date range, county). It specifies the output is deduplicated declaration-level summaries with designatedAreaCount, and distinguishes from sibling tools like fema_get_disaster for detailed rows.

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?

Explicit guidance: declares when to use fema_get_disaster for detailed area rows, explains declaration_type enum values (DR, EM, FM), clarifies date filter behavior, and provides chain key usage. Clearly differentiates from 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 indicate readOnlyHint=true and openWorldHint=true, making the safe read operation clear. The description adds valuable behavioral context about canvas integration: results are staged for SQL aggregation if canvas is enabled and results exceed inline preview. However, it does not detail rate limits or what happens when the canvas is not enabled (it says results returned inline up to the limit).

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 (six sentences) and front-loaded with the primary purpose. Every sentence adds essential context: state requirement, dataset size, canvas behavior, and tool alternatives. No unnecessary words or redundancies.

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 presence of an output schema (not shown but mentioned) and comprehensive input schema coverage, the description adequately explains the tool's purpose, required parameters, return fields, and special behavior (canvas staging). It covers all necessary context for an agent to select and invoke the tool correctly.

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 input schema covers all 7 parameters with descriptions, achieving 100% coverage. The description reinforces the state requirement and mentions year range and canvas_id, but does not add substantial meaning beyond what the schema already provides. Baseline 3 is appropriate when schema documentation is complete.

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 searches NFIP claims data by state, county, ZIP code, and year range, and specifies the return fields (claim counts, amounts, flood zones, loss years). This distinguishes it from sibling tools like fema_search_disasters and fema_query_dataset, as it is specific to NFIP claims.

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 explicitly states that state is required and unfiltered access is prohibited due to dataset size (2.7M rows). It provides guidance on when to use fema_dataframe_query (when results exceed inline preview with canvas enabled) and recommends using fema_dataframe_describe to inspect the staged table schema. This clearly outlines when to use this tool versus alternatives.

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