InstaBids

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description adds only that the answer includes sourceUrl and that trade echoes back as null when omitted, which is modest but real context beyond the annotations; it says nothing about the shape or size of the six items.

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?

Three short sentences, front-loaded with the purpose and followed by the calling rule and a response note. Little waste, though the sourceUrl sentence overlaps with what the output schema already declares.

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-optional-parameter, read-only lookup with both full schema coverage and an output schema, the description covers the calling rule (omit trade) and one return-value expectation (sourceUrl, null trade). Nothing critical is missing, though a hint about what the six items represent would improve agent confidence.

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 the enum values are documented in the schema, so the description only restates the optionality of trade and the null trade in the response. That restatement is mildly useful for output interpretation but adds no new meaning about the enum keys themselves (e.g., what 'ac' or 'pool_repair' preparation entails).

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 names a specific verb and resource ('Get six items to compare in a home-project bid') plus a trade-specific variant, which is concrete enough to distinguish it from siblings like permit_facts or job_status. It does not explicitly compare itself to any sibling, though none of the listed siblings appear to overlap in function.

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 gives clear conditional guidance on the one input ('Omit trade for the general checklist'), so an agent knows how to call it in both modes. However, it never states when to reach for this tool versus how_instabids_works or other informational siblings, leaving selection to inference from the purpose sentence.

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, closed-world behavior, so the safety profile is covered. The description adds genuine value beyond that: it discloses the business policy that all US ZIPs are eligible and that posting triggers contractor bidding, which prevents an agent from treating a 'false' result as a hard block. It does not cover error behavior or what 'guidance' text contains, but that is largely the output schema's job.

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 first two sentences are near-duplicates ('Every US ZIP can post a job' / 'Homeowners anywhere in the US can post a job'), and the final sentence repeats 'five-digit ZIP' twice. Structure is front-loaded with policy rather than with what the tool actually does. It is readable and not bloated to the point of harm, but each sentence does not fully earn 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?

For a one-parameter, read-only lookup with an output schema, the description supplies the key policy context and input format an agent needs to interpret results. Return-value explanation is somewhat redundant given the output schema, but nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must carry the parameter burden, and it does confirm the input is a five-digit ZIP, matching the '^[0-9]{5}$' pattern. But the closing sentence splits the single 'zip' parameter into two apparent operations ('get the answer' and 'list towns'), which muddies rather than clarifies semantics. The format hint is the only real addition over 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 does state the concrete outputs — guidance text, a US-ZIP determination, and nearby town pages — so an agent knows what the tool returns. The core purpose (validating/answering for a ZIP before posting) is inferable but diluted by the opening policy statement 'Every US ZIP can post a job', which reads like marketing rather than a verb+resource definition. No sibling tool is named, though none of the listed siblings clearly overlaps.

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 gating policy ('Every US ZIP can post a job') is useful context that implies this check is not a blocker, and the title's 'before posting' implies the timing. However, the description never explicitly says when to call this versus job_guidance or start_job, and gives no exclusion conditions. Usage is only implied, not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds genuine value beyond that by stating the tool "creates no account and sends no text" and that joining "asks only for your business details" — a privacy and side-effect disclosure the agent cannot get 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?

Two long sentences, and the first is a marketing description of the InstaBids marketplace that does not describe what this tool does. The actionable content — what is returned and what the caller must do with the links — is buried in the second half rather than front-loaded.

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

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

For a zero-parameter read tool with an output schema, the description is nearly complete: it enumerates the returned content (join steps, availability, alias privacy, job-texts status, links) and states the caller's follow-up action. The only gap is that it never scopes itself against the sibling how_instabids_works, leaving overlap unresolved.

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 takes zero parameters, so there is no parameter meaning to convey; the baseline is a 4. The description does note that joining requests only business details, but that refers to the external signup flow, not to any input this tool accepts, so it adds little parameter-level 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 core verb and resource are specific: "Get the contractor join steps, availability, alias privacy, job-texts status and links to join or ask for text alerts." It also distinguishes itself behaviorally from an enrollment action ("this tool creates no account and sends no text"). However, the opening half of the description is a homeowner-facing marketplace pitch rather than a statement of this tool's purpose, which dilutes the clarity.

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 gives clear operating context: "Hand over the links so the contractor signs up and asks for texts themselves." That tells the agent what to do with the output. It does not explicitly name sibling tools such as how_instabids_works as alternatives, so the routing guidance between the two overview-style tools is left to inference.

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 annotations already establish that this is a read-only, idempotent, non-destructive, closed-world tool. The description adds useful domain context about what InstaBids is, but it does not disclose additional behavior such as whether the returned content is static documentation, how current it is, or any rate limits.

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 only two sentences and contains no obvious repetition. The first sentence is somewhat long and marketing-oriented, but it provides context before the second sentence states the covered topics.

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 informational tool with an output schema, the description covers the main content areas but remains somewhat ambiguous about whether it returns static documentation and how it differs from the contractor sibling. It is adequate, but not fully complete for an agent deciding between informational tools.

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 input schema is empty, so the baseline score is 4. There are no parameter meanings for the description to clarify beyond what the schema already shows.

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 names the subject (InstaBids marketplace) and the topics covered (homeowner steps, homeowner cost, contact privacy), so an agent can tell it is an informational tool. It does not explicitly contrast itself with the contractor-focused sibling, which keeps it from a 5.

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?

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'Learn the homeowner steps...' implies an educational purpose, but the description never says when to call this tool instead of job_guidance, how_contractors_join, or other 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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so safety needs no restating. The description goes beyond them by disclosing the fallback behavior for unrecognized trades and by scoping out pricing/budget content, which tells the agent what the response will and will not contain.

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?

Three short sentences, zero filler, with the core capability front-loaded and the fallback and exclusion following as qualifiers. Every sentence carries information an agent would otherwise have to guess.

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 rich annotations, an output schema, and one optional parameter, the definition covers purpose, fallback, and content exclusions adequately. The only mild gap is that 'current intake template' is not explained (versioning or which template is active), which an agent might need in ambiguous cases.

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% and the single optional 'trade' parameter already documents the lowercase-key format and the omit-for-generic default, so baseline is 3. The description adds real meaning beyond that by clarifying that an unrecognized trade value yields the generic template rather than an error.

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?

States a specific verb ('Get') and a concrete resource ('must-have questions and photo asks from the current intake template'), scoped 'for any trade'. It is clearly distinguishable from siblings like bid_checklist or permit_facts, though it never names those siblings explicitly.

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?

Gives clear invocation context: use it to pull intake-template prep questions for a trade, omit the trade for the generic set, and note that unknown trades fall back rather than erroring. It adds one exclusion ('No prices or budget questions'), but offers no explicit comparison to alternatives such as bid_checklist.

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, but the description adds substantial context beyond them: the 7-day handle lifetime, the exact field set returned, and explicit negative guarantees (no bid amounts, contractor names or job text). The 'expired means the one-hour link lapsed before the homeowner opened it' note explains a non-obvious state transition an agent would otherwise misread.

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?

Front-loaded with the when-to-use clause, then the return contract, then the expiry caveat — a sensible order with no filler. Minor redundancy: 'The handle works for 7 days' and 'Read-only' duplicate what the schema and annotations already state.

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 tool this covers everything an agent needs: when to call it, what comes back, what deliberately does not come back, the handle lifetime, and how to recover from the expired state. An output schema exists, so no further return-value detail is required.

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 the schema property already states the handle comes from start_job, is 43 characters, and expires in seven days. The description restates the origin and the 7-day expiry without adding format or validation detail beyond the schema, so the baseline 3 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?

Names a specific verb and resource (check a job's status after start_job returned a statusHandle) and enumerates the exact return fields (stage, bid count, last changed), which lets an agent distinguish it from siblings like start_job or bid_checklist without opening a schema.

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?

Gives an explicit trigger ('Use this after start_job returned a statusHandle') and an explicit recovery path for the failure case: 'Stage expired ... start again with start_job.' The alternative tool and the condition that selects it are both stated, leaving nothing to inference.

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, openWorldHint=false, and idempotent=true, so safety is covered. The description does add genuine value by disclosing that facts are sourced, timestamped with the check date, and that unpublished rules return fallback guidance telling the caller to confirm locally. However, the second sentence describes a job-posting workflow that is not part of this read-only lookup and can mislead an agent about side effects.

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 first sentence is dense and front-loaded with the essential behavior. The second sentence about homeowners posting jobs is off-topic boilerplate that does not earn its place in a permit-lookup definition.

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 two parameters, full schema coverage, an output schema, and rich annotations, the description only needs to add routing and behavior. It covers the unpublished-rule fallback but omits when to prefer it over the other permit/job siblings, leaving a gap for a fairly simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with 'town' documented as a five-digit ZIP or town name and 'trade' constrained to an enum. The description adds nothing about either parameter, so the schema carries the full burden and the baseline 3 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 opens with a specific verb+resource: 'Read sourced local permit facts,' and adds the scope qualifier that each rule carries the date it was checked. That is clearly distinct from siblings like job_status or check_service_area, though no sibling is named explicitly.

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?

There is no statement of when to reach for this tool versus bid_checklist, job_guidance, or check_service_area, nor any precondition such as needing a town or trade. The only guidance is implicit in 'unpublished rules get guidance to ask your bidder,' and the closing sentence about posting a job offers no usage direction for 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?

Annotations only declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=false). The description adds substantial behavior beyond that: the job stays a private draft, nothing reaches a contractor until the homeowner confirms email and sends, and a one-hour link is returned. It also discloses the PII and ZIP-only constraints that govern what may be submitted.

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 critical scoping and privacy rules are front-loaded, which is good, but the text is long and repeats itself ('Nothing reaches a contractor until the homeowner confirms their email and sends it' vs 'Nothing reaches contractors before the homeowner sends the card'). The mid-section question checklist is useful but reads as a run-on.

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 12-parameter mutation tool with an output schema and annotations, the description covers the workflow, privacy constraints and intake procedure thoroughly. The main gap is that idempotentHint=false is never surfaced as a warning about creating duplicate drafts if the tool is called twice.

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 67%, and the description compensates well for the core fields: it explains what belongs in message, that zip is five-digit and street-address-free, that trade is required, and that photos, walk_clip transcripts, timing and must_haves from intake_templates are optional. It does not explain intent_level, intent_confidence, deadline_hard or project_completion_deadline, which rely on the schema text alone.

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?

States a specific verb and resource ('Creates a private draft' job) plus the trigger condition (homeowner wants contractor bids on a US home repair/improvement job) and the return value (a one-hour link). It is clearly distinguishable from siblings like job_status and job_guidance.

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 when-to-use ('when a homeowner wants contractor bids'), explicit when-not ('Do not use for emergencies'), and explicit data exclusions (no names, phones, emails, street addresses, prices). It also prescribes the intake procedure: ask one short question at a time, only for what is missing, and never invent answers.

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