fema-mcp-server

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds valuable behavioral context: row count reflects actually staged data, and recommends checking truncation in the fema_search_nfip response. No contradictions 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?

The description is two sentences, each serving a distinct purpose: stating the action and providing usage guidance. No redundant text, front-loaded with core purpose.

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 (which covers return value details), the description sufficiently covers purpose, usage order, and a behavioral note on row count. It is complete for the tool's 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?

The schema already describes canvas_id with 100% coverage. The description adds context that the ID comes from fema_search_nfip response, reinforcing the parameter's usage. This extra context justifies a score above baseline 3.

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 tables and column schemas on a DataCanvas staged by fema_search_nfip. It distinguishes itself from the sibling fema_dataframe_query by specifying it should be called before querying to discover schema details.

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 advises calling this before fema_dataframe_query to discover table names, columns, and DuckDB types. It also mentions checking truncated in the fema_search_nfip response for completeness. It does not explicitly state when not to use, but the 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 indicate readOnlyHint=true and idempotentHint=true. The description reinforces this by stating 'read-only SQL SELECT' and 'Only SELECT statements are allowed.' It adds extra context: results are capped at canvas row limit, and suggests LIMIT/OFFSET or aggregation to navigate limits. This goes 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?

Two sentences plus an example, front-loaded with the core purpose. Every sentence adds value: purpose, prerequisites, constraints, example. 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?

Given an output schema (not shown but present), the description covers prerequisites, allowed operations, limitations, and examples. For a tool of this complexity, it is complete and leaves no major 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 coverage is 100%, so baseline is 3. The description adds significant value for the 'query' parameter: explains SQL constraints, provides an example, and notes row limits. For 'canvas_id', it merely restates the schema description. Overall, the extra context for query earns 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?

The description clearly states this tool runs read-only SQL SELECT queries on a DataCanvas table, specifying the verb ('run'), resource ('DataCanvas table'), and scope (aggregation, GROUP BY, etc.). It distinguishes itself from siblings by enabling analysis without re-fetching 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?

Explicitly states prerequisites: call fema_search_nfip first and fema_dataframe_describe to get table name and columns. Clearly defines allowed operations (SELECT only) and blocks DDL, DML, COPY, file-reading. Provides example SQL and mentions row limits, guiding the agent on when to use aggregation vs pagination.

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; description adds that the tool returns counties/municipalities, programs, incident period, and state info, plus chaining behavior. No destructive aspects disclosed, but consistent with read-only intent.

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 specifies action and example, second provides usage flow and chaining. No redundant content, front-loaded with key information.

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 single required parameter and existing output schema, the description adequately covers return content (designated areas, programs, incident period, state info) and integration with related tools. No 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 covers disaster_number parameter with description (e.g., 4781) and reference to fema_search_disasters. Tool description repeats the example but adds no new semantic detail beyond the parameter 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?

Clearly states it fetches designated-area rows for a specific FEMA disaster by disaster number, with an example (4781). Distinguishes from sibling tools like fema_search_disasters and 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?

Explicitly instructs to use fema_search_disasters to find disaster numbers, and describes chaining to fema_get_public_assistance and fema_get_housing_assistance. Provides clear when-to-use 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 set readOnlyHint=true, so the description does not need to reiterate read-only behavior. The description adds context about the data fields returned (registrations, amounts, inspection data), which is transparent about the output. No behavioral 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 that front-load the purpose, then detail outputs, then provide usage hints. Every sentence adds value with no 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?

Given the complexity (required disaster_number, optional type/state/limit/offset) and the presence of an output schema, the description covers the key points: which disaster data to use and how to filter. It does not explain pagination (offset/limit) or state filtering, but these are well-documented in the schema.

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?

All 5 parameters are fully described in the input schema (100% coverage). The description adds marginal value by explaining the type parameter's options and the disaster_number's source, but does not provide meaningful new information beyond the schema definitions.

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 explicitly states the action ('Retrieve Individual Assistance housing data'), the resource ('for a disaster by disaster number'), and the output (breakdowns by county/ZIP with specific data fields). It clearly distinguishes from sibling tools like fema_get_public_assistance (public vs. individual assistance) and fema_search_disasters (search vs. retrieve).

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 practical guidance: where to get the disaster number (fema_search_disasters) and how to use the type parameter. However, it does not explicitly mention when not to use this tool or compare it to alternatives like fema_dataframe_query or fema_get_public_assistance, which would help an agent avoid misuse.

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 openWorldHint, and description reinforces that by stating it shows obligated federal recovery money. Adds behavioral constraint that either disaster_number or state must be provided, and that PA projects require pa_declared: true. No contradictions 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?

