Korzy

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds non-obvious behavior: pagination is stateful via a run_id carried from the first page, and each receipt must keep its month, supplier and units distinct. The caveat "links are not routes" warns against a plausible misinterpretation of the returned data.

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 short sentences, front-loaded with the purpose before the data-semantics caveat and then the pagination instruction. No filler, though "links are not routes" is cryptic enough that it may need one more clarifying clause to earn 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?

An output schema exists, so return-shape explanation is not required, and the description focuses on the parts an agent cannot infer: pagination continuity and receipt granularity. It stops short of saying whether the run_id must be reused with identical filters or how long it stays valid, which matters for a stateful paged read.

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 0%, so the description carries the burden and only partly delivers. It explains run_id's provenance (first page of a paged sequence) and implies mine_id is an MSHA mine identifier, but limit and offset get no mention and the run_id format or lifetime is never clarified.

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 names a specific verb and resource: "Get reported coal receipts linking an MSHA mine to power plants," which tells an agent exactly what data comes back. It does not explicitly contrast itself with any sibling, but none of the listed siblings overlaps with mine-to-plant shipment receipts, so ambiguity is low.

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 line "Pass run_id from the first page when requesting subsequent pages" is real usage guidance for pagination, which is valuable. However, there is no statement of when to choose this tool over alternatives or any exclusion (e.g., whether a power-plant-side view exists), so guidance remains 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 declare the tool as read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful behavior beyond that: footprint coordinates are omitted and only their count is returned, avoiding a false expectation about payload contents. It says nothing about behavior for missing or unknown project_id/run_id or about release pinning semantics beyond 'pin the source release'.

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 with no filler, front-loaded with what is returned before the caveat about footprint coordinates and the run_id hint. The middle clause about browser/API/export availability is slightly roundabout but serves the error-avoidance goal.

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 two-parameter read-only lookup with an output schema, the description covers what the tool produces and how to scope the release. Re-enumerating the output fields is mildly redundant given the output schema, and error behavior remains undocumented, but nothing essential for invoking it correctly is missing.

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

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

Schema description coverage is 0%, so the description must carry the burden for both parameters. It explains run_id's provenance and purpose (take it from search to pin the release) but leaves project_id entirely unelaborated — no format, no source, no relationship to the 'merged project' that is returned.

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 ("Get one merged project") and enumerates what the merged record contains: observations, capacity evidence, timeline, matching evidence and conflicts. It does not explicitly contrast itself with siblings like get_parcel or get_state_summary, so the boundary between them is left 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?

There is one concrete usage instruction: pass run_id from search to pin the source release, which is genuinely actionable. However, there is no guidance on when to choose this tool over the other single-resource lookups or list/search tools, and no mention of what to do when run_id is unknown.

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 read-only, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds genuinely useful behavioral context beyond that: brownfields are reported points rather than parcel boundaries, and results do not constitute a clearance determination. It does not quantify result volume or the effect of the limit parameter, but the key semantic caveats are disclosed.

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 short sentences, front-loaded with the action and scope, followed by two precise limitations. Every sentence earns its place; the only minor inefficiency is that the 10 km cap duplicates the schema maximum.

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

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

With an output schema present the description need not document return values, and annotations cover the safety profile, so the remaining burden is scope and limitations, which are handled well. The notable gap is run_id, whose purpose and relationship to a prior call are never explained.

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 0% across five parameters, so the description carries the burden and largely does not meet it. It explains radius_km as a proximity window but merely restates the 10 km maximum already encoded in the schema, and says nothing about limit, run_id, or the latitude/longitude pair beyond 'reference point'.

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?

Uses a specific verb ('Screen') with a specific resource ('mapped environmental layers') and states the spatial scope (reference point plus nearby cleanup locations within radius_km). It is distinguishable from siblings like get_parcel_terrain or get_site_context, though it never names an alternative directly.

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

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

Gives explicit negative guidance ('not full-parcel overlap, contamination or environmental clearance'), which tells the agent what this tool must not be used to conclude. However, it offers no positive when-to-use routing versus the many related context tools (get_site_context, get_parcel_terrain, get_regional_energy), leaving the agent to infer 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 cover read-only, idempotent, closed-world and non-destructive behavior, so the bar is lower. The description still adds genuine behavioral context the annotations cannot: distances are straight-line rather than routed, and results may include candidate_limited flags and per-layer errors, warning the agent about partial output.

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 scope statement comes first, followed by the layer-key prerequisite and then caveats, so the most important information is front-loaded. Sentences are terse and each carries content, though the fragment style ('Preserve candidate_limited flags and per-layer errors') is slightly clipped.

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

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

