telcodata

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

With no annotations, the description carries the full burden. It usefully discloses the Canadian fallback behavior (returns a Geolocator URL instead of proxying), but says nothing about the U.S. return format, error behavior, or the API-key/auth situation that the schema only partially covers.

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 tight sentences with zero waste; the primary U.S. behavior is front-loaded before the Canadian edge case.

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?

No output schema and no annotations, and the description doesn't describe the U.S. return value or which inputs are actually required to succeed. It covers the core intent and the Canada branch but leaves real gaps for an agent trying to call it 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 description coverage is only 17% across 6 parameters, so the description must compensate and largely doesn't. It explains nothing about which of city/state/street/postal_code are needed, what 'language' (en/fr) affects, or how api_key interacts with env 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?

States a specific verb (geocode) and resource (U.S. street address) plus the backing data source (TIGER/Line). The geographic scoping immediately distinguishes its behavior from a generic geocoder.

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?

Clearly tells the agent to use this for U.S. addresses and to expect a URL rather than a proxied query for Canadian ones. It gives a clear context for use, though it doesn't address what to do when address parts are missing (0 required params).

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 no annotations, the description carries the full burden and does disclose the key trait: metadata is returned without transferring file contents, and it enumerates the returned fields (filename, access level, availability, existence, last-updated). It stops short of stating authentication requirements or what happens with an invalid/expired hash, so not a 5.

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 filler, with the scope-limiting clause ('without transferring file contents') front-loaded before the usage guidance. Every clause carries actionable 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?

No output schema exists, so the description compensates by naming the metadata fields returned, and the params are fully covered by the schema. Minor gap: no mention of authentication expectations in prose or behavior on an unknown/expired hash, which matters for a 'paid download' resource.

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 download_hash's origin ('Opaque download hash returned by list_downloads') and api_key's optionality are already documented in structured fields. The description reinforces the dependency on list_downloads but adds no format, constraint, or meaning beyond the schema — 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?

States a specific verb and resource ('Fetch metadata for a specific paid download') and immediately delimits scope with 'without transferring file contents', which separates it from any content-download sibling. An agent can distinguish this from list_downloads or lookup tools without opening a schema.

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 names the prerequisite/alternative ('Use after list_downloads') and enumerates the user intents that should trigger it (suggested filename, access level, availability, file existence, last-updated time). Both the when and the preceding tool are given, 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 no annotations, the description carries the full burden and does disclose the key behavior: aggregate vs. block-level results, the meaning of thousands=-1, and the fields returned. It omits auth/permission behavior (deferred to the api_key schema field) and says nothing about what happens when a prefix is not found.

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 is front-loaded in the first sentence, followed by usage and flag guidance. The TelcoData field enumeration is useful but list-heavy and the most expendable sentence in the block.

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?

There is no output schema, and the description compensates by enumerating the returned fields and explaining the thousands sentinel values. For a two-required-parameter lookup, an agent has everything needed to call it and interpret the response.

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 would be 3; the description does add real meaning for include_blocks and the thousands-digit semantics, which lifts it slightly. But npa/nxx/api_key are still only explained by the schema, so the uplift is partial.

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 ("Look up a single NANP NPA-NXX exchange/prefix") with the exact identifier shape. It never names the near-duplicate sibling get_exchange_thousands, though the include_blocks sentence implicitly separates aggregate prefix lookups from block-level ones.

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 a concrete trigger ("user has an area code plus exchange such as 425-555") and explicit conditions for the include_blocks flag (portability/pooling detail, carrier variance by thousands digit). It stops short of naming an alternative tool or stating when not to use this one.

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 no annotations, the description carries the burden and does disclose important behavior: fallback reporting when no block row exists, the meaning of the -1 aggregate/default row, and common TelcoData fields returned. It does not discuss auth requirements or rate limits, but the core lookup behavior is transparent.

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 front-loaded with the use case and then moves to fallback behavior and field semantics. It is reasonably efficient, though the field list and repeated aggregate explanation add some length beyond the minimum needed.

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?

There is no output schema and no annotations, but the description gives common return fields and explains the fallback-to-aggregate behavior. It is nearly complete for a read-only lookup, with only minor gaps around error and auth details already covered by 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?

