fema_query

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

Annotations mark readOnlyHint=true, so safety is disclosed. The description adds value by noting OData $filter support and the general-purpose nature across datasets, but it does not detail pagination behavior (beyond 'top' and 'skip' in the schema), default result limits (schema says default 50), known datasets, or any service-specific quirks or rate limits. It contributes some context beyond annotations without contradicting them.

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: the first states scope and examples, the second states the key syntax feature. No wasted words; front-loaded with purpose. Every sentence serves a distinct informational 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?

For a flexible query tool with full schema coverage and readOnlyHint annotation, the description is reasonably complete. It omits an output schema, which is absent from the structured data, but the examples and syntax note help an agent. Given that it is a generic query tool, users are expected to know OData; the description could mention that no metadata/fields list is returned, but this gap is minor.

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 100%, so the schema already documents each parameter including examples. The description adds a general note about OData syntax and mentions datasets, which aligns with the schema, but it does not compensate for or add meaning beyond what the schema's per-parameter descriptions provide. Baseline 3 is appropriate because schema carries the heavy lifting.

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 is a 'General-purpose query against any OpenFEMA v2 dataset' with a specific verb 'query' and a distinct resource class. It enumerates example datasets (NFIP, hazard mitigation, mission assignments, IHP registrations) and explicitly notes OData $filter syntax, which distinguishes it from narrow, single-dataset siblings like fema_disaster_declarations or fema_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 a clear context: use this for OpenFEMA v2 datasets, listing representative use cases. It doesn't explicitly say 'use X instead' or 'don't use for Y', but given the sibling list includes separate fema_* tools, an agent can infer to prefer specific tools for declared datasets and use this for undiscovered or alternative datasets. This is clear context without formal exclusions.

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