telecom-truth

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

With no annotations provided, the description must bear the burden of behavioral disclosure. It does add valuable context by promising 'honest numbers with their grain and vintage stated,' indicating the tool reports data quality and timeliness. Still, it does not describe return format, potential error cases, or any caveats about data availability, leaving some ambiguity for a read-oriented tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the core purpose and efficiently lists what the user gets. It's slightly dense with clauses and dashes, but every element earns its place—there is no filler or repetition.

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 read tool with no output schema, the description covers the key inputs and clearly enumerates expected outputs (provider count, fiber share, dominant technologies) plus a notable data-quality guarantee. It doesn't specify output formatting, but the response is adequate for an agent to determine whether this tool fits the need.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema fully documents both parameters with examples, and the description reinforces 'city' and 'two-letter state' without adding new semantic detail. Since schema coverage is 100%, the description provides no additional parameter meaning beyond what the schema already states, matching the baseline for high coverage.

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 identifies the tool's subject (coverage intelligence for a US city) and lists concrete outputs: number of providers filing service, fiber availability share, and dominant technologies. It distinguishes itself from sibling tools like check_availability by focusing on city-level aggregate intelligence rather than address-specific checks, though it doesn't explicitly name an alternative.

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 implies when to use this tool—when you need city-level coverage statistics—and gives input instructions ('Give city and two-letter state'). However, it provides no explicit guidance on when to prefer this over siblings like industry_overview or provider_profile, and it does not mention any exclusions or prerequisites beyond the required parameters.

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 full behavioral disclosure. It explains the data source (FCC BDC filings cross-verified against a 200M-address ledger), output ordering (fiber options first), and additional output details (filing vintage and live page link). This goes beyond a simple generic description, though it does not cover edge cases like no providers found or error handling.

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 that are dense with information: purpose, input methods, output contents, and data provenance. No fluff or redundancy, front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description details the return values (providers, technology, speeds, filing vintage, link) and data source. It is complete for typical use, though it lacks information about potential failure modes or what an empty result looks like.

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 parameters. The description reiterates the alternative relationship (address, lat/lng, location_id) and mentions 'from a previous call' for location_id, but does not add substantive meaning beyond the schema. 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 states a specific verb and resource: 'Authoritative internet availability for one US location' with clear intent to return providers, technology, and speeds. It distinguishes from siblings by emphasizing 'one US location' rather than broader geographic or industry views.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context by listing three ways to specify a location (address, lat/lng, or FCC location_id) and what to expect. Does not explicitly mention alternatives or exclusions relative to sibling tools, but the scope of 'one US location' implicitly guides selection.

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 transparency burden. It discloses the content returned (providers, locations, tech mix, vintages) but does not mention behavioral details such as data update frequency, aggregation methodology, or any limitations. For a read-only overview, this is adequate but not exhaustive.

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 most important information ('US telecom market at national scale') followed by specific data elements. Every phrase earns its place, making it concise without losing specificity.

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 low complexity (no parameters, no output schema), the description is complete. It enumerates the return contents (total providers, locations, technology mix, filing vintages) and provides usage context, covering what an agent needs to know to invoke 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?

The tool has zero parameters, so the baseline is 4. The description adds meaning about the output rather than parameters, which is appropriate given the empty schema. It enriches understanding of what the tool returns.

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 explicitly states the tool provides a national-scale US telecom market overview with specific data points (providers, FCC-registered locations, technology mix, filing vintages). It differentiates itself from sibling tools by positioning as 'the market-context tool' for national broadband questions, not local or provider-specific queries.

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 clearly indicates when to use the tool: for questions about the US broadband industry, the fiber transition, or market size. It implies national scope vs sibling tools (e.g., area_intelligence), though it does not explicitly name 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 burden of behavioral disclosure. It implies a read-only intelligence lookup and specifies US-only coverage and hex granularity, but it does not disclose response format, error cases, or any other operational constraints. The description does not contradict any annotations because none are provided.

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 compact and front-loaded: the first sentence lists concrete outputs and scope, the second explains the use case and input alternatives. Every sentence earns its place with no redundant 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?

There is no output schema, so the description needs to communicate what the tool returns. It lists the main output categories effectively, but it does not specify exact response formatting or units beyond hex size. Still, for a lookup tool with simple inputs, this is reasonably 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?

The schema covers 100% of parameters but only with terse labels like 'Latitude' and 'Longitude.' The description adds meaningful semantics by stating 'Give lat+lng, or an H3 res-8 hex_id directly,' clarifying that lat/lng are used together and that hex_id is an alternative. It also adds res-8 and ~0.46 km context, going 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 identifies the tool as providing Res-8 hex intelligence for US coordinates and lists specific outputs (FCC locations, providers, fiber density, competition, underserved status, speeds). This is specific and distinguishes it from sibling tools like area_intelligence or provider_profile by focusing on neighborhood-level herd-mentality context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states the tool is the 'herd-mentality context' and 'build-predictability grain,' giving a clear sense of when to use it. However, it does not explicitly mention when not to use it or name alternatives, so it falls just short of full 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 provided, the description carries the burden. It discloses the tool's normalization behavior ('handles brand variants') and enumerates the return fields. It does not mention error handling or missing-provider behavior, but for a simple profile lookup it offers sufficient transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is two sentences, front-loaded with the tool's core purpose, and each sentence adds value. No fluff or repetition.

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?

Tool has one required parameter, no output schema, no annotations. Description covers purpose, return content, and usage context. For a single-parameter lookup tool, this is fully sufficient for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'name' is described in schema. The description adds meaning by explaining that brand variants are handled and giving examples ('ATT', 'Google Fiber'), which helps the agent know acceptable inputs beyond the schema's generic phrasing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it returns a canonical profile of a US internet provider by name, listing specific outputs (identity, FCC registration numbers, technologies filed, profile URL). It distinguishes from siblings by emphasizing disambiguation of providers before claims.

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 it to disambiguate providers before making claims about them,' giving clear context for when to use. Does not mention when not to use or alternatives, but the sibling tools are syntactically distinct (area, availability, industry, location) so the usage context is implied.

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