Schema coverage is 100%, so the baseline is 3. The description adds real-world meaning beyond the schema by explaining the seventh digit, individual pooling blocks 0-9, and the special -1 whole-prefix aggregate.

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 states a specific verb and resource: looking up one thousands block within an NPA-NXX. It also scopes the tool with the seventh-digit example and distinguishes the granularity from broader exchange or number lookups in the sibling set.

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?

It gives explicit usage conditions: when the user provides the seventh digit or asks who owns/routes a specific block. It does not name alternative sibling tools or state when not to use it, so it falls short of the top score.

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?

No annotations exist, so the description carries the full burden. 'Return' signals a non-mutating read and the diagnostic framing implies safety, but it says nothing about rate limits, error behavior when the key is invalid or expired, or what the profile object contains beyond four named fields. Adequate but not rich.

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 waste, purpose front-loaded before the usage guidance. Nothing could be removed without losing meaning.

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 zero-required-param identity tool with no output schema and no annotations, the description covers purpose, trigger condition, and the fields the profile exposes. An agent has enough to decide to call it; only error/failure behavior is left implicit.

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 single api_key parameter is fully documented in the schema itself, including the env-var and Authorization header fallbacks. The description's 'for the provided API key' adds no semantics beyond that, so the baseline 3 applies.

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 ('Return') and resource ('the authenticated TelcoData account profile') with clear scope limited to the caller's own account. This is unmistakably distinct from the sibling set, which are all geocode/lookup/list tools operating on external 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?

Gives an explicit when-to-use scenario: confirm entitlement, API access, expiration, and identity 'before explaining why a query or download may be unavailable.' That is a concrete diagnostic trigger. It stops short of naming alternatives or when-not-to-use, but no sibling overlaps this function.

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 no annotations, the description carries the full burden; it discloses the categories of data returned (carrier type, country, FRN/RMD, Canadian registration/contact), which is more than the name. However, it says nothing about behavior for an unknown OCN, error modes, rate limits, or that the call is a read-only lookup with no side effects.

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-loaded with the action and resource, then the usage cues. No filler or 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?

No output schema exists, and the description compensates reasonably by enumerating the field families returned. For a single-key lookup with fully described parameters this is nearly complete; only error/empty-result behavior and auth expectations for api_key are unaddressed.

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 only repeats the 4-character OCN format already documented in the schema. It adds no new syntax, casing, or api_key guidance beyond what the parameter descriptions provide.

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 ('Fetch carrier profile details for a 4-character OCN') and implicitly scopes it to a single-carrier lookup, which distinguishes it from search_carrier_profiles_by_frn and search_carrier_profiles_by_rmd_id. An agent can tell what this returns without opening the schema.

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 triggering conditions ('user asks who an OCN belongs to', 'wants carrier type/country', 'needs FCC FRN/RMD or Canadian registration fields'), which is clear usage context. It does not explicitly name the sibling search tools as alternatives or state when not to use it.

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 no annotations, the description carries the full burden, and it does disclose useful data semantics: officetype holds raw space-separated NECA Tariff 4 office-capability codes and is explicitly not the equipment model in switchtype — a real footgun an agent would otherwise hit. It omits behavior on invalid/not-found CLLI codes and any rate-limit or permission notes, which keeps it from a 5.

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 purpose before the usage triggers and the alternative routing. The officetype/switchtype sentence is long but earns its place as the only disambiguation of a confusing field; nothing here is 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?

No output schema and no annotations, so the description must carry the load, and it does provide the key return-field caveat plus boundary conditions against get_exchange. It stops short of describing the broader response shape or failure modes, but for a single-record lookup it is close to sufficient.

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 both clli and api_key are already documented, and the description's contribution is only restating the 11-character CLLI requirement. The detailed field explanation (officetype vs switchtype) concerns the response, not the inputs. Baseline 3 is correct.

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 ("Fetch") and precise resource ("central-office/switch detail") scoped to exactly one 11-character CLLI code. The scope is narrow enough that an agent can distinguish it from sibling lookups like get_exchange or get_ocn_profile without reading either schema.

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 enumerates the trigger conditions (switch, wire center, location, equipment/switch type, LATA, tandem, point code, English name) and then redirects to a named alternative: "For prefixes served by a switch, start with get_exchange or related prefix-listing tools." Both when-to-use and when-to-go-elsewhere are covered.

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 no annotations, the description carries the full burden and does well: it warns that include_blocks can return many more rows (a volume/cost signal) and explains result semantics, e.g. thousands=-1 is the whole-prefix aggregate while 0-9 are individual pooling blocks. It omits auth prerequisites and pagination behavior, though the api_key parameter covers auth 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?

