PermitReporter — US Building Permit Intelligence

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

Annotations already include idempotentHint and destructiveHint, and the description adds meaningful behavioral context: the watch is pending, additive, not a filing or proof of coverage, and requires email confirmation before alerts begin. It also reinforces safe retry behavior via submission_id. This is substantive beyond the structured 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 three sentences and front-loads the critical precondition. Every sentence adds value, though the first sentence is dense and partly duplicates parameter details and URLs already present in the schema descriptions. Still, it is appropriately sized for a sensitive authorization-gated create action.

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 has a full output schema, 100% parameter coverage, and annotations for idempotency and destructiveness, the description covers all important contextual gaps: authorization requirements, pending state, confirmation-before-alerts, and retry semantics. Nothing essential is missing for an agent to invoke it correctly.

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% and the parameter descriptions already explain email, query, county format, submission_id reuse, and authorization flags. The description mostly restates these concepts rather than adding new parameter-level meaning. A baseline of 3 is appropriate since the schema carries the semantic weight.

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 action ('Create a pending email watch') and clearly differentiates it from a permit filing or coverage proof: 'does not file a permit or prove coverage.' This makes the tool's purpose unmistakable and distinguishes it from the read/search siblings.

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 preconditions: 'only after the user reviews the exact email, search query and optional county, explicitly authorizes this request and confirmation email, and accepts...terms.' It also notes the address must confirm before alerts begin. It doesn't explicitly name alternatives, but the negative constraint and preconditions make usage context clear.

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, and non-destructive nature of the operation. The description adds useful behavioral context beyond annotations by noting that permit records retain source, record date, collection timestamp, and coverage limits. This is meaningful extra information for an agent deciding whether the returned data satisfies a request.

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 with no filler. The primary purpose is front-loaded, and the second sentence adds a concise, relevant detail about retained record attributes without bloating the definition.

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 a single required parameter, a complete parameter schema, strong annotations, and an output schema, the description is largely sufficient for a simple fetch tool. It is slightly incomplete only in not clarifying the relationship to the sibling get_permit_record, which could matter for correct tool 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?

Schema description coverage is 100%, and the schema already explains that the id is a 'guide:… or permit:… ID returned by search.' The tool description does not add meaning beyond the schema for the parameter; it only reinforces the same origin constraint, so the 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 clearly states the verb 'Fetch' and the resource: one reviewed PermitReporter guide or one collected permit record, with a specific scope ('returned by search'). It does not explicitly differentiate from the sibling tool get_permit_record, since a permit record fetch could overlap with that tool, so it falls short of a 5.

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 'returned by search' implies the intended source of IDs and suggests this tool follows a search step. However, it gives no explicit when-to-use versus when-not-to-use guidance and names no alternatives among the sibling tools, leaving some inference to the 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond that: results are 'source-linked' and 'Classifications are editorial signals, not official fields or guaranteed work,' which tells the agent about data provenance and reliability. This is meaningful disclosure not present in the structured metadata.

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 with no filler. The primary purpose is front-loaded, and the caveat about editorial signals follows naturally. Every sentence earns its place, and the structure is easy to scan.

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 do not need elaboration. The description appropriately warns that classifications are not guaranteed work. Still, with 0% parameter documentation and no usage guidance relative to four sibling lookup/search tools, the definition is not fully complete for an agent deciding among related 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?

The schema has no parameter descriptions (0% coverage), so the description must compensate, but it does not. It mentions classification 'by trade' which hints at the trade parameter, but provides no explanation of days, limit, county, or how filters combine. Defaults and bounds in the schema help, but the description leaves most parameter semantics unexplained.

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 a specific verb and resource: 'Return recent, source-linked collected permits classified by trade and project scope for contractor research.' This distinguishes it as a research-oriented aggregation tool rather than a single-record or generic search tool. However, it does not explicitly name or contrast sibling tools like search_permits or get_permit_record, so it stops short of full sibling 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?

The intended use case ('for contractor research') is stated, which gives some context for when the tool is appropriate. There is no explicit when-not-to-use guidance or reference to alternative sibling tools, so the agent must infer selections based on the title and phrasing.

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=true, idempotentHint=true, destructiveHint=false. The description adds a useful list of returned fields and the purpose, but does not go deeper into behaviors like data staleness or errors. Since annotations cover safety, a 3 is appropriate; no contradiction.

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 tightly written sentences that front-load the list of returned fields and then give a clear call-to-action. No wasted words or repetition.

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 are covered. But the description fails to clarify the parameter format and any coverage caveats (e.g., what constitutes a 'covered' county). This leaves a notable gap for correct invocation, even though the tool itself is simple.

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 description only says 'for one covered US county' without specifying the expected format (e.g., FIPS code, name, case sensitivity). This is a significant gap because the agent must infer how to populate the 'county' 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?

