Pool service scheduling and lead management for Pool Pro Florida in St. Lucie County, Florida.
Scored across 10 tools
Most tools target clearly distinct actions, but the contact tools (sync_customer_contacts vs upsert_customer_contact) and route tools (sync_route_calendar vs upsert_route_stop_event) form near-pairs that could be confused. The descriptions do a good job distinguishing them as bulk-replacement vs single non-destructive operations, so the ambiguity is manageable.
Every tool follows a clean verb_noun snake_case pattern (book_appointment, create_lead, get_site_map, read_site_page, sync_customer_contacts, upsert_route_stop_event). No mixed conventions or vague verbs appear.
Ten tools is well within the ideal range and each earns its place, covering distinct concerns (booking, leads, availability, site content, contacts, calendar, media). No redundant or filler tools.
The surface covers booking, lead creation, availability lookup, site reading, contact/calendar sync, and media upload, giving a coherent lifecycle for a pool-service business. Minor gaps exist, such as no explicit reschedule/cancel appointment or update-lead operation, but agents can work around them.
Book a confirmed Pool Pro Florida appointment through Cal.com after the customer has selected an available time. Requires customer name, email, service address, and the exact start value returned by get_available_times. A successful booking triggers the existing Cal.com webhook, which creates the lead in Pool Founder.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Customer full name. | |
| Yes | Customer email address. | ||
| notes | No | Optional notes about the pool or requested service. | |
| phone | No | Customer phone number. Normal U.S. formatting is accepted. | |
| start | Yes | Exact ISO 8601 slot start returned by get_available_times. | |
| address | Yes | Pool service address; Cal.com uses this as the attendee address/location. | |
| timeZone | No | IANA time zone. Defaults to America/New_York. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare it is a non-destructive write in an open world; the description adds the key side effect that a successful booking fires the existing Cal.com webhook and creates the lead in Pool Founder. That downstream consequence is not derivable from annotations or schema. It omits idempotency behavior and what happens on failure or double-booking.
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 tight sentences: purpose first, then prerequisites/required inputs, then the downstream effect. No filler and no repetition that isn't load-bearing for invocation.
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 write tool with no output schema, the description covers the trigger condition, required inputs, and the resulting lead creation, which is what an agent most needs. It could still say what the tool returns on success (confirmation id, booked time) to close the remaining gap.
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 all seven parameters are already documented, including the 'start' constraint. The description repeats the four required fields and the exact-start requirement without adding new syntax, format, or default information beyond the schema (timeZone default, phone formatting, notes are all schema-only). 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?
States a specific verb ('Book'), resource ('Pool Pro Florida appointment'), and provider ('through Cal.com'), plus the precondition that the customer has already selected a time. An agent can distinguish this from get_available_times and create_lead without opening any 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?
Explicitly says when to call it ('after the customer has selected an available time') and ties the required 'start' value to the get_available_times output, which is strong context. It stops short of naming create_lead as an alternative or explicitly telling the agent not to call it, though the webhook note implies the lead is created automatically.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a Pool Pro Florida service lead in Pool Founder when a customer is interested in service but is not yet booking an appointment. Do not call this before book_appointment for the same inquiry because a successful Cal.com booking creates the Pool Founder lead through the booking webhook.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Customer full name. | |
| No | Customer email address. | ||
| phone | No | Customer phone number. | |
| address | No | Pool service address. | |
| message | No | Customer request or useful notes. | |
| service | Yes | Requested service, such as Pool Cleaning or Pool Consultation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the key side effect: it writes a lead into Pool Founder, and a duplicate is created if a booking already happened via the webhook. That is a genuinely valuable behavioral hazard. It does not mention permission/auth requirements or what the response contains, so it stops short of a 5.
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, no filler. The positive scope comes first and the critical 'do not call before book_appointment' warning is front-loaded in the second sentence where it will be read.
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 six-parameter mutation tool with no annotations and no output schema, the description covers purpose, correct sequencing, and the duplicate-lead side effect. It omits return-value expectations and permission needs, but those are minor relative to the sequencing guidance it provides.
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% (all six parameters are documented, including examples for 'service'), so the schema already does the heavy lifting. The description adds no formatting, validation, or optionality guidance beyond it, which is the baseline 3 case.
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 ('Create a Pool Pro Florida service lead in Pool Founder') plus the qualifying condition ('customer is interested in service but is not yet booking an appointment'). That condition alone lets an agent distinguish it from book_appointment without opening either 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?
It gives an explicit prohibition ('Do not call this before book_appointment for the same inquiry') and the underlying reason (the Cal.com booking webhook already creates the lead), which is exactly the routing information an agent needs. The alternative tool is named, so there is no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get real Cal.com appointment availability for Pool Pro Florida. Use date-only YYYY-MM-DD values. Use this when a customer wants to schedule a pool consultation or service appointment.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | Last date to check, YYYY-MM-DD. | |
| start | Yes | First date to check, YYYY-MM-DD. | |
| timeZone | No | IANA time zone. Defaults to America/New_York. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the agent knows this is a safe read against an external system. The description adds the 'real Cal.com' qualifier (confirming live external data) but says nothing about return shape, result limits, or empty-result behavior.
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 core purpose. The date-format instruction duplicates the schema pattern, which is a minor redundancy, but nothing is padded.
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?
No output schema exists, so the description should ideally describe what availability comes back (a list of slots, their shape, or how to feed them to book_appointment). That gap leaves the agent guessing about the response, though the input side is fully covered.
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 start, end and timeZone are already documented, and the description's 'Use date-only YYYY-MM-DD values' merely restates the schema pattern. Baseline 3 is appropriate when the schema does all parameter work.
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 ('Get ... appointment availability') scoped to a named business (Pool Pro Florida) and a named source (Cal.com). An agent can immediately distinguish this from book_appointment and create_lead, which are obviously different operations.
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?
'Use this when a customer wants to schedule a pool consultation or service appointment' gives clear triggering context. It stops short of naming the alternative (book_appointment) or stating that this returns options rather than confirming a booking, so the routing is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the current PoolProFlorida.com sitemap index and discover published site pages. Use this to find the correct Pool Pro Florida page before reading current website content. An optional query ranks likely relevant page URLs first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of matching sitemap URLs to return. | |
| query | No | Optional Pool Pro Florida topic, such as weekly service, green pool, service area, pricing, Pool School, or a neighborhood name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, non-destructive, closed-world safety profile. The description adds useful behavior beyond that: it reads a sitemap index, discovers published pages, and notes that an optional query ranks likely relevant page URLs first. It does not discuss rate limits or return details, but the addition is meaningful.
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 three tightly written sentences with no filler. It front-loads the core action and then adds usage context and query behavior in a logical order.
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 discovery tool with full schema parameter coverage, safety annotations, and no output schema, the description is complete. It explains what is read, why to use it, and how the optional query affects ordering.
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 baseline is 3. The description adds semantics for the query parameter by explaining that it 'ranks likely relevant page URLs first,' which is not stated in the schema and clarifies the parameter's effect.
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 states a specific verb and resource: 'Read the current PoolProFlorida.com sitemap index and discover published site pages.' It clearly distinguishes the tool from sibling read_site_page by positioning it as a discovery step before reading page content.
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 usage context: 'Use this to find the correct Pool Pro Florida page before reading current website content.' This implies the natural alternative, read_site_page, but does not explicitly name it or state when-not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the current text of a PoolProFlorida.com page. The page must be present in the current Pool Pro Florida sitemap index. Use this for current published services, pricing, service areas, hours, policies, and page-specific business information.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Exact PoolProFlorida.com URL returned by get_site_map. A site-relative path beginning with / is also accepted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish read-only, non-destructive, closed-world behavior. The description adds that it returns 'current text' and requires the page to be in the sitemap index, but it does not discuss auth, rate limits, caching, or other operational behavior.
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 front-loaded sentences with no wasted wording. The purpose is stated first, followed by the prerequisite and then concrete use cases.
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 one-parameter read tool with full schema coverage and clear annotations, the description is nearly complete: it covers the domain, prerequisite, and content scope. It could still clarify return length or error behavior, but no output schema exists and the essential calling information is present.
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 already documents the url parameter in detail, including the get_site_map origin and site-relative path support. The description adds no further parameter semantics beyond the sitemap-index prerequisite, so the baseline 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?
States a specific verb ('Read') and resource ('current text of a PoolProFlorida.com page'), with a clear domain scope. It also gives the sitemap-index prerequisite, though it does not explicitly name get_site_map as the sibling that supplies valid URLs.
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: current published services, pricing, service areas, hours, policies, and page-specific business information. The prerequisite that the page must be in the current sitemap index is useful, but no explicit when-not-to-use guidance or named alternative is given in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace the private Pool Pro Florida CardDAV address book from one complete Pool Founder active-customer snapshot. Owner-only. Creates and updates stable vCards and removes stale Pool Founder contacts only after the complete snapshot validates.
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot | Yes | ||
| customers | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real context beyond the annotations: the operation is a full replace (not an incremental merge), deletions happen only after the complete snapshot validates, and it is owner-only. That guard condition on destructive behavior is genuinely useful. It stops short of describing reversibility, failure/rollback behavior, or scale limits, so it is not a 5.
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 compact sentences with zero filler, and the core operation (replace the address book) is front-loaded before the auth and safety qualifiers.
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 destructive, annotation-backed mutation with no output schema, the description covers what is replaced, who may call it, and when deletions occur. The main remaining gap is parameter-level guidance for the two required inputs, which the schema does not fill 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%, and the description never names the 'snapshot' or 'customers' parameters directly. It does implicitly constrain them (source must be Pool Founder, snapshot must be complete and represent active customers), but with deeply nested objects and zero field-level documentation it does not fully 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?
States a specific verb (replace/sync) and resource (the private Pool Pro Florida CardDAV address book) with an explicit source (Pool Founder active-customer snapshot). It is clearly distinguishable from the unrelated siblings (book_appointment, create_lead, get_available_times) without opening any 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 clear operating conditions: owner-only, a single complete snapshot as the input contract, and stale-contact removal gated on snapshot validation. It does not name alternative tools or state when not to use it, but the siblings are unrelated so no routing ambiguity exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Synchronize one complete Pool Founder route-date window into the private Pool Pro Florida CalDAV calendar. Each stop is one stable VEVENT. Completed events are historical records and are never removed. Missing non-completed events inside a validated complete window are retained and marked cancelled instead of deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| events | Yes | ||
| snapshot | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: each stop maps to one stable VEVENT, completed events are never removed, and missing non-completed events are retained and marked cancelled rather than deleted. This precisely explains the non-destructive guarantee consistent with destructiveHint=false and readOnlyHint=false, far exceeding what the annotations alone convey.
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 tight sentences, front-loaded with the synchronization target and followed immediately by the retention/cancellation rules. No filler or repetition.
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 mutating tool with nested objects and no output schema, the description covers the critical semantics (stable identity, non-destructive handling of missing/completed events). It omits auth/permission requirements and any indication of the returned result counts, which would round it out.
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?
Top-level parameters (events, snapshot) carry no schema descriptions, so the description must compensate, and it does explain the window/stop semantics conceptually. However it never documents the required snapshot fields or the per-event fields, leaving the meaning of 'complete'/'validated' to be inferred from the nested 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?
States a specific verb (Synchronize) and precise resource/scope (one complete Pool Founder route-date window into the Pool Pro Florida CalDAV calendar). This clearly distinguishes it from the single-stop sibling upsert_route_stop_event, though it never names that sibling 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?
Usage is implied rather than stated: the tool is for a full validated window, and the 'validated complete window' phrasing hints the caller must not use it for partial data. There is no explicit when-to-use vs. upsert_route_stop_event guidance or stated preconditions for authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import an image attached in ChatGPT into the Pool Pro Florida CMS media library. ChatGPT supplies a temporary download URL and file ID through its native file parameter handoff. The server downloads the image directly, validates it, strips embedded metadata by re-encoding to WebP, stores it outside Git, and returns a stable /media/... URL. This tool does not modify any page.
| Name | Required | Description | Default |
|---|---|---|---|
| alt | No | Accessible alt text for the image. | |
| file | Yes | ||
| tags | No | Optional media tags such as hero, riverview, or generated. | |
| source | No | Whether the image came from image generation or a user upload. | |
| caption | No | Optional media-library caption. | |
| filename | No | Optional override filename. If omitted, the filename supplied by ChatGPT is used. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide the generic readOnly/destructive/openWorld flags; the description adds real substance beyond them by disclosing the server-side pipeline: direct download, validation, metadata stripping via re-encoding to WebP, storage outside Git, and a returned stable /media/... URL. It stops short of covering failure modes, size limits, or auth requirements, so it is not exhaustive.
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 purpose, then the mechanics in one dense but information-bearing sentence, closing with a scope constraint. Four sentences with essentially no filler, though the middle sentence is packed enough to be slightly heavy.
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 no output schema, the description usefully explains that the tool returns a stable /media/... URL, and with 6 parameters and a nested file object it explains how that nested input arrives. It omits error behavior, limits, and what validation actually accepts, but is adequate 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 83%, so the schema already documents alt, tags, source, caption, filename, and the nested file fields. The description only reinforces the file handoff concept (temporary download URL + file ID) and adds no new meaning for the other parameters, 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?
States a concrete verb and resource ('Import an image ... into the Pool Pro Florida CMS media library') plus the source of the input (an image attached in ChatGPT via its native file handoff). No sibling tool touches media, and the description makes that domain obvious without opening the 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?
It clearly signals the triggering situation: an image attached in ChatGPT that needs to land in the CMS, with the file arriving through the native file parameter handoff. It also clarifies the boundary 'This tool does not modify any page,' but gives no explicit exclusions or alternative tools, so it stops short of full when/when-not routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update one private Pool Pro Florida CardDAV contact from Pool Founder. Owner-only and non-destructive: this tool never removes any other contacts.
| Name | Required | Description | Default |
|---|---|---|---|
| customer | Yes | ||
| generatedAt | Yes | ISO 8601 generation time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false; the description goes further by stating the owner-only authorization requirement and guaranteeing that no other contacts are removed. What it omits is merge semantics on update (partial vs full replacement, and the matching key), which matters for an upsert.
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?
A single tight sentence that front-loads the operation and resource before the safety qualifier. No padding, though it is arguably too terse for a nested-payload tool.
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?
Safety, authorization, and scope are covered, but for a tool with no output schema and a complex nested input the description never explains what an upsert does on conflict or what is returned. Adequate but with a real gap for the calling agent.
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 only 50% and the payload is deeply nested (customer, phones, emails, locations). The description adds nothing about the customer object or which field drives the upsert match, so it fails to compensate for the undocumented half of 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 states a specific verb pair (create or update, i.e. upsert) against a concrete resource (private Pool Pro Florida CardDAV contact) and scopes it to one record. That singles it out from the bulk sibling sync_customer_contacts without naming it 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?
The 'one ... contact' phrasing implies single-record use versus the bulk sync_customer_contacts, and 'Owner-only' establishes a prerequisite. But there is no explicit when-to-use/when-not statement or named alternative, so routing 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.
Create or update one private Pool Pro Florida CalDAV VEVENT from a Pool Founder route stop. The identity is jobId plus serviceDate, so planned timing can later be replaced by actual arrival and departure without duplication. Owner-only and non-destructive.
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | ||
| generatedAt | Yes | ISO 8601 generation time. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so 'non-destructive' largely restates structured data. The description does add genuine context the annotations can't convey: the caller must be the owner, and the jobId+serviceDate identity means re-invocation updates rather than duplicates. It still says nothing about what happens on conflict, calendar targeting, or failure handling.
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, front-loaded with the action and resource, then the identity semantics. No filler and nothing buried.
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 no output schema and a nested input object, the description covers the essentials: what is produced, who may call it, and why repeated calls are safe. It stops short of describing the target calendar or error behavior, but the core invocation picture 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 description coverage is only 50%, so the description carries some compensating burden, and it does document the key composite identity (jobId plus serviceDate) that drives the upsert. But the nested event object's other required fields (status, timingSource, stopIndex bounds) get no explanation in the description, leaving the gap only partly filled.
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 pair (create or update) and a concrete resource (a private CalDAV VEVENT derived from a Pool Founder route stop), with the source and target systems named. An agent can distinguish it from sync_route_calendar or book_appointment without opening the 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?
It implies when this tool applies by explaining the upsert identity (jobId + serviceDate) and the planned-to-actual transition, and states the 'Owner-only' precondition. However, it never names an alternative or an exclusion condition, so the agent must infer when to prefer this over sync_route_calendar, which sits right beside it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
upload_mediaget_site_mapread_site_pagesync_route_calendar3 fields changedInput schema / properties / events / items / properties / address / descriptionAdded value: +"Service address. Written to LOCATION so mobile calendars can open Maps."Input schema / properties / events / items / properties / emailAdded value: +{
+ "description": "Optional structured customer email from Pool Founder. Included in event notes for tap-to-email on mobile calendars.",
+ "format": "email",
+ "type": "string"
+}Input schema / properties / events / items / properties / phoneAdded value: +{
+ "description": "Optional structured customer phone number from Pool Founder. Included in event notes for tap-to-call on mobile calendars.",
+ "type": "string"
+}upsert_route_stop_event3 fields changedInput schema / properties / event / properties / address / descriptionAdded value: +"Service address. Written to LOCATION so mobile calendars can open Maps."Input schema / properties / event / properties / emailAdded value: +{
+ "description": "Optional structured customer email from Pool Founder. Included in event notes for tap-to-email on mobile calendars.",
+ "format": "email",
+ "type": "string"
+}Input schema / properties / event / properties / phoneAdded value: +{
+ "description": "Optional structured customer phone number from Pool Founder. Included in event notes for tap-to-call on mobile calendars.",
+ "type": "string"
+}sync_route_calendarupsert_route_stop_eventupsert_customer_contactsync_customer_contactsbook_appointmentcreate_leadget_available_timesManage Housecall Pro customers, jobs, estimates and leads; schedule and dispatch jobs.
Book pool service in Austin, TX: prices, service area by ZIP, free callback from a local pro.
Book pool service in Las Vegas, NV: prices, service area by ZIP, free callback from a local pro.
Manage pest control operations — customers, scheduling, SMS, payments, and reporting.
Add one secure layer between your agents and this server.