Purpose leads the description, followed by usage triggers, the risky flag, and field/value interpretation — each sentence adds information. The field inventory sentence is somewhat long but earns its place by telling the agent what comes back without an output schema.

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 three-parameter read tool with no annotations and no output schema, the definition is essentially self-sufficient: it covers purpose, trigger conditions, the expansion flag, and the field/value shape of the response. Only auth flow and row-count expectations are left thin.

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 genuine meaning by explaining when include_blocks should be flipped and how to interpret the thousands values in results. It does not restate or clarify the npa pattern beyond what the schema already documents.

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 states a specific verb and resource: list all exchanges/prefixes within a given NANP area code. It is clearly narrower than sibling get_exchange (single prefix) or lookup_tn, but it never names an alternative tool, so differentiation is inferred rather than stated.

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?

It gives concrete triggering scenarios (area-code inventory, coverage, 'what prefixes exist in 425') and an explicit rule for the one optional flag: only set include_blocks=true for thousand-block/pooling detail. It lacks explicit routing to the many list_* siblings, but the when-to-use and when-to-expand guidance 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?

No annotations are provided, so the description bears the full behavioral burden. It discloses that results are scoped to the authenticated user and include entitlement/access flags, but it does not explicitly state that the operation is read-only, nor does it mention pagination, rate limits, or error behavior.

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-loaded with the core purpose and followed by a concise usage scenario. Every sentence earns its place 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?

For a simple list tool with one optional parameter and no output schema, the description covers purpose, usage context, and returned data (entitlement flags). It lacks details on pagination or explicit read-only safety, which are minor given the tool's simplicity.

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% for the single optional api_key parameter, so the schema already explains its usage. The description adds no parameter-specific meaning, which is the baseline expectation when schema coverage is high.

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 states a specific verb and resource: 'List paid downloadable TelcoData datasets visible to the authenticated user, including entitlement/access flags.' This clearly distinguishes it from most siblings (geocoding, lookups, searches), though it does not explicitly differentiate from the closely related get_download_metadata sibling.

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?

It gives a clear usage context: 'Use when the user asks what bulk data files, CSVs, database dumps, or paid downloads their account can access.' However, it does not mention when not to use it or name an alternative (e.g., get_download_metadata for details on a specific download).

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 no annotations, the description carries the full burden and does add substantive context: LATA boundary behavior, the typical TelcoData fields returned, and the meaning of a thousands value of -1 versus 0-9. It does not discuss result-set limits, pagination, or error behavior, but for a read-only listing tool the domain disclosure is meaningful.

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 usage are front-loaded in the first two sentences, and the remaining context on LATA semantics and field meanings earns its place. The dense field enumeration is the only mildly verbose element, but it is informative rather than redundant.

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?

There is no output schema, so the description correctly compensates by enumerating common TelcoData fields and explaining the thousands aggregate convention. An agent has enough to invoke the tool and interpret the returned records, though pagination or result-size behavior is not covered.

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 schema itself documents the lata pattern (3-4 digits) and API key fallback behavior. The description adds no input-parameter detail beyond that—its thousands discussion concerns returned data, not the request—so the baseline 3 applies.

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 gives a specific verb and resource ('List prefixes in a LATA') and immediately disambiguates the domain concept, noting LATAs do not match states, cities, or area codes. An agent can distinguish this from list_state_area_codes or list_area_code_exchanges without opening the schema.

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?

It states the use case explicitly ('Use for regional telecom market/routing questions such as all prefixes in a LATA') and implicitly routes agents away from state/area-code tools via the LATA caveat. It does not name the closest alternatives like list_ocn_prefixes or list_tandem_prefixes, so there are no explicit exclusions.

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 no annotations, the description carries the behavioral burden and does well: it discloses the default date range, the effect of omitting dates, and the important semantic caveat that results are exchange-level additions rather than live assignment events. It does not discuss pagination, rate limits, or authentication behavior beyond what the schema already states.

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 concise sentences with the core purpose, usage contexts, date default, and output semantics front-loaded. Every sentence adds useful information 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?

