Permit Verdicts

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 fully covered by structured data. The description adds the openWorldHint-related trait that the result may include no permit data ('on record'), and that it's 'FREE' with a limited scope. It doesn't describe response format/pagination, but given good annotations this is adequate.

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. The description front-loads the purpose and key trait (FREE), enumerates the specific outputs, and closes with a precise pointer to the alternative tool. 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?

For a simple 2-param read-only tool with 100% schema coverage and complete annotations, the description is complete. It clearly delimits what this tool returns (counts and last activity) versus what it doesn't (permit detail, verdict), fully managing agent expectations. No output schema is needed for this simple return type.

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% with both parameters (address and jurisdiction) well described in the schema itself. The description adds the scope context of 'on record' but doesn't provide additional syntax or format details beyond what the schema already documents. Baseline 3 is appropriate 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?

The description uses a specific verb 'check' with a clear resource ('building-permit activity on record') and explicitly states what outputs are provided: how many permits, how many open, and when last activity occurred. It clearly distinguishes this quick-check tool from the more detailed get_permit_verdict sibling.

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 explicitly names when to use this tool (quick free check on permit activity) and when NOT to use it ('no permit detail and no verdict — use get_permit_verdict for those'). This provides clear exclusion guidance relative to a named alternative, which is exactly what usage guidelines should do.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about the free preview limit (5 results) and that 'investor' feed surfaces 'stalled projects, often motivated owners' — which is genuinely useful behavioral/domain insight 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?

Two sentences, front-loaded with the free preview caveat, efficient and zero waste. The preview notice at the start is appropriately prioritized since it's critical for agent decision-making.

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 5 params, 100% schema coverage, and readOnly annotations, the description largely suffices. However, the free preview limit is disclosed but no guidance is given on what happens beyond 5 results (pagination? truncation?), which is a meaningful gap for an agent planning a full-fetch workflow.

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 all 5 parameters are documented in the schema. The description adds brief value by noting the free preview limit and the feed semantic (investor vs contractor), but doesn't add meaning beyond the schema for individual parameters like min_cost/max_cost 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?

The description clearly states the tool finds construction projects filtered by budget, with a specific verb+resource. It doesn't explicitly distinguish from siblings like check_permit_activity or get_permit_verdict, but the scope ('recently permitted construction projects in a covered city') is reasonably 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 clear context on the free preview (5 results) and directs users to feed='investor' for stalled/expired projects. It's missing explicit when-not-to-use guidance versus siblings like check_permit_activity, but the feed guidance gives solid directional 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 provide readOnlyHint=true and idempotentHint=true covering the safety profile. The description adds the payment/pricing detail ($2.00 USDC via x402), which is a behavioral trait not visible in annotations and critical for the agent to know. It also discloses the 'decision-ready verdict with cited public records' nature of the output. No contradiction with 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?

Two sentences, front-loaded with purpose, and the payment info is compactly stated. Every sentence earns its place. Slight inefficiency: the payment detail could arguably be split but is already concise.

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 paid API tool with full schema coverage and read-only/idempotent annotations, the description captures the essence: it's a comprehensive, paid permit-intelligence verdict service covering specific cities. The payment model is disclosed, which is the main non-obvious aspect. Could add what the verdict format looks like, but given readOnlyHint and no output schema, the coverage is reasonably 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 coverage is 100%, so all three parameters have descriptions in the schema itself. The description adds the payment-header flow context ('Omit on first call to receive payment requirements' is in schema too). The description's main added value is the overall commerce model, not per-parameter detail. Baseline 3 is appropriate given full schema coverage.

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?

Description clearly states it provides 'address-level building-permit intelligence' with normalized history, activity signals, and a decision-ready verdict with cited public records. It clearly differentiates from siblings (find_active_projects, check_permit_activity) by being the comprehensive 'verdict' tool. Loses a point for not explicitly naming which sibling to use instead for lighter queries.

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 paid x402 payment flow is clearly disclosed ('Paid: $2.00 in USDC'), which is important usage guidance. However, it doesn't explicitly say when to use this vs check_permit_activity or find_active_projects. The 'first call to receive payment requirements' hint in payment_header param helps but the usage boundary between siblings is implicit, not stated.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the 'Free' pricing disclosure and the presence of pricing/payment details in results. No annotation contradiction. With strong annotations, the modest additional context earns a solid 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?

One sentence, front-loaded with the main purpose, includes the valuable 'Free' disclosure. Brief but sufficient for a parameterless listing tool. Slightly terse given the sibling tools do similar work, but no wasted words.

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 strong annotations and no output schema, the description covers the core: what's listed, what information accompanies it, and the cost. It doesn't specify the return format, but no output schema exists, and listing tools are typically self-explanatory in output. Acceptable given the simple nature.

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 has zero parameters and 100% schema coverage (nothing to cover). The description clarifies what the tool returns (cities, pricing, payment details), adding meaning beyond the empty schema. Baseline is 4 for a zero-parameter tool.

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?

Clear verb+resource: 'List cities covered by the Permit Intelligence API'. It specifies the deliverable (list of cities) and adds pricing/payment context. While it doesn't heavily differentiate from siblings (which are action-oriented tools like check_permit_activity, find_active_projects), the tool name itself is sufficiently distinct.

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 states this is a listing/enumeration tool and mentions it includes pricing and payment details, which tells the agent what kind of information it will get. It also notes 'Free' which is a usage signal. It doesn't explicitly say when-not-to-use or name alternatives, but as a top-level enumeration tool, the context is reasonably clear.

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