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

Beyond annotations (readOnly/idempotent/openWorld), it discloses the full result taxonomy (has_permit, expired, no_permit_found, close_match, audit_only), the payload contents (status, expiry date, city-formatted address, record link), the paid fallback, and hard rate limits of 25 lines per call and 200 per hour. That is unusually rich behavioral context for a read-only lookup.

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 key constraint (free, no key) and the core capability, then the result/fallback details. The long parenthetical city roster is bulky but earns its place by defining coverage; overall it is a single tight paragraph with little 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?

With no output schema, the description properly explains return statuses and payload fields, plus limits and the paid fallback. Minor gaps remain: what close_match implies for confidence, and behavior when an address is ambiguous or a city is misspelled.

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 city/address/lines parameters are already fully documented in the schema. The description only echoes the batch cap of 25 that maxItems already enforces, adding no syntax or format guidance beyond structured data.

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 concrete verb and resource: checks each address against the city's own published STR permit list, and enumerates the 18 live-searchable jurisdictions. The scope is unmistakable, but it never names or contrasts the overlapping sibling `civicdataforge--str-permit-registry`, leaving the agent to guess 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 implies selection criteria by flagging 'Free, no key needed' and by explaining that non-live places fall back to audit_only with a $4.99 audit link, which helps the agent decide when this is the cheap path. However, there is no explicit when-to-use/when-not statement and no routing to the sibling registry or evidence-gateway tools.

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