The description covers purpose, usage contexts, default date behavior, and the key distinction from live assignment events. For a read-only list tool with 100% schema coverage and no output schema, this is nearly complete, though it could explicitly state the return format or pagination behavior.

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 parameter meanings are already documented in the schema. The description adds useful default behavior for date omission and mentions state-filtered monitoring, but does not add format or syntax details beyond the schema's YYYY-MM-DD note.

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 states a specific verb and resource ('List newly assigned TelcoData exchanges') with date-range scope, and explicitly distinguishes the output from live telephone-number assignment events. This lets an agent separate it from siblings like lookup_tn or search_record_history 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?

It gives clear usage contexts: recent numbering activity, new prefix reports, and state-filtered change monitoring. It also explains the default 30-day window and when to pass explicit dates, though it does not name a specific alternative sibling tool for overlapping queries.

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?

No annotations are supplied, so the description carries the full burden, and it delivers real behavioral content beyond the signature: the returned TelcoData field set and, importantly, the encoding rule that thousands=-1 means the whole prefix/default aggregate while 0-9 are individual pooling blocks. It omits pagination, result caps, and rate-limit behavior, which matter for a potentially large prefix dump.

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, then usage triggers, then data-shape notes — the right order. The field enumeration ('npa, exchange/NXX, thousands, state, ...') is a long clause, but it substitutes for a missing output schema, so it mostly 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?

With no output schema, the description fills the gap by naming the returned fields and explaining the thousands encoding, and it points at get_ocn_profile for identity fields. It leaves volume, pagination, and empty-result behavior unspecified, which is the remaining gap for a listing 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?

Schema coverage is 100% — both ocn (with its 4-character pattern) and api_key are fully documented in the schema. The description adds no format or resolution guidance for ocn (e.g., how to obtain one) and its field/thousands detail describes output rather than inputs, so the baseline 3 applies.

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 — 'List NPA-NXX prefixes assigned to an Operating Company Number (OCN)' — with explicit scoping that separates it from the LATA- and tandem-scoped siblings (list_lata_prefixes, list_tandem_prefixes). An agent can tell which prefix listing to pick from the description alone.

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 trigger scenarios ('where a carrier operates', 'what prefixes belong to a carrier', 'pivot from an OCN profile into numbering footprint') and names the companion call get_ocn_profile. It stops short of exclusions — it never says to use list_lata_prefixes or list_tandem_prefixes when the user is starting from a LATA or switch instead.

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?

No annotations are provided, so the description must carry behavioral disclosure; the verb "List" implies a read-only, non-destructive operation, which is useful. However it says nothing about result scope (all NPAs for the state?), ordering, pagination, or what happens when the input has no matching area codes.

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 tight sentences, zero filler, and the core purpose is front-loaded before the usage hint. Every clause 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?

For a simple two-parameter, non-destructive lookup, the definition covers purpose, input semantics, and usage context adequately. A brief hint about the returned data (a flat list of NPAs) would round it out in the absence of an output 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 description coverage is 100%, so both parameters are already documented, and the baseline is 3. The description adds only a little semantic framing (state/province/country/territory inputs) beyond the schema's own wording, without format or edge-case detail.

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 plus resource ("List NANP area codes") and scopes the input to a state, province, or NANP country/territory code. It indirectly distinguishes itself from richer siblings by positioning itself as geography-to-NPA mapping, though it never names the siblings it differs from.

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?

"Use for quick geography-to-NPA mapping before deeper area-code or rate-center queries" gives clear situational context and implies the ordering relative to rate-center/area-code tools. It stops short of explicit when-not-to-use exclusions or naming the alternative 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?

With no annotations, the description carries the behavioral burden. It discloses that broader CLLI prefixes can return more rows and explains the thousands aggregate semantics, but it does not cover pagination, row limits, or other operational 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?

The description is front-loaded with the core operation, followed by usage context, input behavior, return fields, and field semantics. Each sentence contributes useful information, especially because there is no output schema.

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 list tool with no output schema and no annotations, the description supplies meaningful return-field context and explains the thousands aggregation. It is nearly complete, though it omits pagination or row-limit expectations.

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 already 100%, so the baseline is 3. The description still adds useful meaning by explaining that the input can be a 6- to 11-character CLLI prefix and that broader prefixes increase the row count.

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 begins with a specific verb and resource: 'List prefixes routed via a tandem switch CLLI.' It clearly distinguishes this tool from prefix-oriented siblings like list_lata_prefixes and list_ocn_prefixes by tying the result set to a tandem CLLI.

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?

It gives clear usage context: routing/interconnection questions or when the user has a tandem CLLI and wants all served prefixes. It does not explicitly name when not to use it or point to the closest sibling alternatives, so it stops short of full routing guidance.

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?

