fema-mcp-server

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

Annotations already declare read-only and idempotent behaviors. Description adds context about row count reflecting actual staged data and cross-references truncated status, which 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, no wasted words. Front-loaded with purpose, followed by usage guidance. Ideal length 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 simple single-parameter schema and presence of output schema (implied), the description covers all essential aspects: purpose, when to call, how to interpret results, and relevant warnings.

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?

Only one parameter (canvas_id) with 100% schema coverage. Description adds value by specifying it comes from 'fema_search_nfip response', providing source context beyond the schema description.

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 the verb 'list' and the resource 'tables and column schemas on a DataCanvas', referencing the specific staging tool. It distinguishes from sibling by indicating it should be called before fema_dataframe_query.

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 call this before fema_dataframe_query to discover table/column names and types, and advises checking the 'truncated' field in the prior response. Provides clear when and how 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 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?

Annotations declare readOnlyHint=true and openWorldHint=false, so the description's claim of 'fetch' aligns. Description adds that it returns 'every county/municipality designated under the declaration along with programs activated, incident period, and state info', which is useful context beyond annotations. However, it does not disclose potential behaviors like pagination, error handling for invalid numbers, or performance characteristics for large disasters.

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, zero wasted words. First sentence states the core purpose with a concrete example. Second sentence provides immediate usage guidance and chaining context. Every sentence earns its place.

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 simplicity (one optional parameter, read-only, output schema provided), the description covers the essential aspects: what it returns, how to get input, and how to use the output. It does not mention error cases, but the output schema and runtime may handle that. Overall, it is sufficiently complete for an agent to invoke 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?

Schema has 100% coverage for the single required parameter 'disaster_number'. Description adds an example (e.g., 4781) and states to obtain from fema_search_disasters, providing meaningful guidance beyond the schema's description. This elevates the 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?

Description clearly states verb 'fetch' and resource 'designated-area rows for a specific FEMA disaster', with a concrete example (disaster number 4781). It distinguishes from sibling tools like fema_search_disasters (which finds disaster numbers) and fema_get_public_assistance/fema_get_housing_assistance (which chain from the result).

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 directs users to first use fema_search_disasters to obtain the disaster number, and indicates that the returned disaster_number can chain to fema_get_public_assistance and fema_get_housing_assistance. It does not explicitly state when not to use this tool, but the context is clear: use when you have a specific disaster number.

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, so the agent knows this is a safe read operation on external data. The description adds specific behavioral context about returned fields (valid registrations, IHP amounts, repair/rental amounts, inspection data), which is valuable beyond the annotations. 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 front-load the core purpose and output, then parameter hints. Every clause adds value, no filler.

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 and annotations covering readOnly/openWorld, the description is fairly complete. It covers key return fields and parameter usage. However, it does not explicitly mention pagination behavior (offset, limit) or potential limitations, though these are covered 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?

With 100% schema description coverage, the schema already documents all 5 parameters. The description adds marginal value by reinforcing that 'type' selects owners/renters and that disaster_number comes from fema_search_disasters. This is helpful but not transformative beyond the schema's own 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 action 'Retrieve', the resource 'Individual Assistance housing data for a disaster by disaster number', and details the returned data (breakdowns by county/ZIP, registrations, amounts, inspection data). It references the sibling tool fema_search_disasters for getting the disaster number, distinguishing it from related tools like fema_get_disaster or 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 provides context on how to get the disaster_number and select data type, but does not explicitly state when to use this tool versus alternatives like fema_get_disaster for raw disaster info or fema_get_public_assistance for public assistance data. The guidance is clear but lacks exclusionary or comparative statements.

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 and openWorldHint. Description adds behavioral context by stating the tool shows 'where federal recovery money was obligated' and listing return fields. Does not contradict 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 well-structured sentences, front-loaded with the core purpose, no superfluous words. Every sentence serves a clear function.

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 5 parameters (none required), output schema exists, and high schema coverage, the description provides sufficient context for usage, data returned, and relationships. Could mention pagination details (offset/limit) but those are in 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?

Schema coverage is 100%. Description adds crucial semantics: clarifies that disaster_number or state must be provided (mutual exclusivity), explains the origin of disaster_number, and notes county filter is a substring search. Adds significant value 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?

