Permit Verdicts

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

Beyond the annotations (readOnly, idempotent, etc.), the description discloses the paid nature ($0.25 via x402), self-containment of the decision_id, and the exact output components. It also cautions to keep the decision_id, adding practical behavioral context.

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 compact, front-loaded with the core value proposition, and each sentence earns its place — output summary, usage guidance, decision_id retention, and cost. No fluff 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?

Given the lack of an output schema, the description adequately covers what the tool returns (decision_id, hash, candles), when to use it, and its cost. It also highlights a critical user action (keep the decision_id), making the description self-sufficient for safe invocation.

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 parameter meanings are already documented. The description adds no extra parameter-level semantics beyond restating general purpose; it focuses on outputs and usage cost, which is acceptable but not additive to parameter understanding.

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 produces a 'Settlement verdict plus a citable record' including a signed decision_id, integrity hash, and candles. It explicitly contrasts with 'just need to know' scenarios, distinguishing it from simpler price lookup tools like get_crypto_spot or resolve_price_event.

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?

Provides explicit when-to-use ('when the answer may later have to be defended') and when-not-to-use ('not when you just need to know'). However, it does not name specific alternative tools, only implies them, so it falls slightly short of full explicitness.

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 read-only, idempotent, and non-destructive behavior. The description adds valuable context: the tool is free, quick, and returns only summary counts (no details or verdicts). This goes beyond annotations without contradicting them.

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 compact and front-loaded: it starts with 'FREE' and 'Quick check,' then states the key output. It uses two sentences to cover purpose, limitations, and alternatives with zero 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?

With only 2 parameters and no output schema, the description sufficiently explains the input (street address and jurisdiction), the output (counts, open permits, last activity), and limitations. It also provides an alternative tool, making it complete for an agent to know when and how to use it.

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 clear descriptions for 'jurisdiction' (enum) and 'address' (example provided). The description does not add param-specific detail beyond the schema, but it clarifies the overall purpose that ties the parameters together. Baseline 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 what the tool does: it checks a street address for building-permit activity, reporting permit counts, open permits, and last activity. It also explicitly distinguishes itself from get_permit_verdict by stating it provides no permit detail or verdict, making the purpose specific and non-overlapping.

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 explicit guidance: use this tool for a quick summary of permit activity, and use get_permit_verdict when permit detail or a verdict is needed. It also mentions the paid human feeds, further clarifying scope and alternatives.

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 annotations (readOnlyHint, openWorldHint, etc.), the description reveals key behavioral traits: the id is signed by the wallet receiving payment, making forgery and editing detectable. It also clarifies the limitation of the tool (does not validate correctness), which is valuable context not present in 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 reasonably concise and front-loaded with 'FREE.' It covers purpose, limitations, and an alternative in three sentences. The URL for paid feeds is tangential for an AI agent, but it does not significantly bloat the description.

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, no output schema) and the annotations cover safety. The description supplies all necessary context: what it reads, how authenticity works, the free status, and the boundary against verify_decision. There are no significant gaps.

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 already describes the parameter format (pv1.<payload>.<signature>) with 100% coverage. The description adds meaning by explaining the security significance of the signature ('signed by the same wallet that receives payment'), which enriches understanding beyond the raw format.

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's function: 'Read what a Permit Verdict decision_id claims and check whether we actually issued it.' It uses specific verbs (read, check) and identifies the resource (decision_id). It also distinguishes itself from sibling verify_decision by explicitly saying it does not tell if the verdict is still correct.

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 explicit usage guidance: it is free, requires no payment, and tells you the record is genuine. It explicitly states a when-not scenario: 'it does NOT tell you the verdict is still correct — use verify_decision for that,' pointing to the appropriate alternative.

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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context: the 5-result free preview cap and the investor feed's focus on stalled/abandoned permits with 'often motivated owners'. 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 compact sentences, with the critical free preview limitation front-loaded. The external pricing link is brief and not distracting. Every phrase 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 description effectively covers availability, scope, filtering, and feed selection. It lacks return-structure details, but with no output schema this is acceptable. The pricing link provides additional human-relevant context without bloating the description.

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 descriptions already cover all five parameters (100% coverage). The description's mention of 'declared budget' and the feed='investor' hint adds slight context but doesn't meaningfully exceed the schema's own explanations.

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 returns 'recently permitted construction projects in a covered city, filtered by declared budget'. The verb 'find' and resource are specific, and it distinguishes itself from the investor feed variant.

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 explicitly recommends using feed='investor' for expired/abandoned permits and notes the free preview limitation. It doesn't contrast with sibling tools like check_permit_activity or get_permit_verdict, but the within-tool alternative is clear and actionable.

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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context beyond that: it explains that a wide spread means venues disagree and settlements in that range are contestable, and it discloses the cost of $0.01 in USDC via x402. This goes 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 two sentences: one states the core output, the second interprets spread and mentions payment. Every sentence carries meaning, is front-loaded, and there is no fluff.

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 adequately hints at the output (price, agreement, spread) and the payment requirement. It could be slightly more explicit about how the payment_header connects to the paid model, but overall it's complete for a simple spot-price 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 both parameters (asset and payment_header) are well-documented. The description does not add parameter-specific semantics beyond mentioning the payment via x402, which is already captured in the payment_header description. Baseline 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 it returns a live cross-venue spot price, including venue agreement and spread. This is a specific verb (get) plus resource (crypto spot), and it distinguishes itself from siblings like permit tools and settlement asset lists by focusing on current price data.

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: the tool gives a live, cross-venue spot price, and it explains the meaning of a wide spread for settlement purposes. It doesn't name alternative tools explicitly, but the context is sufficient to understand when this tool is appropriate, and the payment note indicates a prerequisite.

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, idempotentHint, and non-destructive behavior. The description adds useful context beyond these: the tool is free and there are paid full feeds for humans, which clarifies the cost model and audience without contradicting any annotation.

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 concise sentences front-load the primary purpose and add relevant cost/link information without wasted words. Every sentence contributes useful detail.

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 is a simple list with no parameters and no output schema, the description sufficiently defines its scope (cities, pricing, payment details) and provides cost context. The external link for paid feeds is a practical addition.

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?