No annotations are provided, so the description carries the full burden; "look up" implies a read-only, non-destructive call but that is never stated. It also says nothing about match behavior (exact 3-letter match only?), empty-result handling, or that an API key may be required — the auth hint exists only 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?

Two tight sentences: the first names the operation and key, the second gives the usage trigger. Nothing is redundant and the operation is 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?

For a single-required-parameter lookup with a fully described schema and no output schema, the description covers what the call does and roughly what it returns (CICs or carrier names). Only the exact result shape and any no-match behavior are unaddressed, which is a minor gap at this 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?

Schema coverage is 100%, so both the acna pattern and the api_key fallback are already documented. The description reinforces that acna is a carrier abbreviation tied to CIC/carrier-name results but adds no format or matching detail beyond the schema, so the baseline 3 applies.

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 (look up) and resource (CIC rows) and clarifies the lookup direction via the 3-letter ACNA key. It implicitly distinguishes itself from the sibling lookup_cic by making ACNA the input, but never names that sibling, so the differentiation is left for the agent to infer.

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?

"Use when the user has an ACNA and wants associated carrier identification codes or carrier names" gives a clear triggering condition and expected payoff. There are no explicit exclusions or pointer to the inverse tool (lookup_cic) for when the agent starts from a CIC instead.

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?

No annotations are provided, so the description carries the burden. 'Look up' strongly implies a read-only, side-effect-free record fetch, so the mutation question resolves by inference rather than statement. Missing are behaviors an agent would want: what happens if the CIC is unmatched, and whether the optional api_key affects access — though the schema's api_key description partly covers the auth path.

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 padding, with the identity of the tool front-loaded before the usage clause. Nothing could be removed without losing 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?

There is no output schema, so the description should convey what a CIC record contains; it only gestures at 'carrier/ACNA data'. For a simple single-key lookup that is close to enough, but the returned fields and any not-found behavior remain unstated.

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%, including the 4-digit pattern and the API-key fallback, so the baseline is 3. The description adds the acronym expansion (CIC/PIC) and the carrier/ACNA meaning of the returned data, but no extra syntax or value guidance 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?

States a specific verb and resource ('Look up a 4-digit Carrier Identification Code (CIC/PIC) record') and disambiguates the acronym. Sibling differentiation is only implicit — lookup_acna is never named, though the mention of mapping to ACNA data hints at the relationship.

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 second sentence gives concrete use cases (long-distance carrier selection, 1010 dialing, CIC-to-carrier/ACNA mapping), which is better than nothing. But there are no exclusions and no explicit statement of when to pick this over lookup_acna or lookup_ocn_profile, which is exactly the ambiguity an agent faces here.

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?

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses that NANP lookups return the most specific exchange/thousands-block record, whether block detail or fallback was used, the common field set, and the meaning of thousands=-1 vs 0-9. It omits any permission, rate-limit, or error behavior, keeping it below a 5.

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 and usage cue, then layers output detail. It runs several sentences but each carries distinct information (NANP behavior, field list, thousands semantics), so little is wasted.

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 no output schema, the description must supply return-value context, and it does: field list, specificity behavior, fallback indicator, and thousands interpretation. Auth is handled by the api_key parameter, so nothing essential for correct invocation 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% with both parameters documented, so the baseline is 3. The description adds only implicit meaning for the tn format (dialable number), re-stating rather than extending the schema's own text.

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 (normalize to E.164) and resource (dialable phone number) plus a secondary function (country metadata). Very clear what it does, though it never names a sibling tool to contrast against, so it falls short of full sibling differentiation.

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?

'Prefer this whenever the user gives a full phone number' gives clear when-to-use context. However, no when-not-to-use guidance or named alternatives (e.g. get_exchange, get_exchange_thousands) are given, leaving the boundaries 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?

No annotations are present to provide technical behavior (e.g., rate limits, safety). The description remains focused on the tool's conceptual purpose and data grouping rather than technical behavioral traits, making a middle score appropriate.

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 definition is highly concise. The first sentence establishes the action, and the second sentence adds essential business value and context, maximizing information density without verbosity.

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?