Four sentences, front-loaded with the main purpose, no redundant or superfluous information. Every sentence adds necessary context about usage, prerequisites, and scope.

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 that an output schema exists, the description appropriately omits return format details. It covers the core logical constraint (one of two parameters required), a key prerequisite (pa_declared), and return fields. Could briefly mention pagination (limit/offset) implicitly covered by schema, but overall complete for the tool's 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?

With 100% schema coverage, description adds value by detailing the dependency between disaster_number and state (one must be provided), linking disaster_number to fema_search_disasters, and explaining the state parameter as browsing for a state. County filter is mentioned but not elaborated. Adds logical constraints not in 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?

Description clearly identifies the tool as retrieving Public Assistance funded project records, specifying return fields (applicant, damage category, etc.) and distinguishing it from sibling tools like fema_get_housing_assistance by focusing on PA projects specifically.

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 clear guidance on when to use disaster_number vs state, referencing fema_search_disasters for disaster_number and noting that projects exist only when pa_declared is true. Lacks explicit when-not-to-use or alternative sibling tool comparisons, but still gives actionable 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 safe read operation; description adds context about timeout risks, dataset name case-sensitivity, and error behavior (unknown_dataset error). Disclosure goes 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?

Single cohesive paragraph logically flows from purpose to specifics to advice. Every sentence contributes value. Could be slightly improved with bullet points, but current structure is effective.

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?

Description addresses dataset selection, filtering, error handling, and performance considerations. With output schema present, return values need no further explanation. Context is fully adequate for agent 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?

Schema descriptions fully cover each parameter. Description adds practical detail (e.g., propertyState recommendation, filtering advice) that enhances parameter understanding without redundancy.

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 tool as a generic OData query against any OpenFEMA v2 dataset, positioned as an escape hatch for datasets not covered by convenience tools. Examples and structure make purpose unmistakable.

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 identifies when to use (datasets not covered by convenience tools) with examples. Provides critical usage tips like using propertyState for NFIP and adding filters to avoid timeout.

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?

Beyond the readOnlyHint and openWorldHint annotations, the description explains that results are deduplicated (one disaster number) and include a designatedAreaCount field, and that the disaster number serves as a chain key for other tools. This adds valuable behavioral context without contradicting 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 (three sentences), front-loaded with the core purpose, and efficiently packs essential information including deduplication behavior, key field explanation, filter usage, and cross-reference to other tools.

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 (8 parameters, output schema present, multiple sibling tools), the description fully covers what the tool does, its unique deduplication, the relationship to other tools, and filter semantics. The presence of an output schema obviates the need to describe return fields.

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 100% schema coverage, the description adds marginal value by explaining the date filter semantics (applies to declaration date) and the declaration_type enum values. This justifies a score above the baseline of 3.

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 that the tool searches federal disaster declarations with specific filters (state, incident type, declaration type, date range, county) and returns deduplicated declaration-level summaries. This distinguishes it from sibling tools like fema_get_disaster which retrieves all rows for a specific 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?

Provides explicit usage guidance: explains declaration_type values (DR, EM, FM) with their meanings, notes that date filters apply to declaration date, and directs users to use fema_get_disaster for detailed area-level data. While it doesn't explicitly state when not to use, it effectively directs to alternatives.

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?

ReadOnlyHint and openWorldHint annotations are consistent with the description's read-only query behavior. The description details that results are either inline up to a limit or staged on a canvas, and that unfiltered access is blocked. No contradictions, but lacks mention of rate limits or cost implications.

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 yet informative, front-loading the core purpose and mandatory filter. Each sentence serves a purpose (purpose, constraint, canvas behavior). Could potentially be slightly shorter, but no redundancy.

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 (7 parameters, canvas integration, output schema), the description covers mandatory filters, return fields, and post-search workflow. It doesn't detail output schema because that's handled separately. Adequate for guiding correct invocation.

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%, but the description adds context beyond the schema, e.g., explaining that limit affects inline preview but not canvas staging, and clarifying county_code's flexible format. This aids agent understanding of parameter interactions.

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 flood insurance claims data, specifying searchable dimensions (state, county, ZIP, year range) and return fields (claim counts, amounts paid, flood zones, loss years). This distinguishes it from siblings like fema_search_disasters by focusing on claims data rather than disaster declarations.

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 mandates a state filter due to dataset size and prohibits unfiltered access. It explains canvas workflow, directing users to fema_dataframe_describe and fema_dataframe_query for further analysis. However, it doesn't contrast with other search tools like fema_query_dataset for when to choose this tool over alternatives.

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