permitverdict-mcp

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

Goes well beyond annotations by disclosing the record's self-contained nature, the cost ($0.25 paid via x402), free authentication, and re-check pricing. These are behavioral traits not present in the readOnly/idempotent hints, adding significant transparency about side effects and requirements.

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 yet information-dense: it defines the output, states usage criteria, emphasizes preserving the decision_id, and mentions cost. Every sentence earns its place without fluff or repetition, and front-loads the core purpose.

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 adequately explains the return value (signed decision_id, hash, candles) despite the lack of an output schema, and includes usage and payment context. It could mention error conditions or prerequisites like payment_header, but the essentials are covered. Given the tool's complexity, this is near-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 baseline is 3. The description does not elaborate on asset, operator, or threshold beyond the schema, but it does add context for payment_header by explaining the paid mechanism. No additional parameter-level semantics are provided.

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 produces a signed decision_id, integrity hash, and candles as a citable record, distinguishing it from siblings like resolve_price_event or get_crypto_spot. It explicitly frames it as an attestation for defensive use, not just information lookup.

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 guidance: 'Use this when the answer may later have to be defended to a counterparty, not when you just need to know.' This contrasts with simpler lookup tools and gives clear context for selection. It also mentions payment requirements, which is crucial for invocation.

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 useful behavioral context beyond annotations: it's a 'quick check' that returns aggregate counts and last activity, and explicitly states what it does not return (permit detail or verdict). This sets clear expectations about the tool's granularity and limitations.

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, front-loaded with 'FREE. Quick check.' Every phrase adds value: the scope, the return values, and the explicit exclusion of detail/verdict. No fluff or redundant explanation.

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-parameter tool with no output schema, the description adequately explains the return shape ('how many permits, how many are open, and when the last activity was') and sets boundaries ('No permit detail and no verdict'). This is complete for the tool's simplicity, and the sibling alternative is provide.

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?

Both parameters have full descriptions in the schema (100% coverage), so the schema does the heavy lifting. The description mentions 'street address' but adds no additional semantics about the parameters beyond what the schema already provides. Baseline 3 is appropriate because the description neither enriches nor degrades 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 the tool checks for building-permit activity at a street address and specifies the exact outputs (count of permits, open permits, last activity). It explicitly differentiates from the sibling tool get_permit_verdict by stating 'No permit detail and no verdict — use get_permit_verdict for those.'

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 usage context: it's a quick, free check for high-level permit activity. It explicitly names the alternative tool for permit detail or verdicts, telling the agent when not to use this tool. However, it doesn't enumerate other potential alternatives or when to choose this over other sibling tools like find_active_projects, so it falls short of 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 declare read-only, idempotent, non-destructive, and open-world hints. The description adds valuable behavioral context beyond these: the signature is by the paying wallet, making forgery/editing detectable, and it clarifies that authenticity does not imply current correctness. 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 four sentences, front-loaded with 'FREE' and an immediate action verb. Every sentence adds distinct value: purpose, authentication mechanism, cost, and exclusion of correctness verification. No 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 a single parameter, full schema coverage, and no output schema, the description adequately covers what the tool does, what it doesn't do, its free status, and points to verify_decision for the complementary need. It is complete for the tool's simplicity.

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 a clear description of the decision_id format. The description adds context about the id being a signed Permit Verdict id, but does not add new parameter-level syntax or semantics beyond what the schema already provides. 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 clearly states the tool's purpose: to decode a decision_id and verify authenticity ('read what... claims and check whether we actually issued it'). It distinguishes from sibling verify_decision by explicitly stating it does NOT tell if the verdict is still correct, making its scope 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?

Explicitly provides when to use: it is free and needs no payment. Explicitly provides when not to use and the alternative: 'use verify_decision for that' when checking if the verdict is still correct. This gives clear decision-making 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?