An output schema exists, so return structure need not be described, and the key caveats about straight-line distance and error flags are covered. However, for a 6-parameter tool with zero schema descriptions, leaving limit and run_id unexplained is a real gap an agent must guess around.

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 0% across 6 parameters, so the description carries the full burden. It clarifies radius_km's 25 km ceiling and that layer values come from the dataset catalog, but says nothing about limit, run_id, or the meaning of latitude/longitude ranges — run_id in particular is entirely opaque.

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?

"Find nearby transport/logistics features within radius_km" gives a specific verb and resource, and the domain (logistics) distinguishes it from siblings like get_environment_context or get_site_context. It never explicitly names a sibling or the boundary between them, so it stops short of full 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?

Usage is implied by the radius-based 'find nearby features' framing and by the pointer that layer keys live in the dataset catalog under logistics, which tells the agent how to prepare a call. But there is no statement of when to prefer this over get_site_context, get_environment_context, or get_parcel_terrain, and no 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?

Annotations already cover the read-only/idempotent safety profile, yet the description still adds substantive behavior: include_owner doubles cost, ownership fields are source information rather than proof of title, and restricted values plus redacted zoning are silently omitted from results. The cost implication and the omission behavior are exactly the kind of disclosure an agent cannot get from 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?

Short, front-loaded sentences with one idea each: purpose and inputs first, then cost, then data caveats. Nothing is repeated and no sentence 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?

For a 4-parameter read tool with an output schema, this covers input provenance, cost, and data-omission behavior. The one gap is failure behavior — it never says what happens if the supplied location does not fall on the parcel identified by korzy_id.

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 description carries the full burden and largely succeeds: it explains the provenance of korzy_id, that latitude/longitude must lie on the parcel and bound the lookup, and that include_owner adds ownership fields at double cost. It does not restate the coordinate ranges, which the schema already enforces.

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 a parcel's attributes") and names the key inputs, korzy_id plus a location on the parcel. It implicitly distinguishes itself from search_parcels by saying the id comes from a prior search, but it never names a sibling explicitly, so differentiation is inferential 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 a real prerequisite: both korzy_id and the coordinates must come from a parcel address search or point lookup, and it flags the include_owner cost tradeoff. However, there is no guidance on when to use this instead of get_parcel_terrain or search_parcels, and no when-not conditions.

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?

The annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful context: it may fetch elevation data and cache analysis inputs and results, and it explicitly frames output as screening-level. The caching remark sits slightly at odds with readOnlyHint, but as an internal cache it does not rise to a contradiction, and no limits, latency, or failure modes are described.

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 compact sentences, front-loaded with the action and followed by prerequisites and caveats; no filler. The phrasing is slightly clipped ('May fetch elevation data'), but nothing is 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?

With an output schema present, the description need not explain return values, and it instead spends its space on interpretation limits, which is the right call for a screening tool. The main gap is the unaddressed slope_threshold_percent, plus no mention of cost or timing for the elevation fetch.

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 0%, so the description carries the full burden. It only partially does so: it says korzy_id must be verified and that the point must lie on that parcel, which gives real meaning to three required params. The fourth parameter, slope_threshold_percent, is never mentioned, so the agent gets no guidance on what the threshold does or how the resulting classification is produced.

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 verb+resource ('Analyze terrain over the full parcel polygon') is specific and scoped, and the caveats make clear this is a screening-level terrain analysis. It never distinguishes itself from the nearby get_terrain_metadata or get_site_context siblings, so the agent must infer which one to call.

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 real precondition ('Use a verified korzy_id and point on that parcel') and warns what the results are not suitable for (grading/design, usable acreage, developable campus). What is missing is any routing to alternatives: it never says when to prefer get_terrain_metadata or get_site_context, or when a parcel-level terrain run is unnecessary.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds real context: the response contains multiple tables, pagination limits apply independently per table, and units/dimensions/periods must not be conflated. It does not mention volume expectations or failure modes, but the multi-table pagination caveat is genuinely useful information not available in 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?

Four short sentences, front-loaded with what is returned and followed by operational caveats; almost nothing is wasted. The telegraphic style ('Keep units, dimensions and periods separate') is terse but each sentence carries distinct information.

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

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

An output schema exists, so return values need not be spelled out, and the per-table pagination note covers a key operational concern. However, for a 5-parameter tool with zero schema descriptions, leaving `run_id` and `dataset` key semantics unexplained is a meaningful gap an agent would hit at call time.

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 0% across 5 parameters, so the description carries the full burden. It partly compensates by explaining that limit/offset apply per returned table and by pointing to a dataset catalog for `dataset` keys, but `run_id` is never mentioned and `plant_id` format/spelling is undocumented. Half the parameters remain opaque beyond their type names.

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?