The description is highly complete regarding *what* the tool does and *why* it is useful. While it does not specify low-level execution details like pagination or return structure, it provides all necessary information for the agent to select the correct tool based on the problem scope.

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 high. The description enhances this by providing semantic value—explaining that the FRN acts as a 'common FCC registration' anchor for multiple related records like OCNs and RMDs.

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 defines the function (List carrier profiles) and the primary input resource (FCC Registration Number/FRN). This is specific and avoids ambiguity, especially when compared to other search 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?

It provides clear usage intent: 'Use to group related OCNs, carrier names, and RMD records under a common FCC registration.' This tells the agent precisely what business problem this tool solves, guiding its selection effectively.

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?

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a non-mutating read, but the description says nothing about result size, pagination, ordering, or what fields a carrier profile contains, leaving real gaps for an agent planning a call.

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 filler, with the resource definition front-loaded and the investigative purpose following. Every clause 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?

For a simple read-only two-parameter lookup with full schema coverage and auth already documented, the description is sufficient to call it correctly. It stops short of describing the returned profile fields, which an agent would need to know for downstream reasoning.

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 rmd_id documented as 'FCC RMD filing identifier' and api_key explaining its fallback sources, so the baseline is 3. The description adds the semantic link between the ID and OCNs/brands but no format or matching-behavior detail 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 gives a specific verb and resource ('List carrier profiles') plus the exact scoping key ('sharing an FCC Robocall Mitigation Database filing ID'), and the second sentence explains what the linkage means in practice. It does not explicitly name the sibling search_carrier_profiles_by_frn as the alternate lookup key, so the sibling differentiation is only implicit.

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?

'Use to connect multiple OCNs or brands to the same RMD filing/contact when investigating carrier identity, voice providers, or robocall-mitigation relationships' gives clear investigative contexts. There are no stated exclusions or pointers to alternative tools for other lookup keys, which keeps it below a 5.

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 no annotations, the description carries the behavioral burden and does well: it lists common TelcoData return fields and explains the thousands value semantics, including -1 as default aggregate and 0-9 as pooling blocks. It does not cover auth behavior, pagination, or error conditions, so it is not fully complete.

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 front-loaded with purpose and examples, then adds only relevant caveats and return-field context. Sentences are dense but each contributes useful selection or interpretation 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?

Because there is no output schema, the description appropriately compensates by naming common returned fields and explaining thousands semantics. It covers enough for correct invocation, though pagination and response shape are not 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?

Schema coverage is 100%, so the schema already documents all four parameters. The description still adds useful meaning by clarifying that rate-center names are telecom labels rather than necessarily postal cities and by emphasizing include_blocks=true for pooling detail.

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 states a specific verb/resource pair: search exchanges/prefixes for a rate center, scoped by state/province/NANP country code. It also distinguishes telecom rate-center geography from postal-city geography and gives concrete examples, which helps separate it from geocode-style 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?

It clearly states when to use the tool, including example local-service geography questions, and notes that rate-center names may differ from postal city names. It does not explicitly name sibling alternatives or when-not-to-use cases, so it falls short of full routing guidance.

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 no annotations, the description must carry the burden, and it discloses substantive behavior: reverse chronological ordering, that omitting all filters returns most recent changes, that baseline-load events are excluded, and crucially that multi-field changes are returned as one structured old/new JSON entry rather than fragmented per-field results. It omits auth/rate-limit/pagination behavior, which keeps it from a 5.

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 the purpose, then the use case, then result semantics, then parameter notes — a sensible order. Slightly dense with some overlap between the description and the clli/field schema entries, but every sentence carries 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?

For a 9-parameter, zero-annotation, no-output-schema tool this covers the essentials: what changes are tracked, how results are shaped (paired old/new JSON), ordering, and no-filter behavior. Pagination beyond the limit parameter and the api_key handling are left to the schema, which is a minor gap rather than a blocking one.

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. The description does add real semantics beyond the schema for clli (6- to 11-character CLLI or prefix matching switch-related changes) and clarifies that source is a tracked source name, not an archive filename — useful, but the remaining parameters are left entirely to 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 ('Search TelcoData's tracked source-record changes') plus ordering (reverse chronological), which no sibling tool does — the siblings are point lookups (lookup_tn, get_exchange, get_switch) rather than change history. An agent can distinguish this from every other tool in the list without opening a schema.

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 itself: 'Use this for questions about when an NPA-NXX or thousands block changed carrier, OCN, CLLI/switch, assignment status, rate center...' and explains the no-filter fallback. It stops short of naming an alternative tool or stating when not to use it, but the context is clear enough to select it confidently.

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