Annotations already mark it as read-only and idempotent. The description adds the important 'FREE PREVIEW (5 results)' limitation and explains the behavioral difference of the investor feed (expired/stalled permits). It does not describe pagination or output format, but given the annotations, this is sufficient.

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, front-loaded with the key limitation, and every clause adds value. It efficiently conveys the tool's scope and its alternative feed.

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 has no output schema, but the description states it returns up to 5 construction projects, which is adequate. It explains scope and the alternative use case. It might benefit from describing result fields, but for a simple preview tool, this is sufficient.

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 parameters are documented. The description enriches the 'feed' parameter by explaining when to use 'investor' and clarifies that results are filtered by declared budget, adding meaning to min_cost/max_cost.

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 clear verb 'find' and specifies the resource: active construction projects in a covered city, with budget filtering. It distinguishes itself from related permit tools by focusing on active projects and mentioning the alternative investor feed.

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 explicit guidance on using feed='investor' to surface expired/abandoned permits, which indicates when to modify the query. However, it does not directly compare to sibling tools like check_permit_activity or get_permit_verdict, though the context implies this is the tool for finding projects.

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 cost ('$0.01 in USDC via x402'), the live nature, and the interpretive meaning of the spread, which enriches behavioral understanding without contradicting 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 the core function, followed by critical interpretation and cost. No filler words or 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?

For a simple read-only price tool with no output schema, the description covers what it returns, the meaning of spread, and the payment requirement. It does not specify the response format, but this is acceptable given the tool's simplicity.

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 the baseline is 3. The description does not add parameter-specific semantics beyond the schema, though it does mention the payment requirement which relates to the payment_header parameter, but this is not a thorough explanation of each 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 identifies the tool as returning a live cross-venue spot price, with the explicit concept of venue agreement and spread. This distinguishes it from sibling tools focused on attestation, permits, and decisions.

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 usage context by explaining the significance of wide spreads ('any settlement in that range is contestable'), helping the agent decide when the price is reliable. It also notes the payment cost, but does not explicitly compare to alternative tools.

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 readOnly/idempotent/non-destructive behavior. The description adds valuable context beyond annotations: the tool is paid ($2.00 USDC via x402), requires a covered city, and returns cited public records. It does not mention rate limits or error conditions, but the payment and coverage details are meaningful.

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, front-loaded with the core purpose and output components, and the payment detail in the second sentence. No wasted words; every element 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 is reasonably complete for a read-only tool with robust annotations and full parameter schema coverage. It outlines the three output components (history, signals, verdict) and mentions the payment requirement. It lacks details on response structure, but the absence of an output schema is somewhat mitigated by the description's explicit list of result components.

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 schema already explains jurisdiction and address. The description adds no additional parameter-level detail beyond the schema. It does reinforce that jurisdiction must be a covered city, but this is already encoded in the enum. 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 the tool produces address-level building-permit intelligence, including permit history, activity signals, and a decision-ready verdict. However, it does not explicitly distinguish this from sibling tools like check_permit_activity or find_active_projects, relying on the word 'verdict' to imply uniqueness.

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 implies usage: it is for obtaining a verdict about building permits at a specific address in a covered city. It does not explicitly state when to use this over alternatives (e.g., check_permit_activity) or provide exclusions. The payment requirement is mentioned but not framed as a usage decision.

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. The description adds the 'Free' aspect and the fact that the response includes pricing and payment details, which are useful behavioral traits beyond the annotations. No contradictions.

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 short sentences: the first clearly states the action and content, the second adds the cost detail. Every word is essential and front-loaded, with no unnecessary 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?