Names a specific verb and resource (get plant-level observations) and enumerates the concrete datasets returned: generation/fuel observations, nuclear outages, monthly generator inventory, equipment details. It does not differentiate itself from siblings like get_power_plant or get_regional_energy, and the enumerated scope is broader than the name 'energy history' implies, which slightly muddies the purpose.

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 line about the dataset catalog implies the agent should consult list_datasets to pick dataset keys and coverage, which is an implied workflow rather than an explicit instruction. There is no statement of when to use this versus get_power_plant or get_regional_energy, and no prerequisites or exclusions are given.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine domain context that annotations cannot: nameplate MW is inventory, not available power or interconnection capacity. It still omits behavior on a missing/invalid plant_id and says nothing about ordering or page exhaustion.

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 short sentences, front-loaded with the primary action and immediately followed by the caveat that prevents the most likely misreading of the data. Nothing is padded, though the trailing sentence does not connect to any parameter or usage decision, leaving the definition feeling slightly clipped.

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

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

An output schema exists, so return-value documentation is not required, and the annotations cover the safety profile. However, for a three-parameter tool with zero schema description coverage, the description leaves both pagination parameters and the plant_id format undocumented, which is a meaningful gap for correct 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 description coverage is 0%, so the description must carry parameter meaning and largely does not. "Bounded page of generators" weakly signals that generator_limit/generator_offset are pagination controls, but there is no explanation of the plant_id format (a 1-12 digit numeric string) or of the 1-100 / 0-1000 bounds and defaults.

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 ("Get a power plant") plus the secondary return ("a bounded page of generators"), which separates it from siblings like get_plant_energy_history or get_regional_energy. It stops short of naming any sibling explicitly, so differentiation relies on the agent inferring from the resource noun.

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?

There is no when-to-use guidance and no exclusions; the description never says when to pick this over get_plant_energy_history, get_regional_energy, or get_transfer_capacity. Usage is only implied by the resource name, which is weak given how many plant-adjacent siblings exist.

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 the provided annotations (readOnlyHint=true), the description conveys key behavioral guarantees, specifically that 'units and dates' are preserved, which is a vital technical detail for consumers of the output data.

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 and front-loaded. It delivers the core function and crucial data limitations within two tight, efficient sentences without any fluff.

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 definition is adequate for describing *what* is retrieved (regional averages). However, because parameter usage relies on external lookups ('The dataset catalog lists region and dataset keys'), the definition remains incomplete regarding the practical operational steps for parameter selection.

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 a 0% schema description coverage, the definition defaults to a baseline score of 3. While the text clarifies the nature of the data being queried (regional averages vs. parcel-specific metrics), it adds no semantic meaning or guidance to the individual parameters themselves.

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 immediately and clearly states the purpose: to retrieve state prices, energy, emissions, or hourly grid demand and fuel mix. This is highly specific.

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 crucial usage context by stating that the results are regional averages. It explicitly cautions the user that this data is not equivalent to parcel utility prices or available grid capacity, effectively defining its operational scope against potential alternatives.

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 establish safe, idempotent, closed-world reads, and the description adds real value beyond them: distances are straight-line (so location precision must be inspected), 'no match means unknown' rather than a negative result, overlapping condos return separate records, and include_owner doubles the parcel cost. Cost and data-quality caveats like these are exactly what annotations cannot convey. It stops short of covering rate limits or pagination semantics.

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?

Dense and front-loaded, with the result footprint stated first, but the body degenerates into clipped fragments ('No match means unknown. Overlapping condos return separate records. parcel_offset stops at 1000.'). The 'parcel_offset stops at 1000' line duplicates the schema maximum rather than adding behavior, so not every sentence 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?

An output schema exists, so return-value explanation is not required, and the description covers the composite nature of the response (parcels, boundaries, plants, projects) with their limits. What remains thin is routing guidance versus siblings and the unmentioned parcel_limit, but for a five-parameter read tool with strong annotations this is close to 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?

Schema description coverage is 0%, so the description must carry the load; it explains include_owner (adds owner fields, doubles cost) and parcel_offset (stops at 1000), which is genuinely useful. But parcel_limit is never mentioned and the offset note largely restates the schema maximum. Two of five parameters get meaning added, leaving a real gap.

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?

