Corbelworks Utility Defect Scan and Buyer Intake

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

Annotations provide no hints (all false), so the description carries the full burden. It discloses key behaviors: no payment taken, pseudonymous and agent-operated, AI involvement disclosed, response within 48 hours, and honest rejection. This is substantial transparency, though it doesn't mention idempotency or side effects, but given the nature of an intake request, that is not critical. It adds value beyond the 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, dense sentence that front-loads the core action (describe want and willingness to pay) and then provides key behavioral facts. Every clause earns its place, with no fluff or redundancy. It is efficient and well-structured.

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 presence of an output schema (so return format need not be explained), the description covers the key expectations: how to frame the request, the response timeframe, payment policy, and the nature of the counterparty. It doesn't discuss error cases or follow-up steps, but for an intake tool this is sufficient. Slightly more detail on post-submission behavior could be added, but it 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 description coverage is 57% (4 of 7 parameters have descriptions). The description does not explicitly map to parameters like 'want' or 'budget' beyond the general 'describe what you want done and what you are willing to pay,' which weakly corresponds to two of the fields. It adds little detail for the uncovered parameters (budget, handle, deadline) that could benefit from clarification, so it does not compensate for the coverage gap.

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 title 'File a Buyer Intake Request' and description clearly state the verb (file/intake) and resource (buyer request), and the description expands on the process. It distinguishes from siblings like permit_inspection_exception_watchlist or purchase_utility_defect_scan by focusing on the intake of a buyer request, so an agent can tell it apart.

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 when to use it (to file a buyer intake request) but offers no explicit guidance about when not to use it or how it compares to sibling tools. It does not name alternatives or exclusions, so it relies on the agent to infer from context. That is adequate but not explicit.

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, and non-open-world. The description adds meaningful behavior beyond these: 'Deterministic,' 'does not query live jurisdiction systems,' and the 250-row limit. This enriches the agent's understanding of what the tool does and its operational boundaries.

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 with no filler. The first sentence front-loads the core function and scope; the second adds a crucial caveat. Every word 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 covers purpose, volume cap, determinism, and the specific triage criteria. With an output schema present, it does not need to explain return values. It lacks explicit error-handling or edge-case notes, but for a deterministic triage tool with this complexity, the description is largely 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 50% (only as_of has a description; items and nested fields do not). The description adds context by referencing 'construction permit or inspection rows' and specific checks like 'missing owner or next action,' which hints at the meaning of fields. However, it does not directly explain the structure of `items` or the format of `as_of`, leaving some ambiguity for the agent.

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 with a specific verb ('Triage') and resource ('construction permit or inspection rows'), enumerating the exact exception categories (stale review, failed/hold status, overdue inspections, expiry risk, missing owner/next action). This distinguishes it from sibling tools focused on utility defects, preflight checks, and receipt verification.

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 a clear usage context by noting 'Deterministic; does not query live jurisdiction systems,' implying it should be used when a deterministic, offline triage is needed. However, it does not explicitly name alternatives or exclusion conditions beyond the live-system caveat, so it stops short of full when/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 include readOnlyHint=true and destructiveHint=false, which already set a safety baseline. The description adds important behavioral context by stating that the 'signed link receipt explicitly records payment_status=not_paid,' clarifying that no actual payment is collected and adding price information.

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 concise sentences, front-loaded with the primary action ('Get the $149 Stripe checkout link...'). Every sentence contributes relevant information without 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 tool with one optional parameter and an output schema, the description covers key facts: price, checkout link, and receipt status. However, it lacks guidance on the property_summary parameter and does not relate this tool to siblings, so it is not fully complete for an agent deciding how to invoke 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?

The input schema has one parameter, property_summary, with 0% schema description coverage. The description does not mention this parameter at all, leaving the agent to guess what should go in it. The parameter name gives a slight hint, but the description adds no semantic value.

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 starts with 'Get the $149 Stripe checkout link for a single-property utility and telecom defect scan,' providing a specific verb, resource, scope, and price. It clearly distinguishes this from siblings like utility_defect_preflight and verify_action_receipt by focusing on purchasing.

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 usage is implied rather than explicit. It says 'Get the... checkout link' but does not mention when to use this tool versus the sibling tools (preflight or verify receipt), nor does it provide any 'when not to use' 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 readOnlyHint=true, so the read-only nature is covered. The description adds behavioral context by naming the linting dimensions (evidence, freshness, external-receipt requirements) and the side effect of returning a signed receipt, which goes beyond the bare 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?

The description is a single sentence, front-loaded with the core action ('Find false-green risk'), contains no filler, and efficiently incorporates both the method (linting claims) and the output (signed receipt).

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?

Because an output schema exists, return-value details are covered. The description captures the tool's purpose and distinctive preflight role. It falls slightly short on explicit relationship to siblings and on clarifying the nested 'manifest' input structure, which is not explained in the schema either.

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 0%, so the description must compensate. It partially does by identifying 'utility audit claims' as the subject and mentioning linting requirements, which gives meaning to the 'claims' array. However, the 'manifest' parameter and nested claim structure remain unexplained, limiting the compensation.

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 'Find false-green risk by linting utility audit claims' – a specific verb and object. It also distinguishes from siblings 'purchase_utility_defect_scan' and 'verify_action_receipt' by positioning this tool as a preflight linting step, not the purchase or verification action.

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 term 'preflight' implies it should be used before the actual scan or purchase, but the description provides no explicit when-to-use or when-not-to-use guidance, nor does it name alternatives. Usage is only implied, not clarified.

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 declare readOnlyHint, idempotentHint, and non-destructive, which match the verify action. Description adds that it verifies against a published public key and specifies Ed25519, providing useful context 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?

Single sentence with 13 words, directly states the action with no superfluous information. Front-loaded 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?

Given low parameter count and existing output schema, the description is acceptable but lacks usage guidelines and detailed parameter semantics. It is adequate but not comprehensive.

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 sole parameter 'receipt' is an object with no schema description (0% coverage). The description implies the receipt contains payload digest and signature, adding some meaning, but does not fully specify the expected structure or any subfields.

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 verb 'verify', the resource 'action receipt', and specifics (Ed25519, payload digest, signature, published public key). It distinguishes from siblings which are about reliability scans.

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?

No guidance on when to use this tool vs alternatives, no prerequisites, and no mention of when not to use. The description lacks contextual usage hints.

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