Clearly states it retrieves FEMA Public Assistance project records for a disaster or state, and specifies the exact data fields returned (applicant, damage category, project size/status, federal share, total obligated). Differentiates from sibling tools by referencing disaster_number from fema_search_disasters and the pa_declared: true condition.

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 guidance on when to use disaster_number vs state, and notes that PA projects exist only when pa_declared: true. Lacks explicit when-not-to-use or alternatives, but contextual cues are strong.

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 discloses critical behavioral traits: raw OData parameter acceptance, timeout risk without filtering, case-sensitive dataset names, and the exact error for unknown datasets. This adds significant context for safe invocation.

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 a single, dense paragraph that efficiently conveys the core purpose, usage guidance, and important warnings. Every sentence is meaningful, though it could benefit from slightly more structured formatting (e.g., bullet points) for readability. Nevertheless, it is concise 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 the tool's generic nature and the existence of an output schema, the description covers all essential aspects: what it does, when to use it, how to avoid common pitfalls (timeout, case sensitivity, error handling), and parameter usage. It is comprehensive for an escape hatch 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?

With 100% input schema coverage, the schema already documents parameters well. The description adds value by explaining the OData nature of filter, select, and orderby, providing usage examples, and warning about propertyState for NFIP datasets. This enriches understanding beyond the 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 clearly states it performs a generic OData query against any OpenFEMA v2 dataset, explicitly positioning it as an escape hatch for datasets not covered by convenience tools like fema_search_nfip or fema_get_disaster. It provides specific dataset examples and distinguishes its role from 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?

The description explicitly tells when to use this tool (for datasets not covered by convenience tools) and when not to (e.g., for NFIP Policies it advises using propertyState and including county or ZIP filters to avoid timeout). It provides clear context and alternative tools, making it easy for an AI agent to decide.

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, and the description complements this by detailing that results are deduplicated and that date filters apply to the declaration date. 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?

The description is a single dense paragraph, but every sentence adds value. It could be slightly more structured (e.g., bullet points), but it remains concise and 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?

With 8 all-optional parameters and an output schema, the description provides sufficient context: deduplication behavior, designatedAreaCount field, and chaining to other tools. The annotations provide readOnly/openWorld hints, making the tool well-described.

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 has 100% coverage with descriptions for all 8 parameters. The description adds value by explaining the meaning of declaration_type values and clarifying that date filters apply to declaration date, improving semantic understanding beyond the 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 clearly states the tool searches federal disaster declarations with specific filters (state, incident type, declaration type, date range, county) and returns deduplicated summaries. It distinguishes itself from sibling tools like fema_get_disaster by noting the disaster number is a chain key for other 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?

The description explicitly provides when-to-use guidance, explaining declaration type values (DR, EM, FM) and directs users to fema_get_disaster for full detail. This clearly differentiates usage from sibling tools.

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 annotations (readOnlyHint, openWorldHint), the description details behavioral traits: results staging on canvas when enabled, inline return limit, mandatory state filter. No contradictions with annotations. It fully discloses how results are handled and constraints.

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 around 150 words and well-structured: purpose, constraints, canvas behavior, sibling references. Every sentence serves a distinct purpose. Slightly verbose in explaining canvas but overall efficient.

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, large dataset), the description covers purpose, required constraints, parameter details, return values, and integration with siblings. Output schema is separate but mentioned. Complete for an agent to select and invoke.

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 100% schema coverage, the description adds significant meaning: explains that state is required, limit affects inline preview (overridden by canvas), canvas_id ties to prior call, county_code accepts both formats. This goes beyond baseline 3 by clarifying usage nuances.

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 specific fields (state, county, ZIP, year range) and returns specific attributes (claim counts, amounts, flood zones, loss years). It distinguishes from siblings like fema_dataframe_query (for SQL aggregation) and fema_dataframe_describe (schema inspection), making the purpose unambiguous.

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 that state is required and unfiltered access is prohibited due to dataset size. Provides clear context on when to use canvas (when DataCanvas enabled and results exceed preview) and when to use siblings (fema_dataframe_describe before writing SQL, fema_dataframe_query for aggregation). No ambiguity.

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