Uses a specific verb ('Find') and enumerates exactly what is returned: exact parcel matches, mapped water/sewer boundary matches at a point, plus up to 3 treatment plants within 50 km and 5 data-center project points within 10 km. The point-lookup scope clearly separates it from siblings like get_parcel, search_parcels, and get_environment_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?

Usage is implied by the coordinate-based framing and the radius caps, so an agent can infer this is a single-point context sweep. However, it never states when to prefer this over search_parcels or get_parcel, nor any prerequisites or exclusions. The guidance is implicit only.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds one genuinely useful behavioral fact beyond that: an empty state yields compact nationwide counts, effectively defining the default/no-argument response. It says nothing about response size, ordering, or how counts relate to coverage gaps.

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 short sentences, front-loaded with the outcome and followed by input formats; no filler. The line break mid-sentence and the vague phrase 'field coverage' are the only slight costs to structure.

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 one-optional-parameter read tool with an output schema already defining return shape, the description covers purpose, accepted input formats, and the empty-input default — enough to invoke correctly. It omits any mention of what 'field coverage' is measured against, which leaves the summary's semantics slightly open.

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 0% and the single 'state' parameter has no description of its own, so the description carries the full burden — and it does: accepted forms are abbreviation, name, or FIPS, and the empty string is documented as a valid value producing nationwide results. Only minor gaps remain, such as whether names are case-sensitive or partial matches are allowed.

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?

Uses a specific verb and resource: 'Get exact parcel record counts and field coverage', which tells an agent this is a coverage/count summarization tool rather than a record fetch like get_parcel or search_parcels. It stops short of naming or contrasting any sibling, so differentiation is inferred from the phrasing 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?

There is no explicit when-to-use or when-not-to-use guidance relative to get_parcel, search_parcels, or list_datasets. The only usage signal is the implied 'call with empty state for nationwide counts', which is an input behavior rather than a routing rule.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by clarifying that the call triggers no terrain computation — something an agent could otherwise misread as an expensive operation — and it discloses that 'access state' is returned, hinting at permission gating.

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 short sentences, front-loaded with the returned content and followed by the one behavioral caveat that matters. Nothing is redundant or padded.

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

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

An output schema exists, so return-value explanation is unnecessary, and with zero parameters the surface is small. The description covers purpose, content and side-effect profile adequately, though 'access state' remains undefined and no guidance on acting on the metadata is given.

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 takes zero parameters, so there is no parameter semantics to explain; baseline is 4. The description correctly does not waste space describing inputs.

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 a specific verb ('Get') and names the exact payload: source resolution, units, coverage, limits and access state. It also implicitly separates itself from get_parcel_terrain by stating it 'does not initiate a terrain analysis', though it never names that sibling outright.

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 phrasing 'discovery tool' and 'does not initiate a terrain analysis' hints that this is a prerequisite/inspection call, which is useful positioning. However, it never explicitly says when to call this versus get_parcel_terrain, nor does it state any prerequisites or ordering.

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?

