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 readOnlyHint, idempotentHint, and destructiveHint, establishing safety. The description adds context about what the tool does not do (no permit detail, no verdict) and notes it is free. This goes beyond annotations, though it does not discuss rate limits or authentication, which is acceptable given the annotations' coverage.

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 at three sentences, with the core purpose in the first sentence. The second sentence provides a crucial exclusion and alternative. The third sentence about paid feeds is slightly extraneous for an AI agent but is short and does not detract significantly. Overall, well-structured and efficient.

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 check tool with two parameters and no output schema, the description fully covers what it returns (counts, open, last activity) and what it omits (detail, verdict). It also names a sibling tool for deeper queries. Annotations cover safety, making the description complete for its complexity.

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%, with both parameters (address, jurisdiction) described and jurisdiction having an enum. The description's mention of 'street address' aligns with the address parameter but does not add new semantic detail. The baseline of 3 is appropriate as the schema carries the parameter documentation burden.

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 whether an address has building-permit activity, specifying exactly what it returns: number of permits, open permits, and last activity date. It distinguishes itself from sibling tool get_permit_verdict by explicitly noting that permit detail and verdicts are not provided.

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 a 'quick check' for activity counts, not for details or verdicts. It directly names the alternative tool: 'use get_permit_verdict for those,' making the decision boundary clear.

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

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

Annotations already declare readOnly/idempotent, but the description adds valuable behavioral context beyond that: the signature mechanism prevents forgery and editing, and the tool does not validate verdict correctness. It also clarifies there is no payment requirement, which is not evident from 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 front-loads key facts ('FREE. Read...') and remains informative across a few sentences. It includes a marketing link that is slightly tangential but not excessive; overall it earns a high score for density.

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

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

For a single-parameter read-only tool with no output schema, the description covers purpose, security model, cost, limitations, and alternative. This is complete enough for an agent to decide when to invoke and 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 covers 100% of the parameter with a format description, so baseline is 3. The description adds the security relevance of the signed format but doesn't go beyond the schema to explain parameter semantics further.

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 a specific action: 'Read what a Permit Verdict decision_id claims and check whether we actually issued it.' It names the resource (decision_id) and differentiates from sibling verify_decision, making its purpose 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?

Explicit usage guidance is provided: 'This tells you the record is genuine; it does NOT tell you the verdict is still correct — use verify_decision for that.' This directly tells the agent when to use this tool versus the alternative, plus notes it is free and requires no payment.

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/destructive hints, so the bar is lower. The description adds valuable context: the 5-result preview limit, the feed behavior differentiation, and the link to paid feeds, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long, front-loaded with the critical free-preview limitation, and every sentence contributes useful information without 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?

The description covers the tool's purpose, preview limit, and feed options, but with no output schema it doesn't indicate what fields the results contain. It also doesn't mention the days parameter or jurisdiction list, which are only in the schema. Overall, it's adequate but leaves some 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?

Schema description coverage is 100%, so the baseline is 3. The description adds some context about budget filtering and feed semantics, but these are largely already in the schema's parameter descriptions, so no significant new meaning is added.

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 active construction projects in a covered city, filtered by declared budget, with a specific verb and resource. It also distinguishes the investor feed variant, making its scope explicit and different from other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool (recently permitted projects) and explicitly recommends feed='investor' for stalled projects. However, it doesn't mention alternatives among sibling tools, so it stops short of full when-not 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 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds no contradicting information and contributes slight extra context ('Free', 'payment details'), but does not elaborate on return format or behavioral nuances. With robust annotations, a 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?

Two short, front-loaded sentences. The first states the primary action and resource; the second adds relevant context about cost and a link. Every word earns its place, with 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?

For a zero-parameter, read-only list tool with strong annotations, the description sufficiently covers what the tool does, what data it returns (cities, pricing, payment details), and its free nature. It could optionally mention that it returns a list or the structure, but given the simplicity and lack of output schema, the description is nearly 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?

Tool has zero parameters. Per rubric, this yields a baseline of 4. The description does not need to explain parameters, and it doesn't, so the score reflects the absence of need rather than a compensation effort.

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 uses a specific verb ('List') and resource ('cities covered by the Permit Intelligence API') and adds scope ('with pricing and payment details'). This clearly differentiates from sibling tools like get_permit_verdict or find_active_projects, making its purpose 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 clear context by noting the tool is 'Free' and pointing to paid feeds for humans. This implies the tool is the free way to access jurisdiction data, giving an agent a sense of when to use it. However, it does not explicitly mention alternatives or when not to use it, so it stops 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, open-world, and non-destructive behavior. The description adds the 'FREE' distinction and clarifies that full paid feeds are for humans, which is useful behavioral context about cost and audience. 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 a single, well-structured sentence that front-loads the key 'FREE' tag, followed by the core purpose and a link for more info. Every word earns its place, with 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?

For a parameterless list tool with no output schema, the description adequately conveys the full scope of information returned (assets, venues, operators, modes, pricing). Annotations cover safety traits, making the description complete for the agent to decide 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?

The tool has zero parameters, and the schema coverage is effectively 100% (an empty schema). With no parameters to explain, the description is not expected to add parameter details, so the baseline 4 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?

The description uses a specific verb 'list' and clearly identifies the resource: 'which crypto assets, venues, operators and modes the settlement oracle supports, plus pricing.' This distinguishes it from siblings like list_jurisdictions, which would cover legal jurisdictions, not settlement asset 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 provides clear context: it is a free tool for querying settlement oracle coverage and pricing. It also points to the paid human-facing feeds via a link, offering an alternative for more comprehensive data. However, it does not explicitly name sibling tools as alternatives, so it stops 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?

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.