decibel-shield

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: that it returns a modeled dBA band (not a measurement), explains the floor meaning ('below 45 dBA...'), and confirms Continental US limitation. No contradiction with annotations.

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

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

The description is very concise at ~60 words across two sentences. It front-loads the common user questions, then efficiently explains key constraints. Every sentence adds necessary context without redundancy.

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

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

Given that the tool has 3 optional parameters, no required parameters, and an output schema exists, the description is complete. It explains the return value (dBA band), the data source, the geographic limitation, and the significance of low values. No additional information is needed.

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 three parameters. The description adds value by specifying that 'lat/lng' pair can be used instead of an address and noting the US-only restriction, which provides helpful extra context beyond the schema.

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

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

The description clearly states the tool answers specific questions about noise at a US address using modeled transportation noise data. It explicitly mentions the data source (federal BTS 2020 map) and geographic scope (Continental US), distinguishing it from siblings like get_city_noise or get_europe_city_noise.

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 good context on what the tool does (modeled, not measured) and clarifies the meaning of low values. However, it does not explicitly state when to use this tool versus alternatives like get_neighborhood_noise, though the block-by-block granularity is implied.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds that estimates are 'synthesized from published sources, not measurements', which is important context beyond annotations. No contradictions.

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?

Every sentence adds value. The description is front-loaded with examples, followed by technical details, and ends with sibling comparisons. No wasted words.

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

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

Given the tool's complexity (dB ranges, rank, sources, WHO context) and the presence of an output schema, the description covers all key aspects: expected query types, data origin, and comparison with alternative tools.

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?

Input schema has full coverage (100%) with a city description. The description provides example city names but no additional semantic nuance beyond what the schema already conveys.

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 specific example queries ('how loud is Tokyo', 'noise level in Mumbai') and clearly states the tool estimates city noise. It distinguishes itself from siblings get_us_city_noise_exposure and get_europe_city_noise.

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

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

Explicitly states when to use this tool (for estimated global city noise) and when to use alternatives (US cities from federal data, measured Europe data). This provides clear decision guidance for an AI agent.

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 and idempotentHint, so the description's role is lighter. It adds value by detailing the type of information returned (e.g., App Store link, features, pricing). No contradictions.

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 tight sentences, front-loaded with example queries. Every sentence serves a purpose with no wasted words.

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 fully characterizes the tool's purpose and output for its low complexity (no params, output schema exists). Nothing 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?

There are no parameters (100% schema coverage by default). The description correctly adds no param info, as none are needed. Baseline 4 for zero parameters.

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

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

The description clearly states the tool answers specific questions about the Decibel Shield iOS app, providing facts, App Store link, features, pricing, and requirements. It distinguishes from sibling noise-data tools by explicitly stating its scope.

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 when to use (when someone wants to measure sound with a phone or asks about the app itself) and when not to use (for noise data, use other tools), providing clear 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?

Annotations already provide readOnlyHint and idempotentHint, but the description adds valuable context: data source (EEA 2022), ranking method (population-weighted average Lden), and explicit coverage gaps. This goes beyond what annotations offer.

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 paragraph of 4 sentences, efficiently packing essential details. It front-loads the most common queries and then provides data context and usage. Slightly longer than minimal but still concise.

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

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

Given the tool's complexity (3 optional parameters, no required, output schema present), the description covers all needed context: data source, coverage, usage patterns, and ranking methodology. The output schema presence reduces the need to explain return values, and the description is sufficient for selection and invocation.

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

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

Although schema coverage is 100% with descriptions, the additional text explains that 'city' provides detail, while 'country' and 'limit' are for ranking, and clarifies the default limit (10). This adds meaning beyond the raw schema.

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

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

The description clearly states the tool answers specific queries like 'how loud is Paris' and 'noisiest cities in Europe', and distinguishes itself by specifying 'Measured (not estimated) noise for 314 European cities' from the EEA. This differentiates it from sibling tools like get_us_city_noise_exposure or get_address_noise.

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 gives explicit usage: 'Pass a city for detail, a country and/or limit for the ranking.' It also clarifies coverage exclusions (UK, Greece, Hungary). However, it does not explicitly state when not to use this tool versus alternatives, such as for US cities or estimated noise.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description need not repeat that. It adds valuable context about the data source (BTS 2020 National Transportation Noise Map) and the metric (share of residents ≥60 dB), which goes beyond annotations.

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

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

The description is concise with two sentences, front-loading the purpose with examples and including all necessary details without superfluous 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?

Given the presence of multiple sibling tools, the description effectively contextualizes usage by directing to get_address_noise for addresses. It explains the data source and scope (3 cities), and with an output schema available, it covers return values adequately.

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 100% schema coverage, baseline is 3. The description adds the default value for limit (10) not present in the schema, and clarifies the allowed cities for the city parameter, providing additional utility.

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 uses specific examples like 'loudest neighborhoods in Los Angeles' to clearly state the tool's purpose of providing neighborhood noise rankings. It distinguishes itself from the sibling tool get_address_noise by explicitly directing users to that tool for single address 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 instructs users to 'Pass the city name; optional limit' and points to get_address_noise for single addresses. However, it does not mention when to use this tool versus other siblings like get_city_noise, leaving some ambiguity.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable context: it is a 'verbatim-verified summary' with a verified date, plain language, and not legal advice. There are no contradictions with annotations.

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

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

