InstaBids

Next draft question

ask_next

fill what you can; everything else can come later. Start with the homeowner’s description, trade and ZIP, plus a photo or a good description. Optional: photos, a description or transcript of a 20–60 s walk clip, timing and the job type’s must-haves from intake_templates. Never invent answers. ZIP only; never send a street address or a price. Nothing reaches contractors before the homeowner sends the card. Continue this private draft with draftHandle. Supply message, fixes, or both to answer_intake. Use the new draftHandle returned each time; the old handle expires immediately. Send only the homeowner actual reply; never answer for them. If a call fails, do not guess; ask the homeowner again. Nothing is sent to contractors. Continue with the returned question until readiness.canSend or readiness.homeownerActionRequired is true, then show sendUrl to the homeowner. The homeowner completes their insurance answer and send confirmation on that sheet; never claim the job was sent. Never invent answers. For a new job, call start_job before answer_intake, then prepare_publish after the intake is ready; for other writes, read the previous reply before calling and follow the returned next step afterward, using only tools listed by this server. Only the homeowner tap sends anything to contractors. If anyone asks, say you are an AI assistant.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "draftHandle": "<draftHandle>"
    },
    "name": "ask_next"
  }
}

Input Schema

Name	Required	Description
`trade`	No	Job trade; generic home repair is allowed.
`photoUrls`	No	Optional photos; attachment still requires the existing scan and photo permissions.
`quotes_by`	No	ISO date, or null for no deadline; never a price.
`walk_clip`	No	Description or transcript of a 20–60 s walk clip. This tool does not upload video bytes or fetch video URLs.
`must_haves`	No	Known answers to this job type’s intake_templates must-haves; unknown answers can come later.
`draftHandle`	Yes
`intent_level`	No	10 emergency; 8 soon; 6 planned; 4 if the price is right; 2 someday. Use only evidence from the homeowner.
`deadline_hard`	No
`deadline_reason`	No	Optional reason for the date, without names or contact details.
`intent_confidence`	No
`project_completion_deadline`	No	ISO date, or null for no deadline; never a price.

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 11, 2026

TDQS

B3.1/5.0

Behavior4/5

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

Beyond the annotations (non-idempotent, non-read-only, closed-world), the description discloses meaningful behavior: the returned draftHandle rotates and the old handle 'expires immediately', nothing reaches contractors until the homeowner taps send, failures should be surfaced rather than guessed at, and readiness.canSend / readiness.homeownerActionRequired / sendUrl govern the loop. This is substantive context not present in the structured fields, though some of it belongs to neighboring tools.

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

Conciseness2/5

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

A single dense ~250-word block mixes this tool's behavior with onboarding instructions for start_job, answer_intake and prepare_publish, and repeats 'Never invent answers' verbatim twice. The genuinely tool-specific content (draftHandle rotation, readiness flags, sendUrl handoff) is buried mid-paragraph rather than front-loaded.

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

Completeness3/5

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

With no output schema and 11 parameters, the description does the necessary work by naming the return signals (new draftHandle, question, readiness flags, sendUrl). However, it never describes the shape of the returned question or what a 'fixes' payload is, and it spends capacity on sibling-tool workflow instead of this call's input/output contract.

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

Parameters3/5

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

At 73% schema coverage the schema documents trade, photos, walk_clip, must_haves, timing and intent_level well, so the description's main additions are priority ordering ('start with the homeowner's description, trade and ZIP, plus a photo') and provenance rules ('never invent answers', 'ZIP only; never send a street address or a price'). These add value but also introduce confusion: it references a ZIP field that is absent from the schema and discusses message/fixes parameters that this tool does not have.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The title and the phrase 'Continue with the returned question until readiness.canSend...' imply this tool advances a draft intake and returns the next question, but the description never states that outright. The opening sentences ('fill what you can... start with the homeowner's description, trade and ZIP') describe field entry, not this tool's operation, and it even points at 'answer_intake' for supplying message/fixes. An agent must infer the verb+resource from scattered clauses.

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

Usage Guidelines3/5

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

There is real sequencing guidance ('For a new job, call start_job before answer_intake, then prepare_publish after the intake is ready') and a loop-termination rule tied to readiness flags. But the guidance is entangled with instructions for sibling tools and never cleanly says 'call ask_next to get the next draft question' versus when to call answer_intake. Alternatives are named but their division of labor is left implicit.

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

All InstaBids tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?