For a simple no-parameter list tool with no output schema, this description is nearly complete: it states what is returned (cities, pricing, payment details) and the cost. It could optionally hint at the response structure, but given the simplicity, it is sufficient.

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, so the schema coverage is 100% and the baseline is 4. The description doesn't need to explain parameters, and it doesn't, which 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 states a specific verb ('List') and resource ('cities covered by the Permit Intelligence API'), and adds detail about content (pricing and payment details). This clearly distinguishes it from sibling tools like attest_price_event or check_permit_activity, which focus on other actions.

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 implies when to use this tool: to discover which cities are covered and their pricing/payment details. It doesn't explicitly mention alternatives, but there are no obvious sibling tools for this purpose, so clear context is provided without needing exclusions.

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, non-destructive behavior. The description adds the 'FREE' cost aspect and specifies the enumerated data categories (assets, venues, operators, modes, pricing), giving context beyond the schema. No contradictions.

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 sentence with 17 words, front-loaded with 'FREE', and no redundant words. Every word adds useful information.

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's simplicity (no params, clear annotations, single-purpose), the description fully covers the need. It tells the user exactly what information is available (coverage and pricing) without requiring output schema. The sibling list_jurisdictions reinforces the convention.

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 is empty. The description correctly focuses on the output content rather than inputs. The baseline for zero-param tools is 4.

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: enumerating supported crypto assets, venues, operators, and modes for the settlement oracle, and including pricing. This is a specific verb (list) plus resource and scope, and it distinguishes from siblings like list_jurisdictions by focusing on settlement coverage.

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 implies use when the user needs to know the settlement oracle's coverage and pricing. It provides a clear context ('FREE' indicates low-risk informational use) but does not explicitly mention alternatives or situations to avoid this tool.

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 detail beyond annotations: it discloses that Binance is blocked by region and will be reported unavailable rather than silently omitted, and states the $0.05 USDC x402 payment. These are non-obvious traits not captured by readOnlyHint or idempotentHint.

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 dense but each sentence earns its place: purpose, answer format, venue availability caveat, mode guidance, and payment. It is appropriately sized for a tool with 7 parameters and complex settlement logic.

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 compensates by stating the return values (verdicts, per-venue evidence, confidence) and key edge cases (Binance unavailable, mode differences, payment requirement). This is complete enough 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the semantic difference between mode='touch' and 'close' (intrabar vs candle closes) and that this choice often changes the answer, which goes beyond the schema's brief enum 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 clearly states the tool's function as a 'Settlement verdict for a crypto price event' and explains the answer format (YES/NO/DISPUTED/UNRESOLVED) with per-venue evidence. It is very specific, but it does not explicitly differentiate itself from the sibling tool 'attest_price_event', which could be a similar operation.

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 guidance on when to use mode='close' vs mode='touch', calling out the difference as the most common settlement dispute. However, it does not mention when to use this tool instead of alternatives like attest_price_event or verify_decision.

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, but the description adds valuable behavioral context: it states the operation is paid ($0.02 USDC via x402), that it re-resolves against price venues, and the real-world rationale (candle history revisions, venue reachability). This goes well beyond the 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 a single, well-structured paragraph that leads with the core action and outputs, then provides usage rationale and cost. Every sentence adds value—there is no fluff or repetition of schema content.

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 has rich annotations, full schema parameter coverage, and no output schema, so the description's job is to explain why and when to use it. It names the three possible return values, explains the payment mechanism, and gives concrete environmental reasons for re-verification. This is complete for an agent deciding whether to use the 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 coverage is 100% and both parameters (decision_id, payment_header) have clear descriptions. The description reinforces that decision_id is an 'attested settlement' and mentions the payment cost, but it does not add substantive parameter-level detail beyond what the schema already provides, 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 opens with a specific verb 'Re-resolve' and names the resource ('an attested settlement'), the method ('against the price venues right now'), and the exact outputs (CONFIRMED, CHANGED, INDETERMINATE). This clearly distinguishes it from siblings like resolve_price_event (fresh resolution) and decode_decision_id.

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 states when to call ('whenever someone hands you a decision_id you are about to rely on') and explains why attestation alone is insufficient because exchanges revise candle history and venues may become reachable. It also contrasts with 'resolving fresh' and notes the cost advantage, giving clear decision context.

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