Nearby Permits

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety and repeatability are covered. The description adds the useful detail that a single record is returned and names the fields, but says nothing about missing-permit behavior, rate limits, or error handling 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?

A single front-loaded sentence with no filler: it leads with the lookup action and key, then the returned fields. Every clause earns its place.

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

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

For a simple two-parameter read tool with safety annotations already in place, the description covers purpose, keying, and return fields, which compensates for the absent output schema. The remaining gaps are the parameter formats and not-found behavior, which are minor for this tool's complexity.

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

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

Schema description coverage is 0%, so the description must carry the full parameter burden. It does convey that permit_id is a city permit number and that the two parameters form a scoped key, but neither parameter's format (e.g., expected permit-number pattern) nor the city's accepted value form is explained, leaving meaningful ambiguity.

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

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

States a specific verb (look up), a specific resource (one building permit), and the key (city permit number), and enumerates the returned fields (work, date, status, cost, address). The word 'one' plus the permit-number key clearly separates it from the list-oriented siblings permits_at_address and recent_permits.

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 rather than stated: looking up 'by its city permit number' signals it is for the case where the agent already has a permit number, which implicitly rules out permits_at_address. However there is no explicit when-to-use statement, no mention of the sibling tools, and no guidance on what to do when the number 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 readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered structurally. The description adds genuinely useful context about the return contents (cities/counties plus slugs for other tools), but says nothing about whether the list is exhaustive, stable, or how large it is.

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?

A single sentence with no filler, and it front-loads the resource and scope before the payoff (slugs for other tools). Every clause earns its place.

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

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

