fcc-spectrum-mcp-server

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

Annotations already carry the safe-read profile (readOnlyHint, idempotentHint, openWorldHint=false), so the description's value is in edge-case behavior: non-coordinate filings are dropped, mobile/temporary areas are returned at their center with radiusKm and match on center-in-radius, and the active-status default. That is substantive beyond the structured fields, though the status default is also visible in the schema.

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?

Front-loaded with purpose and ordering, then edge cases; every sentence carries information. The mid-sentence enumeration of returned fields is slightly redundant given an output schema exists, but it costs little and the whole is a tight paragraph.

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 12-parameter, defaulted, paginated search tool with an output schema and full annotation coverage, the description supplies the remaining operational context an agent needs: defaults, exclusion behavior, and where to go for the one class of records this tool cannot return.

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 baseline is 3, but the description adds cross-parameter semantics not obvious from the schema alone: coordinates accept decimal degrees or DMS strings, and the center-radius matching rule explains how radius_km interacts with mobile/temporary-fixed records. Frequency overlap matching is also clarified, though much of it is echoed in 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?

States a specific verb and resource ('Find FCC-licensed transmitter sites within a radius'), fixes the ordering ('nearest first') and enumerates the salient returned attributes. It also differentiates itself from siblings by directing market-area license lookups to fcc_spectrum_search_frequencies.

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?

Gives explicit when-to-use conditions (radius search near a coordinate), when-not (locations filed without coordinates are not returned; market-area licenses go to another tool), and the default filter state ('active by default'). The named alternative tool and the condition selecting it are spelled out, leaving nothing to inference.

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?

With annotations already covering the read-only/idempotent safety profile, the description adds substantial behavioral context beyond them: paging caps (50 locations, 100 antennas, max_frequencies rows, 100 leases), the nextLocationOffset/nextLeaseOffset paging protocol, truncation order ("rows beyond it are dropped from the last locations first"), the dedup rule for callsigns shared by several records, and the filter that technical detail is kept only for active, pending-legal, and term-pending records.

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?

Purpose and scope are front-loaded, and the dense later clauses about paging, detail retention, and dedup all carry information an agent needs. It is a single long semicolon-chained passage rather than cleanly separated sections, which slightly hurts scannability.

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?

An output schema exists, so return values need no explanation, yet the description still tells the agent what record types exist (geographic-area licenses with market/spectrum blocks, lease links in both directions) and how to page large records. Nothing needed to call this correctly appears to be missing.

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 all six parameters with patterns, defaults, and constraints; that sets the baseline at 3. The description reinforces the meaning of the offsets and max_frequencies but adds little semantic detail the schema does not already carry.

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 opens with a specific verb and resource ("Fetch one FCC ULS license or spectrum lease in full") and enumerates the returned structure down to antenna emission designators, so an agent knows exactly what this tool produces. It also names the two lookup keys (callsign, USI) that separate it from the search siblings.

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?

Usage context is implied clearly: usi values come from fcc_spectrum_search_licenses / find_transmitters / search_frequencies, and location_number comes from find_transmitters or search_frequencies results, which routes the agent to use this after searching. There is no explicit when-not statement or direct contrast with fcc_spectrum_search_licenses beyond this sourcing of arguments.

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, idempotentHint and openWorldHint=false, so the safety profile is covered structurally. The description adds genuinely useful context beyond that: this lookup works even before the index is built, and the coverage branch reports record counts and last-updated timestamps.

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 dense sentences, front-loaded with the primary purpose (decode codes) followed by the secondary one (report coverage). Every clause earns its place and there is 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?

An output schema exists, so return values need not be described, and the description covers both invocation modes plus the pre-index availability. Only the `filter` parameter's behavior is left entirely to the schema, which is acceptable given the schema documents 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?

Schema description coverage is 100%, with the enum values and the filter semantics fully documented in the schema itself. The description restates the same vocabulary list already enumerated in the `topic` enum and says nothing about the `filter` parameter, so it adds little beyond the schema. Baseline 3 is appropriate.

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?

States a specific dual purpose — decoding FCC ULS code vocabularies or reporting index coverage — and enumerates the exact vocabularies (radio services, license statuses, location types, antenna types, applicant types, operator classes). This clearly separates it from the find/get/search sibling tools, which operate on records rather than code lookups.

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?

'Decode FCC ULS codes used by the other tools' establishes the context (a helper for interpreting values returned by siblings), and 'Works before the index is built' signals a prerequisite-free availability window. No explicit when-not guidance or named alternative is given, but the usage 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 cover safety (readOnly, idempotent, closed-world), but the description adds substantive behavior: the divergent row shapes for site vs market/lease records, the coverage gap that PALs file no frequency, and the default live-status filter. It doesn't mention pagination semantics beyond the schema's cursor/limit, but the depth here exceeds the annotation bar.

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, purpose front-loaded, with the routing advice appended rather than buried. The long semicolon-delimited enumerations of license types and filters are dense but each clause carries distinct 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?

An output schema exists, so return values need no explanation. For a 12-parameter search tool, the description covers purpose, result row semantics, coverage exclusions, and sibling alternatives – nothing an agent needs to invoke it correctly is missing.

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 baseline is 3. The description enumerates the filterable dimensions (state, radio service, licensee, FRN, market code, live status) but adds little syntax or semantics beyond what the schema already documents for each parameter.

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?

Opens with a specific verb+resource+scope: 'Find FCC ULS authorizations whose occupied band overlaps a frequency or band.' It then distinguishes result shapes (one row per site vs per spectrum block), which no sibling tool does, so an agent can route correctly without opening schemas.

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 routes two cases to alternatives: 3.5 GHz Priority Access Licenses have no frequency and must go through fcc_spectrum_search_licenses with radio_service PL, and coordinate-proximity transmitter searches belong to fcc_spectrum_find_transmitters. Both when-not conditions are named with the substitute tool.

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 mark it read-only and idempotent, so the safety profile is covered. The description still adds meaningful behavior beyond that: the default-to-active filtering and the word-prefix (non-fuzzy) matching semantics of licensee names, which an agent could otherwise get wrong.

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?

Front-loads the core purpose, then adds constraint, default-status, and matching-semantics sentences. Four sentences, all carrying distinct information with no repetition, though it is dense enough that a slight trim would improve it.

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 an output schema present, return values need not be explained. The description fully covers the invocation constraints, default filtering, status override, and matching caveats for a nine-parameter search tool, leaving nothing an agent needs missing.

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 documents each parameter's format, keeping this near the baseline of 3. The description goes beyond it by stating the cross-parameter constraint (at least one of callsign/licensee/frn/market_code/radio_service/state required), which is not expressed via JSON Schema required fields, plus the status-narrowing rule.

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?

States a specific verb (Search) and resource (FCC ULS licenses and spectrum leases), enumerates the filterable fields, and precisely describes the return shape (one row per record with USI). It also names the follow-up sibling fcc_spectrum_get_license, so an agent can distinguish it from find_transmitters and search_frequencies.

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?

Gives concrete conditions: at least one of the six search fields is required, status only narrows, and status "any" is needed to include expired/cancelled/terminated records. It explains the follow-up tool by name, but does not explicitly contrast against the other search siblings, keeping it short of a 5.

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