Skip to main content
Glama

Tallyho

Book a plumber

book
Idempotent

Book a plumber from a find (business_id + find_id). Version 1 is a handoff: Tallyho records the request and returns the plumber's phone number and the questions to ask; nothing is booked until the user calls, so booked is false. Don't send the user's contact details on a handoff; they are never stored either way. Keep the booking_id and call report after the call to the plumber, and again after the job.

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": {
      "business_id": "<business_id>"
    },
    "name": "book"
  }
}

Input Schema

NameRequiredDescriptionDefault
jobNoRequired when there is no find_id; otherwise the search's job is used.
testNoDefaults to the search's environment.
channelNoDefault: the best available. Version 1 offers only handoff.
contactNoThe user's details for the business. Never stored; unused on a handoff.
find_idNoThe search this business came from. Required unless `job` is given.
promisesNo
business_idYes
principal_refNoAny stable id for the user; only a salted hash is kept.
principal_nameNoOn a Tallyho call: the first name the call uses ("calling for Jordan"). Spoken, never stored. Without it, "the property owner".
idempotency_keyNo
previous_booking_idNoThe booking this one follows, e.g. after a counter-offer.

Output Schema

NameRequiredDescriptionDefault
jobYes
callNo
bookedYes
statusYes
channelYes
handoffYes
billableYes
businessYes
booking_idYes
environmentYes
contact_usedYes
report_afterYes
check_after_sNo
contract_versionYes
promises_in_scopeYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds what those annotations cannot: nothing is actually booked until the user calls the plumber, the response is the phone number plus questions to ask, and 'booked' returns false. It also discloses two privacy/retention rules (don't send contact details on a handoff; contact details are never stored) and a post-call step (keep booking_id and call report), which materially change how an agent should behave.

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

Conciseness4/5

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

Four sentences, front-loaded with the one fact that changes everything (this is a handoff, not a booking), and each remaining sentence carries a distinct rule. Slightly dense with the privacy rules and the call-report instruction stacked in the tail, but every sentence earns its place.

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

Completeness4/5

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

For an 11-parameter mutation tool with nested objects and an output schema, the description covers the key non-obvious behavior: it writes only a request, returns a phone number and questions, and yields booked=false. Return details are correctly left to the output schema. It could do slightly more on the non-handoff channels and on what happens to an idempotency key on retry, but nothing essential is missing.

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?

Schema coverage is 73%, so the schema already carries most parameter meaning, and 3 is the baseline. The description adds only the business_id/find_id relationship (a find is the source of the booking) and the rule that contact details are unused on a handoff; it says nothing about job, urgency, promises, price ceilings, or previous_booking_id, which the schema must explain alone.

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

Purpose5/5

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

The definition names a specific verb and resource ('Book a plumber') and immediately scopes the inputs ('from a find (business_id + find_id)'). The follow-up sentence rewrites the mental model by stating that version 1 is a handoff and that 'booked is false' — an agent cannot mistake this for a confirmed reservation, and it is clearly distinct from find/report/status.

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?

Usage is only implied: the parenthetical '(business_id + find_id)' hints that a prior find is the source, and 'Version 1 is a handoff' tells the agent what the tool will actually do. There is no explicit statement of when to call this instead of find, report, or status, and no stated prerequisites or exclusions for the non-handoff channels that exist in the schema.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources