Ironclad Verified

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

Discloses read-only nature, no personal data returned, and lists exactly what fields are provided, adding value 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 but packs substantial information; slightly dense but front-loaded and 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?

For a simple read-only tool with one parameter, the description covers all return values fully, compensating for lack of output schema.

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 already fully describes the parameter; description adds no further meaning about the withdrawRef itself beyond context of what the tool returns.

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 reads a request's status by withdrawRef and enumerates possible statuses, distinguishing it from mutation tools like request_contractor or complete_job.

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?

Implies using it to check request status after creation or update, but does not explicitly state when not to use or compare to siblings like withdraw_request or reroute_request.

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?

Adds value beyond annotations by explaining the idempotent behavior (re-calling returns same URL), the 'single-use' nature of the review URL, and the homeowner's attestation. No contradictions 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 with front-loaded purpose, followed by idempotency and usage caution. Every sentence adds essential information with 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?

The description covers the core action, idempotency, return value (URL), and the attestation context. It is complete for a tool with one parameter and no output schema.

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 single parameter `withdrawRef` is fully described in the schema (100% coverage). The description does not add extra detail about the parameter, but the schema is sufficient.

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 explicitly states the tool's verb (marks complete), resource (contractor's record), and outcome (returns single-use review URL). It distinguishes from sibling tools like request_contractor or check_request by focusing on job completion.

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 clear usage context: call only when user confirms work is done. The idempotency note reassures safe re-calling. Does not explicitly mention alternatives, but the sibling list makes them obvious.

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 readOnlyHint=true, so the read-only nature is clear. The description adds value by disclosing that reviews are never removed even if negative, and that the response includes links to profile and verified record. This provides context beyond the read-only flag.

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 purpose ('full public record for one contractor by slug') and then lists contents. Every part adds information, though it could be slightly more concise by omitting the parenthetical about reviews.

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 output schema, the description provides a good sense of what is returned. It mentions key fields, reviews policy, and links. It does not cover authentication or rate limits, but annotations cover read-only. The schema references search_contractors for slug origin, which is adequate context.

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% (slug is documented with a description). The description mentions 'by slug' but does not add new meaning beyond the schema's description. Baseline score 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 returns the full public record for one contractor by slug, listing specific fields (Ironclad Score, tier, rating, confirmed-job count, all reviews, links). This distinguishes it from siblings like search_contractors (which searches) and other mutation 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 implies the tool is used when you need the full record for a specific contractor, but it does not explicitly state when to use it versus alternatives (e.g., when to search first, or that reviews are always included). No exclusions or alternative tool references are given.

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 behavioral traits beyond annotations: it explains the retry-safe idempotency (24h dedup), the creation of a withdrawRef as a kill switch and status key, and the requirement for explicit homeowner approval. No contradiction with annotations (idempotentHint=true is consistent).

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 and well-structured: purpose first, then prerequisites, then retry behavior, then a critical action item. Every sentence serves a purpose with no waste.

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 there is no output schema, the description compensates by telling the agent to save the withdrawRef. It covers prerequisites, retry behavior, and optional parameters. It is remarkably complete for a submission 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%, so the description doesn't need to redundantly document parameters. However, it adds value by emphasizing the critical nature of homeowner_approved and the need for real name/phone. This context enhances understanding beyond the schema.

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 files the homeowner's request with ONE contractor, using a specific verb and resource. It distinguishes from sibling tools like check_request and withdraw_request by emphasizing that it sends the request to a single chosen contractor.

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

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

The description explicitly says when to use (after user explicitly approves with real name and phone) and requires homeowner_approved=true. It also explains the retry-safe behavior. However, it does not explicitly mention when not to use or provide direct alternatives to siblings.

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 (all false), the description discloses critical behavioral traits: it closes the quiet contractor's request, that contractor 'can never earn that job's completion or review', and it returns a new withdrawRef that should replace the stored one. This adds significant value over 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 structured with key details front-loaded: what, when, how. It is efficient with only three sentences, each adding necessary context without redundancy. A slight deduction for length, but it's justified by the complexity.

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 single parameter, no output schema, and sparse annotations, the description adequately covers preconditions, side effects, return value usage, and restrictions (3 contractors max). It leaves no obvious gaps for an agent to misuse 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?

The schema already describes withdrawRef as 'The withdrawRef returned by request_contractor' with 100% coverage. The description enhances this by explaining that the call returns a NEW withdrawRef and instructs to replace the stored one, providing practical usage guidance beyond schema.

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 a clear verb-resource pair ('Move a ghosted request') and specifies the exact condition ('when check_request shows the contractor declined or stayed silent past 24 hours'). It explains the action of offering to the next contractor, with constraints like '3 contractors max', differentiating it from sibling tools like request_contractor or withdraw_request.

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

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

The description explicitly states when to use the tool (after check_request indicates decline or 24-hour silence) and warns 'Only call with your user's go-ahead'. It implies the when-not-to by indicating the previous contractor's request is closed, but does not name alternative tools; however, the context is clear enough.

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 the tool as read-only. The description adds behavioral details: score-ranked results, Ironclad Score can be null (explained as honesty, not error), and empty list means no verified contractor. This adds 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?

The description is concise, front-loaded with the core purpose, and every sentence provides essential information without redundancy. Ideal length for an agent.

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 simple tool (2 params, no output schema), the description sufficiently covers return values (slug, score, rating, reviews) and edge cases (null score, empty list). It is 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% with descriptions for both parameters. The description adds that trade accepts consumer language and region is ZIP or city, augmenting the schema with real-world usage hints.

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 'Score-ranked contractor search' with a specific verb and resource. It also mentions the slug for use with sibling tools get_contractor and request_contractor, distinguishing it from retrieval and mutation 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 explains when to use (search by trade and region) and how the trade parameter accepts consumer language, but does not explicitly state when not to use this tool. However, it implies alternatives through the result context.

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

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

The description adds significant context beyond annotations: it explains the consequence ('contractor loses access and contact stops') and labels it a 'kill switch.' Annotations already indicate idempotentHint=true and destructiveHint=false, and the description aligns without 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 concise sentences: first defines the tool's nature, second states when to use. No wasted words; every sentence serves a 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?

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral impact. Annotations provide additional safety signals, making this 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 100%, so baseline is 3. The description adds value by clarifying that 'withdrawRef' is the reference returned by 'request_contractor', which helps the agent understand provenance.

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 action ('withdraws the request') and the resource ('request identified by withdrawRef'), and the phrase 'kill switch' provides a vivid purpose. It distinguishes from siblings like 'check_request' and 'complete_job' by focusing on withdrawal and stopping contact.

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 states when to use: 'Use when your user changes their mind.' It provides clear context, though it does not explicitly mention when not to use or alternatives. The sibling list is available for contrast.

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