With zero parameters, the schema provides no property semantics. The description compensates by stating the output includes pricing and payment details, giving meaning to what the returned list covers, which exceeds the baseline for no parameters.

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 action ('List') and resource ('cities covered by the Permit Intelligence API'), adding valuable detail about pricing and payment information. It distinguishes this tool from siblings by explicitly naming the unique scope of covered cities.

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 notes it is 'Free' and points to paid human feeds on the pricing page, implying the API tool is for free programmatic access. However, it does not explicitly state when to use this tool versus alternatives among sibling tools, leaving usage guidance only implicit.

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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the fact that the tool is free and reports pricing, which is useful but not deeply behavioral. With annotations providing the core transparency, a score of 3 is appropriate.

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 concise, two sentences, with the key information front-loaded: 'FREE' and the coverage list. The standalone 'FREE.' is slightly awkward but not wasteful. Every word earns its place, and the external link is relevant. It loses a point for the fragmented opening, but is otherwise tight.

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 no parameters, no output schema, and strong annotations, the description covers the essential purpose and even adds the pricing link. It could benefit from stating the return format (e.g., a list of assets), but for a simple free listing tool, this is nearly complete. The annotations and simple nature lower the required richness.

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 the schema description coverage is 100% (vacuously). With no parameters to document, the baseline is 4. The description does not need to add parameter meaning and does not, which is acceptable.

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 reports which crypto assets, venues, operators, and modes the settlement oracle supports, plus pricing. The verb is implied by the name ('list') and the description uses 'which...supports' to convey the listing action. It distinguishes from sibling tools by focusing on settlement oracle coverage, though it does not explicitly contrast with list_jurisdictions.

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 minimal usage context: it marks the tool as 'FREE' and points to a paid human-facing pricing page, implying this is the free tier. However, it gives no explicit when-to-use guidance, nor does it mention alternatives like list_jurisdictions for jurisdiction-specific coverage. The link to paid feeds is a distinction but not a clear usage rule.

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 significant behavioral context beyond the annotations including that Binance is reported unavailable rather than silently counted, the payment amount and method ($0.05 USDC via x402), and the semantics of 'touch' vs 'close'. This provides the agent with important expectations about network behavior and costs that annotations alone do not convey. 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?

The description is well-structured and front-loaded. It starts with the core function, then explains output types, venues, Binance caveat, mode guidance, and payment. Every sentence contributes essential information without redundancy or fluff.

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 complexity of the tool (multiple venues, payment, mode semantics, settlement disputes), the description is remarkably complete. It covers the answer categories, evidence per venue, a potential network issue, payment details, and mode implications. Without an output schema, it still gives enough context for an agent to understand what to expect.

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 parameters have descriptions. The tool description adds extra semantics by explaining the real-world meaning of 'mode' (candle closes vs intrabar prints) and clarifying the payment_header usage ('Omit on first call to receive payment requirements'). This supplements the schema meaningfully.

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's purpose: 'Settlement verdict for a crypto price event.' It specifies the output types (YES/NO/DISPUTED/UNRESOLVED), per-venue evidence, and confidence, which distinguishes it from sibling tools like attest_price_event or get_permit_verdict. The verb 'resolve' and resource 'price event' are specific and unambiguous.

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 explicit guidance on when to use mode='close' vs mode='touch', which is a critical usage decision. It also explains the Binance region block and payment requirement. However, it does not explicitly contrast with sibling tools or specify when not to use this tool, so it's not a full replacement for usage 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 annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the payment requirement ($0.02 USDC via x402), the first-call behavior for payment_header (omit to receive payment requirements), and the fact that results can differ from the original attestation due to venue or candle history changes. This adds real behavioral context the annotations do not cover.

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 dense sentences: first states the action and statuses, second gives the exact call scenario, third explains why a fresh check is needed, and fourth covers cost and trade-off. No filler or redundancy; every sentence earns its place and key information is front-loaded.

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?

Despite no output schema, the description names all three possible outcomes, explains the payment flow, and gives the rationale for using this tool. It fully covers the tool's contract for a two-parameter, single-output operation, and the sibling-tool context reinforces its niche.

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 input schema already documents both parameters (decision_id and payment_header) at 100% coverage, so the baseline is 3. The description adds meaningful usage context by explaining decision_id is an attestation identifier and that payment_header should be omitted on the first call to trigger payment requirements, enriching the schema's basic descriptions.

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 opens with a precise verb and object: 'Re-resolve an attested settlement against the price venues right now and report whether it still holds' and names the three possible outputs (CONFIRMED, CHANGED, INDETERMINATE). It clearly distinguishes this from the act of creating a fresh attestation by emphasizing it verifies someone else's answer, which sets it apart from sibling tools like attest_price_event and resolve_price_event.

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: 'Call this whenever someone hands you a decision_id you are about to rely on.' It also explains why this is needed (attestations age, exchanges revise candle history, venues may become reachable) and contrasts with the more expensive alternative of buying a fresh resolution, giving clear selection guidance.

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