Permit Scouter

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

With no annotations, the description carries the full behavioral burden and does disclose the notable traits: this is a paid call at $0.10, settled via x402 in USDC on Base, and it returns aggregate job value and trade counts rather than raw records. It omits pagination behavior, result caps, and what happens for an unknown contractor_key.

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 tight sentences: the first front-loads what is returned, the second front-loads cost and payment rails. No filler, no redundancy.

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

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

There is no output schema, so the description responsibly summarizes the return shape (permits plus total job value and trade counts) and adds the cost/payment context an agent needs before calling. It leaves gaps only around result volume, pagination, and error behavior.

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?

Only one parameter with 100% schema description coverage, so the schema already documents contractor_key formatting (license number, lower case). The description adds no further parameter detail, which is the baseline expectation here.

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: retrieving every permit a contractor has pulled, plus aggregate value and trade counts. This clearly separates it from sibling property_history (property-scoped) and get_permit (single permit), though it never names those siblings explicitly.

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 required contractor_key input and the contractor-centric framing, but the description never states when to prefer this over property_history or search_permits, nor any preconditions beyond payment. Adequate but leaves the agent to infer routing.

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?

With no annotations, the description carries the full behavioral burden. It discloses one genuinely useful trait, 'Free' (no cost/credit consumption), but offers nothing about permissions, read-only nature, rate limits, or freshness guarantees. The 'last update time' phrase largely restates return data already covered by the output schema, so real added behavioral context is thin.

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 short sentence with 'Free' front-loaded as the most decision-relevant token. No filler, though the flat comma list of returned fields is unprioritized and partially duplicates the output 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 zero-parameter info tool with an output schema, the description is minimally sufficient: it flags cost and names the data categories. It falls short by not explaining the practical use case (e.g., verifying that permit data exists for a city before issuing a search), which is the main thing an agent would need to route to 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?

The tool takes zero parameters and schema coverage is 100%, so there is nothing for the description to clarify. Baseline for a parameterless tool applies, since parameter semantics are not a meaningful axis here.

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 enumerates what the tool surfaces (cities covered, permit counts, date range, last update time), which lets an agent infer it is a metadata/coverage lookup. However, it reads as a bare noun list with no verb or explicit statement of what the tool does, and it never distinguishes itself from siblings like search_permits or sample_permits. Purpose is implied 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?

'Free' hints that calling it is cheap, which loosely implies it can be called early or speculatively, but there is no explicit when-to-use guidance and no mention of the alternative tools. An agent gets no instruction on whether to check coverage before calling search_permits or get_permit.

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?

With no annotations, the description carries the full burden, and it does disclose a genuinely useful trait beyond structured data: this is a paid call ($0.01 per call, x402/USDC on Base). It also implies a read of full change history. It stops short of permissions, error behavior on unknown permits, or whether payment is automatic, which holds it at a 3.

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, zero waste, and the purpose is front-loaded before the billing note. Nothing repeats the name or title.

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?

No output schema exists, so the description must carry return-value meaning, and it does sketch the payload (permit plus every recorded change to status, value, issue date) and the cost model. Missing only edge-case behavior for invalid source/permit_number, which is minor for a single-record 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 100%, and both parameters (source, permit_number) have example values in the schema. The description adds no format or syntax detail beyond the schema, so the baseline 3 is correct.

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 precise resource and scope: a single permit plus the full change history of its status, value and issue date. 'One permit' implicitly contrasts with search_permits/sample_permits, but it never names a sibling or uses an explicit verb, 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?

There is no when-to-use guidance at all: nothing tells the agent to pick this over search_permits for a known permit_number, nor what prerequisites exist. The only usage-adjacent content is billing, not selection 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?

With no annotations, the description carries the full burden, and it does disclose genuinely useful behavior: cost ($0.05 per call) and the payment mechanism (x402, USDC on Base), which an agent must know before invoking. It says nothing about pagination, result caps, or rate limits, so the transparency is partial rather than rich.

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, zero filler, with the scope and ordering front-loaded ahead of the cost note. 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 2-parameter read tool with no output schema or annotations, the description covers scope, ordering, and pricing adequately. The main remaining gap is pagination/result-limit behavior for a tool that claims to return 'every' permit, which could matter for dense addresses.

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% – the address example format and the zip's narrowing purpose are already documented in the schema. The description adds no format or matching semantics beyond that, so the baseline 3 applies.

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: returns all permits recorded at one street address, with an ordering guarantee ('newest first'). The address-scoped full-history framing implicitly separates it from contractor_history (by contractor) and get_permit (single permit), though no sibling is named.

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, and no alternative is named. The scope phrase 'one street address' only faintly implies this is the full-history counterpart to get_permit; an agent gets no routing help among the five siblings.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the two key constraints an agent needs — the tool is free and returns only three recent records — but says nothing about permissions, rate limits, or whether the output is truncated in shape versus the paid tools.

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 fragments with no filler, and the most decision-relevant fact ('Free') is front-loaded. The telegraphic phrasing slightly hurts readability, so it falls just short of 5.

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 the description needn't describe return values. For a zero-parameter tool it covers what is returned and why, though it could note that the sample is not representative of full result volume.

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 per the rubric the baseline is 4. There is no parameter behavior the description needs to compensate for.

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+resource (returns sample permits) and scopes it to 'three recent' records, which is enough for an agent to tell it apart from get_permit or search_permits. It stops short of explicitly naming which sibling is the paid alternative, so it isn't 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?

'to see the record format before paying' gives a clear condition for using this tool rather than a full query. There is no explicit when-not or named alternative, but the usage context is unambiguous.

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?

With no annotations, the description carries the full behavioral burden and does disclose real traits beyond the schema: result ordering ('Newest first'), a hard per-call cap ('up to 25 per call'), and a concrete paywall ('$0.02 per call, x402, USDC on Base'). It stops short of explaining paging behavior via offset or what an empty/over-limit result looks like, so it is useful but not complete.

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, zero filler, and the core capability is front-loaded before the ordering/cap and pricing constraints. Nothing repeated from the schema is wasted.

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 10-parameter search tool with no annotations and no output schema, the description covers scope, sort order, cap, and cost, but omits the return shape (permit fields) and how offset paging interacts with the 25-item ceiling. Adequate but with clear gaps an agent would need to discover by calling.

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 each of the 10 parameters (limit range, trade enum values, since/until format, jurisdiction key) is already documented in the schema. The description's facet list restates those fields without adding format or interaction semantics, which is the baseline-3 case when the schema does the heavy lifting.

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 ('Search new building permits') plus the facets it can search on (trade, job value, date, zip, city), so the agent knows exactly what the tool returns. It does not name or distinguish itself from siblings like get_permit or sample_permits, which keeps it at a 4 rather than 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?

Usage is only implied: 'search' plus facet list suggests this is the query tool for permits, but there is no explicit when-to-use, no condition for choosing it over sample_permits (preview) or get_permit (single record), and no mention of a required prerequisite such as first calling coverage for jurisdiction keys.

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