peerglass_country_chokepoints

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

Annotations declare readOnlyHint=true and destructiveHint=false, establishing the safety profile. The description adds valuable behavioral context beyond these booleans: it explains the scoring methodology (0–100 scale), defines catastrophic vulnerability thresholds (1–2 providers), and details the specific output components (transit providers by dependency, single-upstream count), helping the agent understand what constitutes a 'good' vs 'bad' result.

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 uses a structured docstring format (Args/Returns) with zero filler. The vulnerability explanation ('cutting those providers isolates the entire country') earns its place by contextualizing the tool's value proposition. Information is front-loaded with the core action in the first sentence, followed by parameter and return value specifications.

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 presence of an output schema (noted in context signals) and good annotations, the description appropriately focuses on domain-specific context rather than repeating structural metadata. It comprehensively covers the complex BGP/infrastructure domain by explaining what the resilience score measures, the risk model (upstream dependency), and the specific data returned, making it sufficient for an agent to use effectively.

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?

With 0% schema description coverage (the schema properties lack descriptions), the description fully compensates by documenting both parameters in the Args section: country_code includes the format standard (ISO 3166-1 alpha-2) and concrete examples ('SY', 'BY'), while response_format specifies the enum values ('markdown', 'json') and default behavior.

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 'Map[s] internet resilience for a country by identifying transit providers that many in-country ASNs depend on, and computing a resilience score.' This provides a specific verb (map/identify/compute), resource (transit providers/ASNs), and distinguishes from siblings like peerglass_country_health by focusing specifically on chokepoint analysis and dependency concentration rather than general health metrics.

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

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

The description provides clear contextual guidance by explaining that 'Countries with 1–2 dominant upstream providers are catastrophically vulnerable,' which signals when this tool is valuable (assessing isolation risk). However, it does not explicitly name sibling alternatives (e.g., 'use peerglass_country_health for general connectivity status instead') to guide selection against the 30+ related tools available.

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