For a zero-parameter, read-only enumeration tool with no output schema, the description covers what it does and roughly what comes back. The one remaining gap is that it does not characterize the return set's size or stability, which is minor here.

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 and the baseline of 4 applies. The description correctly does not invent or restate any parameter information.

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 (List) and resource (US cities and counties with building permit data) plus the payload shape (each one's slug). It is immediately distinguishable from the sibling retrieval tools (get_permit, permits_near, recent_permits) as the discovery/lookup tool rather than a data-fetch tool.

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 phrase 'for the other tools' implies this is a prerequisite lookup step to obtain slugs before calling siblings, which is useful implied guidance. However, it never explicitly says when to call this versus going straight to a sibling, nor any exclusions or prerequisites.

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/openWorld, so the bar is low, and the description clears it comfortably: it enumerates the returned fields (type of work, description, date, status, reported cost), discloses the geographic coverage limit, explains the fuzzy address-matching behaviour, and documents the did_you_mean ambiguity path. That is real behavioural context not present in the annotations or 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?

Front-loaded with the use case and return behaviour, which is good, but roughly half the text is a 50-entry wall of city names that bloats the definition and duplicates what the sibling list_cities presumably provides. The matching/disambiguation sentences earn their place; the coverage enumeration is disproportionate.

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 must carry the return contract, and it does — listing the fields returned plus the did_you_mean ambiguity structure. Coverage limits and input flexibility are also covered, leaving only minor gaps around result volume or paging.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the address may be typed loosely (missing N/S, 'Drive' for 'Dr', trailing city/state/ZIP, unit) and is normalized to the city's filing spelling, and it clarifies what a supported city means for the city parameter. This goes beyond the schema's terse examples.

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 — returns every building permit on record at a given street address — and the address-based scope implicitly separates it from the time-based sibling recent_permits and the proximity-based permits_near. An agent can tell what it retrieves and by what key without opening the schema.

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

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

Opens with concrete trigger questions (which permits exist at an address, whether a house had permitted work) and gives an explicit follow-up protocol when multiple addresses match — ask which one, then re-call with the disambiguated address. It never names the sibling tools or states when a different tool (permits_near) is the better choice, so it stops short of full routing guidance.

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

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

Beyond the already-strong annotations (readOnly, idempotent, non-destructive), the description discloses defaults for radius and date, sort order, per-permit distance and compass direction, 24-month coverage limit, that counts.total is exact even when the list is capped, and the ambiguity branch (found=false with did_you_mean). This is rich behavioral context that structured fields do not 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?

Front-loaded with the triggering scenario before mechanics, and each sentence carries information. Slight redundancy from restating defaults already present in the schema, but overall dense and well-ordered.

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

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

There is no output schema, and the description compensates fully: it describes the returned items (distance in meters, compass direction, newest first), the exactness of counts.total, and the found/did_you_mean ambiguity response. An agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates defaults (radius 400m, six months back) and the since format, but adds no format or syntax detail beyond what the schema already documents for each parameter.

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 ('the tool returns building permits within a radius') scoped to proximity queries, and explicitly differentiates itself from sibling permits_at_address ('It matches a loosely typed address the same way permits_at_address does'). An agent can distinguish it from the other siblings without opening any schema.

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

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

Opens with an explicit use scenario ('when someone asks what is being built near an address or a place: new buildings next door...'). It names sibling permits_at_address as a behavioral reference but does not state when to prefer it over permits_at_address or the other siblings like recent_permits or zoning_requests_near, so routing is clear but not complete.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that — results are ordered newest-first, and scope is limited to "supported" cities/counties — but omits pagination/limit behavior and what happens for unsupported locations.

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 compact sentences that are well front-loaded: usage trigger first, return semantics second. Nothing is wasted, though "supported city or county" is slightly vague phrasing that could be tightened.

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

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

With no output schema, the description is right to say what it returns, but it doesn't specify the returned fields, the limit default, or behavior for unsupported areas. For a simple 3-parameter lookup this is adequate but leaves gaps an agent may 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 coverage is only 33% (only zip is documented), so the description has to compensate. It clarifies that zip is an optional narrowing filter and that city/county is the primary scope, which helps, but limit (max 50, default unknown) is undocumented in both the schema and the description.

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 ("Returns the newest building permits") plus scope (city/county, optional ZIP). It distinguishes itself implicitly from address- and radius-based siblings via the neighborhood/ZIP framing, but never names an alternative like permits_near, so differentiation is left partly to inference.

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

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

"Use when someone asks what is being built in their neighborhood or ZIP code" is a clear, concrete usage trigger. It offers no explicit exclusions or sibling comparisons (e.g., when to prefer permits_near or permits_at_address instead), so it stops short of the top tier.

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/openWorld, and the description goes well beyond them: it names the four supported cities, lists the status vocabulary returned, states that owner and applicant names are deliberately omitted, and commits to never inferring an outcome the city record does not state. That is substantive behavioral and data-quality disclosure an agent cannot get from the 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 sentences, front-loaded with the use case, then coverage, then inputs, then return shape and exclusions. Every sentence carries information, though the closing two sentences could be tightened slightly without loss.

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

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

With no output schema, the description carries the return-value burden and does so: status labels, hearing date, and the link to the city case record are all named, plus what is intentionally excluded. Combined with the annotation safety profile, an agent has everything needed to call and interpret the tool.

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

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

Schema coverage is 100%, so per-parameter meaning is already documented; the description still adds the non-obvious constraint that inputs are either city+address or lat/lon ('Give a city and street address, or a latitude and longitude'), which the flat optional schema does not express. It does not touch limit, since or radius_m, so it is additive rather than exhaustive.

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+resource ('zoning requests near an address or a point') and enumerates the case types it covers (variances, conditional uses, rezonings, zoning appeals), which cleanly separates it from the permit-oriented siblings. An agent can route between this and permits_near without opening a schema.

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

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

Opens with an explicit triggering condition ('Use when someone asks about variances, conditional uses, rezonings or zoning appeals near an address') and adds the follow-up intent of checking upcoming hearings. It stops short of naming the sibling tools (permits_near, recent_permits) or stating when not to use this, so it is clear context rather than full alternative routing.

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