The description clearly states it returns coverage metadata (source route, issuer, cadence, etc.) for a specific US county, and immediately provides the use-case context ('Call this before interpreting a missing county result'). This makes it distinct from siblings like get_statewide_snapshot and get_permit_record.

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 provides an explicit trigger condition: 'Call this before interpreting a missing county result.' However, it does not name alternative tools or state when not to use it, so it lacks the full when/when-not guidance that would merit a 5.

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, and non-destructive behavior, so the description adds value beyond them by disclosing that records are 'privacy-minimized' and include canonical citation, official source link, and collection timestamp. This provides useful context about the nature and contents of the returned record without needing to restate annotation facts.

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 dense sentence with no filler. It front-loads the core action and object, then appends the included return fields. Every phrase earns its place without redundancy with the title or schema.

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 single-parameter read-only lookup with an output schema present, the description is largely complete. It specifies the retrieval method, the identifier semantics, and the key returned content. It could mention not-found behavior or response wrapping, but those are minor gaps given the simple, safe operation.

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 schema has 0% description coverage, but the schema itself already defines record_id as an integer with a minimum of 1 and marks it required. The description adds meaning by explaining that record_id is a PermitReporter record ID used to retrieve a specific record, which is important context beyond the bare schema. With one simple parameter, this is sufficient.

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 ('Retrieve'), names the exact resource ('one privacy-minimized collected building-permit record'), and identifies the lookup key ('by PermitReporter record ID'). It also lists the included fields, clearly distinguishing this from sibling search and snapshot tools.

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 clearly indicates this is for retrieving a single record by a known ID, which implies it should be used when the agent already has a record_id rather than needing to search. It does not explicitly name alternatives or exclusions, but the single-record ID-based framing provides adequate 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it guarantees no personal data is returned and clarifies the behavior for states with no collected data, going beyond what annotations convey.

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 tightly written sentences front-load the primary output and scope while immediately addressing the optional parameter. Every sentence earns its place with no redundancy or 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?

With an output schema available and all parameters fully documented, the description covers the essential return contents, the parameter-driven behavior, and the privacy guarantee. Nothing an agent needs to correctly invoke this tool 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?

The schema description already fully documents the `state` parameter (pattern, examples, omit for national). The tool description adds the behavioral nuance that passing `state` yields 'collected coverage' and an explicit answer for empty states, enriching the semantic meaning beyond the formal 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 states a specific action ('Return current PermitReporter counts, route-status boundaries, record-date range and latest collection timestamp') and explicitly excludes personal data, making the tool's purpose unambiguous. It clearly differs from siblings like get_county_coverage (which likely focuses on counties) and get_permit_record (individual records), establishing its role as a statewide snapshot.

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 use the `state` parameter versus omitting it for the national snapshot, and notes that state-level results include an explicit answer for uncollected jurisdictions. However, it does not explicitly name alternative tools for when this tool should not be used, leaving some inference required for sibling differentiation.

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, and non-destructive behavior. The description adds useful behavior beyond annotations by stating the output is canonical URLs and that full source retrieval requires a fetch call. It also notes the data is 'reviewed' and 'privacy-minimized,' giving the agent context about data quality and scope.

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 sentences with no filler. The search action is front-loaded, the return behavior is stated, and the downstream fetch step is included. 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?

The tool is simple (one parameter), has safety-relevant annotations, and an output schema exists, so the description does not need to explain return values in depth. It could be more complete by clarifying how it differs from the similarly named 'search_permits' sibling, but the existing description covers the agent's immediate needs.

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%, and the schema already documents the single 'query' parameter as a natural-language question about US building permits or PermitReporter. The tool description does not add extra meaning about query formatting, examples, or edge cases, so the baseline 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 uses a specific verb ('Search') and identifies the exact resource: 'PermitReporter reviewed guidance and privacy-minimized collected building-permit records.' It also clarifies the return type (canonical URLs for citation). It does not explicitly distinguish itself from the sibling tool 'search_permits,' so it falls short of a 5.

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 clear usage context: use this for searching collected permit records and getting citation URLs, then 'Call fetch with a returned ID for the full source.' It provides a concrete next-step routing to fetch, though it does not mention exclusions or how to choose between 'search' and the sibling 'search_permits.'

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 description adds meaningful behavioral detail beyond the annotations: results are privacy-minimized, raw payloads and party arrays are omitted, and empty results are explicitly defined as 'no matching record collected, not that no permit exists.' This is exactly the kind of boundary condition an agent needs to avoid misinterpreting an empty response.

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 sentences with no filler: first sentence states the search capabilities, second gives coverage and county formatting, third clarifies empty-result meaning. Essential information is front-loaded and each 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?

Given the rich annotations, output schema, and moderate complexity, the description covers searchable fields, geographic coverage, privacy posture, and empty-result interpretation. A small gap is the lack of explicit statement about how multiple filters combine (AND vs OR), but this is common and inferable. Overall it is sufficient for an agent to invoke the tool correctly.

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 does a good job mapping 'public text' to query, 'county' to county, 'city' to city, 'PermitReporter trade classification' to trade, and 'record-date range' to date_from/date_to. It omits the 'limit' parameter and does not specify exact date/text matching semantics, but the core parameter meaning is well 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 clearly identifies the tool as a search over collected building-permit records, with specific categorical filters (public text, county, city, trade, date range). It is specific enough to distinguish itself from siblings like get_permit_record or get_county_coverage, though it does not explicitly name an alternative -- which keeps it one step below the highest bar.

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 concrete operational guidance: coverage spans 34 states plus DC, and county naming conventions are described with examples ('Cobb' vs 'Los Angeles, CA'). It does not explicitly contrast with sibling search tools, so the 'when-not-to-use' half of usage guidance is absent, but the context is clear enough.

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