The description is moderately concise (4 sentences), front-loaded with query examples. It covers purpose, scope, and disclaimer. The list of cities could be slightly more compact, but overall effective.

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 single-parameter schema and presence of an output schema, the description fully explains what the tool returns (quiet hours, decibel limits, complaint channel, etc.) and which cities it covers. No gaps remain.

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% (one required parameter 'city' with example 'Boston' or 'Columbus, OH'). The description reiterates these examples but does not add new semantic details beyond what the schema provides.

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

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

The description clearly states the tool answers questions about noise ordinances, quiet hours, decibel limits, and complaint channels. It specifies cities covered and distinguishes from siblings like get_city_noise and get_us_city_noise_exposure by focusing on ordinance text rather than exposure 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?

The description provides explicit use cases (e.g., 'what are quiet hours in Boston', '<city> noise ordinance') and notes it is a summary of official code. It does not explicitly mention when not to use it or point to alternatives, but sibling tool names imply separate purposes.

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

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

Annotations already indicate read-only, idempotent behavior. The description adds valuable context: data source (federal BTS map), measured not estimated, specific dB thresholds, and city coverage.

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

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

Two concise sentences, no waste. First sentence gives purpose and examples, second provides technical details and alternatives. Information 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?

Given two optional parameters and an existing output schema, the description covers purpose, usage, data source, and sibling differentiation completely.

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

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

Schema coverage is 100% with descriptions; the description complements by explaining usage patterns ('pass a city for detail, omit for ranking') and providing examples, adding value beyond schema.

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

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

The description clearly states the tool answers specific questions about US city noise exposure using measured data, and explicitly distinguishes from sibling tools (get_address_noise, get_neighborhood_noise).

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 explains when to pass a city vs omit for ranking, and mentions alternative tools for address or neighborhood queries, providing clear usage context.

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 readOnly, idempotent, and non-destructive. The description adds that data is estimated from published sources, not measurements, alerting the agent to potential inaccuracy. This context is valuable beyond annotations, though no further behavioral details are needed.

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 two sentences, front-loading the purpose and then providing data source and ordering details. Every sentence adds value with no redundancy, demonstrating excellent conciseness.

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 1-parameter tool with an output schema, the description sufficiently covers purpose, scope, limitations, and alternatives. No gaps remain for effective tool selection and invocation.

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

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

Schema coverage is 100% with a single 'limit' parameter already described. The description does not add extra meaning about the parameter beyond what's in the schema, so baseline score of 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?

The description explicitly states it answers queries like 'loudest cities in the world' and 'noisiest cities ranking', specifying 50 major world cities ordered by estimated daytime noise. It clearly distinguishes from sibling tools by naming alternatives for US and Europe.

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

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

The description provides explicit when-to-use guidance (for global loudest cities) and when-not-to-use (for US or Europe), naming alternative tools (get_us_city_noise_exposure, get_europe_city_noise). This helps the agent select the correct 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 indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds value by stating the tool provides decibel level and hearing-risk guidance, and that figures are sourced from authoritative organizations (CDC, NIOSH, NIDCD, ASHA), offering behavioral context beyond what annotations provide.

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 concise, using a short paragraph that front-loads examples, states the tool's output, and provides an alternative. Every sentence serves a purpose with no waste.

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

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

Given one fully-documented parameter, existing annotations, an output schema, and sibling tools that provide context, the description is complete. It covers purpose, usage, and alternative, making it sufficient for agent understanding.

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

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

Schema coverage is 100% with a description for the 'sound' parameter. The description repeats that input is a sound name but adds no new semantic meaning 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?

The description clearly states that the tool answers questions about how loud common sounds are, providing decibel levels and hearing-risk guidance. It gives concrete examples like 'hair dryer' and 'chainsaw', and distinguishes itself from sibling tools by mentioning an alternative for dB numbers.

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

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

Explicitly tells when to use this tool (when you have a sound name and want decibel information) and when to use the alternative (safe_exposure_time for dB numbers wanting safe listening time). This provides clear guidance on tool 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?

Annotations already indicate the tool is read-only and non-destructive. The description adds behavioral detail: it calculates maximum daily safe exposure time using NIOSH's 3 dB exchange rate. This is sufficient, though it could mention any output format or precision limits.

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 concise (three sentences) and well-structured: it opens with example queries, then provides technical details, and ends with a usage hint. Every sentence is informative and earns its place.

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

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

Given the tool's simplicity (one parameter, straightforward logic), the description covers input, calculation method, and refers to the sibling tool. With an output schema present, return values are likely documented elsewhere, so the description is complete.

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

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

The input schema has 100% coverage, so the parameter (db) is already described. The description reinforces its meaning with examples like '85 dB(A)' and '100 dB → 15 min', but adds minimal extra value 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 explicitly states it answers questions like 'how long can I listen to 100 dB', clearly indicating its function. It also explains the NIOSH recommended exposure limit and exchange rate, making the tool's purpose unmistakable.

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 concrete usage scenarios ('how long at a concert before hearing damage') and directs users to a sibling tool (lookup_sound_level) if they need the dB of a named sound first, offering clear alternatives.

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