The annotations already declare readOnly, idempotent and non-destructive behavior, so the description is not required to re-state safety. It adds genuinely new behavioral context: ATC values can legitimately be negative and some values are unknown, and the agent is instructed to preserve both rather than sanitize them. It does not describe pagination or units-of-time granularity, but the output schema covers the return shape.

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 short sentences, front-loaded with the core purpose and unit before the caveats. Each sentence carries information, though the two-sentence caveat block could be tightened and the dataset-catalog hint would be clearer if it named the actual tool.

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 tool is a simple three-parameter read and the output schema plus annotations cover the result shape and safety profile, so the description is close to adequate. The gaps are the unexplained market enum and the vague 'dataset catalog' reference, which an agent must resolve to a concrete listing tool on its own.

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 0%, so the description carries the whole burden of explaining three parameters. It implies the roles of day, market and interface and gives the unit (MW) and the TTC/ATC concept, but never explains the DAM/HAM enum values or the expected format for the interface string beyond pointing at the dataset catalog.

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 ('Get regional interface TTC/ATC in MW') plus the scoping dimensions (date and market), so the agent knows exactly what data comes back. The sentence 'Interface transfer capacity is not parcel interconnection capacity' explicitly separates it from parcel-related siblings without ambiguity.

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 tells the agent where to find valid inputs ('The dataset catalog lists available interfaces/dates'), which functions as a prerequisite/dependency for calling the tool correctly. It also carves out the parcel-interconnection case as out of scope, though it never names which sibling to use for that 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?

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the description need not repeat them. It adds value beyond them by disclosing that results carry coverage limitations and by explaining that data_version, where returned, signals a changed release. It does not describe pagination or response shape, but an output schema exists to cover returns.

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 purpose is front-loaded in the first clause, and every subsequent sentence adds operational information rather than restating the name. Minor waste remains in brand framing ("Korzy") and vague phrases like "standardized attributes" and "coverage limitations" that are not cashed out.

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-only lookup with an output schema, the description supplies the ID-provenance workflow and version semantics an agent needs to call it correctly. The residual gap is that "coverage limitations" is named but never characterized, which matters for a domain (utility coverage) where incompleteness is likely.

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 0%, so the description carries the burden and mostly does: it enumerates the layer domain and links each layer to the source of its feature_id, and it explains that data_version is a release-change detector rather than an input filter. It leaves feature_id's opaque format and the data_version hash pattern unaddressed, but the operational meaning of all three parameters is conveyed.

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 a specific verb ("Fetch") plus a clearly bounded resource (a Korzy utility record by feature_id for water/sewer/treatment/gas/fiber). It also states what comes back conceptually (standardized attributes and coverage limitations). It does not explicitly differentiate itself from siblings, though the sibling list is domain-distinct enough that confusion is unlikely.

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 real usage context by specifying where each ID type originates: water/sewer/treatment IDs from point context results, gas/fiber IDs from infrastructure search results. That tells an agent the precondition for calling it. It stops short of naming explicit alternatives or when-not-to-use cases.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: the scope caveat that the fiber layer covers only California's state middle-mile network and not nationwide fiber, which prevents a serious misinterpretation of results.

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 short sentences, front-loaded with the returned fields and then the default-vs-parameter behavior; nothing is padding. The line-wrapped fragments are slightly choppy, but each sentence earns its place, including the fiber-coverage caveat.

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

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

With an output schema present, the description need not document return shapes, and its job narrows to scope, default behavior, and caveats – all of which it covers. For a one-parameter, read-only catalog tool this is close to complete; only the dataset-key format is left unspecified.

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 0% – the single 'dataset' property has no description at all – so the description carries the burden, and it does: the default/null behavior (overview of all datasets and layer keys) and the non-null behavior (product metadata, operators, energy regions) are both spelled out. It does not give the key format or examples (e.g. 'fiber'), which leaves some ambiguity against the 160-char string constraint.

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

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

Opens with a specific verb+resource ('List Korzy's datasets') and immediately enumerates the content of each entry: geographic coverage, source dates, grid interfaces, and query limits. That enumeration makes it unmistakable that this is the catalog/enumeration tool rather than one of the sibling 'get_<asset>' lookups.

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

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

It clearly splits the two usage modes: no argument returns an overview retaining every dataset and layer key, while passing a dataset key returns product metadata such as operators or energy regions. It stops short of naming alternative tools or stating any exclusion conditions, so it is clear-context guidance rather than 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?

Beyond the readOnly/idempotent annotations, the description discloses the matching model (abbreviations, partial words, typos, optional commas; house numbers exact; approximate matches labeled) and the result-shape asymmetry: exact hit returns every parcel there up to 100, otherwise up to 15 ranked locations. It also flags the cost implication of include_owner=true, which is exactly the kind of behavioral detail annotations cannot carry.

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?

Dense but front-loaded: what it finds, then matching tolerance, then result shapes, then field/cost caveats. Every sentence carries information an agent would otherwise have to discover by trial, with only minor compression possible in the korzy_id/point-lookup sentence.

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

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

An output schema exists, so return-value documentation is not owed here, and the safety profile comes from annotations. What remains missing is how the limit parameter interacts with the exact/ranked result caps, plus any hint about how many ranked candidates to expect before falling back to a point lookup.

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 0%, so the description must carry parameter meaning; it does so for address (format, abbreviation/typo tolerance, exact house numbers) and include_owner (adds published owner fields, doubles cost). The limit parameter is never named, though the 'up to 100' and 'up to 15 ranked locations' ceilings hint at result capping. Strong compensation with one gap.

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 definition opens with a specific verb and resource ('Find parcels by address'), including the expected address shape ('street, city, state'), so an agent immediately knows this is the address-based search entry point rather than an ID lookup. It does not explicitly name the sibling get_parcel as the follow-up route for a resolved korzy_id, which keeps it from a 5, but the scope is otherwise unambiguous.

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

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

Usage is implied: fuzzy address entry, with a note that korzy_id-less locations need a point lookup. There is no explicit when-to-use versus when-not guidance, no statement that get_parcel should be preferred once an ID is known, and no mention of prerequisites. Adequate but leaves routing to inference.

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