faa-aircraft-registry-mcp-server

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds specific behavioral context (decoding to specifications from reference table) and lists return fields, which is consistent and valuable.

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 concise sentences with no wasted words. First sentence lists specific outputs, second provides usage guidance.

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 full schema coverage, clear annotations, and existence of output schema, the description is complete. It provides necessary context for 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 description coverage is 100% and already includes the parameter's meaning, format, and example. The description does not add new parameter-level information 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 decodes a 7-character FAA manufacturer/model/series code to a list of aircraft specifications. It distinguishes the tool from siblings by mentioning faa_search_aircraft_types for code discovery.

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 'Use faa_search_aircraft_types first to discover a code by manufacturer or model name,' providing clear guidance on when to use this tool vs. 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?

Beyond annotations (readOnly, idempotent), the description adds value by detailing the priority order, the definitive recordType return, and that 'unknown' is a valid response.

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 core action, each sentence informative with 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 one simple parameter, presence of output schema, and comprehensive coverage of behavior and edge cases, the description is fully 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%, and the description adds meaning by clarifying input formats ('N12345' or '12345') and shape constraints, going beyond the schema's 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?

The description clearly states the tool resolves registration and airworthiness status across three status files in priority order, and distinguishes itself from sibling faa_lookup_registration by handling inactive numbers.

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 tells when to use this tool (when a number may be inactive) versus faa_lookup_registration, and explains the behavior for never-issued numbers.

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 context about relational joins, decoded fields, and the ownerRedacted flag. No contradiction. Could mention error responses but not required given 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 adding essential information, front-loaded with the core function. No unnecessary words. Optimal length for a simple lookup tool.

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 one parameter and an output schema, the description covers everything: what it does, input formats, when to use alternative tools, and notes a key output field (ownerRedacted). 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 the parameter with 100% description coverage; the description adds value by explaining the accepted formats (with/without leading N) and shape (1–5 chars, digits and optional letters).

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 decodes a US civil aircraft N-number to a full registration record, listing specific fields (make/model, engine, etc.). It distinguishes itself from sibling tools like faa_get_registration_status by noting it does not handle inactive numbers.

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 (decode one N-number) and when not to (inactive numbers → use faa_get_registration_status). Also clarifies input formats ('N12345' or '12345').

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 indicate readOnly and idempotent. Description adds that the response reports totalCount and provides nextOffset for pagination, and that at least one filter is required. This adds value beyond 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, then usage guidance, then pagination details. Every sentence adds value; no wasted words. Excellent structure.

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 (5 parameters, output schema exists) and high schema coverage, the description covers key points: purpose, required-at-least-one filter, pagination mechanism, and relationship to sibling. Output schema handles return details, so 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% with descriptions for each parameter. The description adds the important constraint that at least one filter is required, which is not in the schema (no required fields). This provides critical usage context that the schema alone lacks.

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 the FAA aircraft reference table by multiple criteria (manufacturer/model, type code, category code) and returns 7-character codes and specifications. It distinguishes itself from siblings like faa_get_aircraft_type by noting to use this tool first to find a code by name.

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 advises using this before faa_get_aircraft_type and notes 'at least one filter is required.' It also explains pagination with nextOffset, providing clear guidance on usage. Could be slightly more explicit about when not to use, but overall good.

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 idempotentHint annotations, the description discloses critical behaviors: at least one filter is required, owner-name search may be unavailable depending on deployment, and pagination behavior (totalCount and nextOffset). 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 efficiently structured: first sentence states purpose and key filters, then details search type, constraints (at least one filter), deployment-specific note, and pagination. No redundant information; 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 seven parameters and an output schema, the description covers all essential aspects: filter options, required inputs, deployment variability, pagination mechanics, and linkage to a sibling tool for detailed lookups. The presence of an output schema reduces need to describe return fields, so 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 coverage is 100%, but the description adds value by clarifying that searches for makeModel and ownerName are full-text, while state, aircraftType, and modeSCode are exact matches. It also flags the conditionality of ownerName parameter based on deployment config.

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 searches active US civil aircraft registrations by multiple filter criteria (owner name, make/model, state, aircraft type, Mode S code). It distinguishes itself from sibling tools like faa_lookup_registration by noting it returns summaries for drilling into 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 provides explicit guidance on when to use alternative filters when owner-PII redaction is active, and explains pagination using nextOffset. It implicitly suggests using faa_lookup_registration for detailed lookups after search, but could be more explicit about when to use other sibling search tools.

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