Housecall Pro MCP by usefulapi

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

Annotations supply only destructiveHint=true, so the description must carry the behavioral burden and adds little beyond the REST endpoint. It never says whether the note is append-only or editable, who can see it, what permissions are required, or what happens on failure. The endpoint string is the only extra context.

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 short sentences, action front-loaded, no filler or redundancy. Every token earns 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 simple two-parameter append tool with full schema coverage and no output schema, the description is nearly sufficient. It omits any note about the response or about the job needing to exist, which keeps it just short of 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% (both job_id and content are documented, with minLength constraints), so the schema already does the work. The description adds no format, length, or content-convention guidance beyond it — 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 specific verb and resource: 'Add a text note to a job.' There is no sibling that adds notes, so no differentiation is needed or attempted; the API endpoint line reinforces what the tool does. Clear, but it does nothing to situate itself among the create/list/get family.

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 when-to-use guidance, no preconditions (e.g. job must exist, required permissions), and no mention of alternatives such as updating a job or leaving a line-item comment. The agent must infer all 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?

Annotations already declare destructiveHint=true, so the mutation profile is partly covered. The description adds the API endpoint and the fact that addresses can be created inline, but says nothing about the effect on failure, whether partial records are created, or what the response contains. The additive nature of 'create' alongside destructiveHint=true creates mild tension, but since create is still a write it is not a direct 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 short sentences, front-loaded with the core verb and resource, with no filler. It is efficient, though arguably too terse given a 12-parameter 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?

For a 12-parameter mutation tool with no output schema and no annotations explaining side effects, the description is far too thin. It does not indicate which fields matter, how addresses are structured, or what a caller should expect on success or failure.

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?

Only 33% schema description coverage across 12 parameters, so the schema leaves most fields (email, notes, phone numbers, lead_source, tags, first_name/last_name) undocumented. The description only mentions the addresses parameter's optionality and adds no meaning for the other eleven fields, failing to 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 and resource ('Create a new customer') and notes the optional address sub-objects, so the operation is unambiguous. However, it does not distinguish itself from siblings like housecall_create_customer_address or housecall_update_customer, leaving the agent to infer which create path to use.

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?

No when-to-use or when-not-to-use guidance is given. It never tells the agent to prefer housecall_create_customer_address for adding an address to an existing customer, nor what prerequisites (e.g., required fields or auth) apply before calling.

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 supply destructiveHint=true, so the description carries most of the load. It adds two useful facts beyond the annotations: the prerequisite of an existing customer and the return of an address id. However, it says nothing about validation failures, required-field handling, or why a create is flagged destructive, leaving meaningful behavioral gaps.

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 tightly written sentences plus an endpoint reference; the operation and its purpose are front-loaded with no filler. Every sentence earns 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?

Covers the operation, prerequisite, and return value (valuable since there is no output schema), but with 7 parameters at 29% schema coverage, an agent still lacks guidance on the required address fields. Adequate but with a clear documentation 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 coverage is only 29% (7 params, 6 required, only country and customer_id described) and the description adds no parameter meaning whatsoever. With low coverage, the description was expected to compensate for the five undocumented address fields, and it does not.

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?

Specific verb+resource: 'Add a service address to an existing customer', clearly distinct from sibling create tools like housecall_create_customer and housecall_create_job. It also states the downstream purpose of the created resource (address id for jobs/estimates), so an agent can distinguish it 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?

'An existing customer' states the prerequisite, and the note about using the returned address id 'when creating a job or estimate' tells the agent where this tool fits in a workflow. It stops short of naming exclusions or alternative tools, but the context for use is clear.

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 supply only destructiveHint=true, so the description carries most of the burden. It adds the cents pricing convention and the address_id-vs-address choice, plus the API endpoint, but says nothing about side effects such as notifying the customer, permission requirements, or what happens on duplicate estimate numbers beyond the schema note. Adequate additions, but far from rich.

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 action and payload shape, with no wasted prose. The trailing 'Housecall Pro: POST /estimates' is mildly redundant with the tool name but provides endpoint traceability.

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 with nested objects and no output schema, the description orients the agent on the main payload but never says what the call returns (e.g. the new estimate id) or that a created estimate can be retrieved via housecall_get_estimate. It is workable but leaves a chaining 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?

At 67% schema description coverage, the baseline is 3. The description usefully clarifies unit conventions (cents) and the mutually exclusive address inputs, but several of the 12 parameters (business_unit_id, lead_source, assigned_employee_ids, note, address subfields) remain undocumented in both the schema and the description.

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 ('Create an estimate for a customer') and even describes the internal shape of the payload (options with line items priced in cents), which distinguishes it from sibling create tools like create_job and create_lead. It never explicitly contrasts itself with those siblings, so it falls short of 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?

It gives one useful selection rule ('Give an existing address_id or a new address') and a cross-tool pointer ('job_type_id ... From housecall_list_job_types'), which is real routing guidance. But there is no when-to-use vs create_job/create_lead/create_lead guidance, no prerequisites, and no exclusions, so usage is only implied.

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 destructiveHint=true; the description adds useful conventions (line-item prices are in cents) and the underlying endpoint, but says nothing about permissions, side effects such as customer notifications, or whether the created job is returned. Given the low bar set by a single annotation, this is adequate but not rich.

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 dense, front-loaded sentences; the required inputs and the address-id source come first. The trailing 'Housecall Pro: POST /jobs.' is low-value metadata for an agent choosing a tool, costing it a perfect score.

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 an 11-parameter, nested-object creation tool with no output schema, the description covers the critical onboarding facts: the customer/address prerequisites, where to fetch address ids, and the cents pricing convention. The main omission is the return shape (presumably the new job id needed for follow-up calls like dispatch or line-item listing), which the absent output schema leaves unexplained.

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 55%, so the schema documents many fields (address_id, schedule sub-fields, unit_price/unit_cost in cents, invoice_number uniqueness) while notes, lead_source, and business_unit_id remain undocumented in both places. The description's 'optionally scheduled, assigned, tagged and with line items' only roughly maps the parameter groups and adds little 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?

States a specific verb (Create) and resource (a job) and immediately bounds it: 'for an existing customer at one of their existing addresses.' That scoping distinguishes it from siblings like housecall_create_customer, housecall_create_estimate, and housecall_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?

Gives clear preconditions (existing customer, existing address) and routes the agent to housecall_get_customer to obtain address ids, which is the main upstream dependency. It stops short of stating when NOT to use this tool (e.g., for estimates or leads) or what to do after creation, so it is context-rich but not exhaustive.

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 destructiveHint=true annotation carries the safety profile, and the description adds a useful domain detail ('priced in cents') that is not in the annotations. It does not disclose permissions, validation failures, or side effects of the two customer modes, but the annotation absorbs most of the burden.

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 dense sentences, front-loaded with the core verb/modes and closed with the endpoint. Every clause maps to a parameter group, though the second sentence packs many optional fields into one list.

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 mutation tool with nested objects, no output schema, and 0 required params, the description covers the primary modes and field semantics but says nothing about what the call returns, required fields for the inline customer, or auth needs. Adequate but with clear gaps.

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?

With only 44% schema description coverage, the description compensates well by naming the key inputs (customer_id, customer, address, lead_source, assigned_employee, tags, note, line_items) and adding the 'cents' unit convention. It does not clarify address vs address_id exclusivity, but it adds real meaning 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?

States a specific verb+resource ('Create a lead') and uniquely names the two operating modes: existing customer via customer_id or inline new customer via customer. This clearly separates it from create_customer and create_job, but does not explicitly contrast it with adjacent estimate/lead creation flows.

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 distinguishes the two mutually-exclusive input paths (existing vs inline customer), which is useful selection guidance. However, it never states when to reach for this tool versus siblings like create_customer or create_estimate, so usage 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.

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

Annotations only flag destructiveHint=true; the description goes further and states precisely what is destroyed (the existing dispatch list) and that the supplied list must be complete. That is exactly the behavioral context an agent needs before a destructive write.

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 replace warning before the mechanics; every sentence carries information and 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?

For a two-parameter destructive tool with no output schema, the description plus annotations cover the safety profile, the replacement semantics, and the API mapping — nothing an agent needs to call it correctly is missing.

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, but the description's 'pass everyone who should be on the job' reinforces the full-replacement semantics of employee_ids — a meaning the schema field doesn't spell out quite as explicitly.

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?

Specific verb (set/dispatch) applied to a specific resource (a job's employee dispatch list), with the underlying API operation named. It is clearly distinguishable from siblings like update_job_schedule or create_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?

The description gives the key invocation rule — this REPLACES the current list, so pass everyone — which tells the agent exactly how to call it. It stops short of naming when-not-to-use it or pointing at an alternative sibling.

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, so the safety profile is covered; the description adds value beyond them by disclosing the payload contents, the multi-location behavior of the locations field, and the cost/latency signal ('cheap'). It doesn't mention auth failure modes or rate limits, keeping it at a solid 4 rather than 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?

Front-loads the operation and its return contract, then the usage hint, with no filler. The trailing 'Housecall Pro: GET /company' is endpoint trivia that is only marginally useful for an agent, costing it the top mark.

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 carries the burden of describing returns and does so by enumerating the fields, including the conditional locations array. Complete enough to call correctly; only the absence of any error/empty-response guidance keeps it from a 5.

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 parameter semantics carry a baseline of 4 by rule. The description correctly adds no param prose, and the key-scoping ('this key belongs to') explains implicitly how the target company is determined.

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?

Specific verb+resource ('Fetch the Housecall Pro company this key belongs to') plus an enumeration of exactly what comes back (name, contact details, address, time zone, service-area zip codes, locations). The scope phrase 'this key belongs to' cleanly separates it from sibling getters like housecall_get_customer and housecall_get_job, which take an ID.

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 one concrete use case — 'A cheap way to confirm the key works' — which tells an agent when this is the right call (credential/connectivity validation) rather than one of the list_* tools. It stops short of naming alternatives or stating when not to use it, so it lands just below the explicit-routing bar.

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?

readOnlyHint=true already establishes the safety profile, so the bar is lower. The description adds genuinely useful behavioral context beyond annotations: the response includes the customer's addresses and their ids are the input to downstream job/estimate creation, which is the key thing an agent must know before calling.

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 compact clauses, front-loaded with the action and payload, plus a short API endpoint mapping. Every sentence earns its place with no filler.

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 two-parameter read with full schema coverage and no output schema, the description covers purpose, payload, and downstream use. Minor gaps remain around the expand parameter and not-found behavior, which keeps it from a 5.

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 both customer_id and expand are already documented in the schema, and the description adds only that the id lookup is the entry point. Baseline 3 is appropriate; the description adds no format or syntax detail 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?

States a specific verb and resource ('Fetch a single customer by id') and implicitly separates itself from housecall_list_customers via 'single'. It also names the returned payload (addresses), but never names an alternative sibling explicitly, so it stops short of 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?

Gives a concrete reason to call it: the address ids returned are needed 'to create a job or estimate', which effectively tells the agent when this tool belongs in a workflow. There is no explicit when-not or named alternative (e.g. versus list_customers), so it is not a 5.

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?

readOnlyHint=true already establishes the safe-read profile, so the description's added value is its disclosure of what the response contains (the estimate's options and each option's approval status) plus the underlying API route. It does not cover not-found/error behavior, but it usefully offsets the absence of an output schema.

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 short sentences, front-loaded with the action and return contents. The trailing 'Housecall Pro: GET /estimates/{estimate_id}' is mildly redundant but earns a little place as API-mapping context.

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 carries the burden of describing returns and does so (options and approval statuses). For a simple one-parameter read tool this is nearly complete, with only error behavior left implicit.

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 required estimate_id is already documented in the schema; the description only restates 'by id'. Baseline 3 is appropriate since the schema fully carries parameter semantics.

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 (Fetch) and resource (a single estimate by id), and clarifies it returns the estimate's options and each option's approval status. The word 'single' plus the 'by id' qualifier cleanly separates it from sibling housecall_list_estimates.

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 'by id' framing implies this is the single-record lookup versus the list_estimates sibling, but the description never explicitly says when to use this versus listing or creating estimates. Usage is left to be inferred from the name and schema.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful detail that a rich set of related fields is returned, plus the underlying endpoint (GET /jobs/{id}). It does not cover failure behavior (missing job), pagination/expansion cost, or auth requirements, so it adds moderate value over the 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?

A single dense sentence front-loads the action and resource, then lists returns, with the endpoint appended as a compact reference. No filler or redundancy.

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 correctly compensates by enumerating the returned fields, which is the key thing an agent needs. The gap is the unexplained 'expand' option and no error behavior for an invalid id.

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 explains the job_id implicitly ('by id') but says nothing about the 'expand' parameter — what 'attachments' or 'appointments' do, or their cost — even though that is the only non-obvious input.

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 ('Fetch a single job by id') and enumerates what the payload contains — customer, address, status/timestamps, schedule, employees, notes, totals. This clearly distinguishes it from the sibling housecall_list_jobs and from mutation siblings like housecall_update_job_schedule.

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 by 'by id' — call it when you already have a job_id and need the full record rather than a list. There is no explicit when-not guidance, no mention of the alternative (housecall_list_jobs) for discovery, and no note about what to do when the id is unknown.

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 readOnlyHint=true; the description adds value by enumerating what fields come back (customer, address, lead source, tags, assigned employee, status, pipeline status), which is meaningful since there is no output schema. It does not, however, cover error behavior (e.g. not-found), auth, or rate limits, so it adds some but not rich behavioral context.

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 front-loaded sentences with zero waste: the operation and its return payload come first, followed by the endpoint reference. Every clause earns 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 single-id read with no output schema, the description supplies the return-field inventory an agent would otherwise lack, plus the underlying endpoint. It is close to complete; only error/edge-case behavior is unaddressed, which is a minor gap for a simple getter.

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?

There is a single parameter with 100% schema coverage, so the schema already documents 'lead_id' fully and the description only restates 'by id'. Baseline 3 is appropriate since the description adds no syntax or format detail 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?

States a specific verb (fetch) and resource (a single lead by id), and enumerates the returned facets. This clearly distinguishes it from the sibling list_leads, which returns multiple leads rather than one.

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 phrase 'by id' implies retrieval of a known lead, and the sibling housecall_list_leads provides an implicit alternative, but the description never states when to use this versus that list endpoint or what prerequisite (a valid lead_id) is needed. Usage 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.

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the upstream endpoint mapping (GET /customers), which is mildly useful, but it says nothing about pagination limits, default page size, result caps, or auth scoping — real behavioral traits for a 7-param list endpoint.

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 tight sentences with no wasted wording; the resource and search behavior are front-loaded and the endpoint reference is appended compactly. It is efficient, though the endpoint line is reference detail rather than agent-facing guidance.

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 7-parameter, zero-required list tool with no output schema, the description does not describe the shape of the returned customer list or how to page through it, and gives no default sort/page-size behavior. It is adequate but leaves meaningful gaps for an agent constructing a multi-page query.

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 in the schema. The description restates `q`'s search targets (name, email, mobile, address) without adding syntax or format detail, and it is silent on page, page_size, expand, sort_by and sort_direction. Baseline 3 is appropriate when the schema does the heavy lifting.

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 and resource ('List or search customers') and names the returned fields (phone numbers, tags, addresses), so the agent knows what this returns. It does not explicitly distinguish itself from the sibling housecall_get_customer, so sibling differentiation is only implicit.

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 search use case via `q`, but gives no explicit when-to-use guidance: nothing says to prefer this over housecall_get_customer for a single record, and there is no guidance on paging (page/page_size) or when to use `expand`.

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?

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description usefully narrows the scope to 'active' employees (implying inactive ones are excluded), but says nothing about pagination behavior, rate limits, or how multi-location filtering interacts with company-scoped accounts.

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, front-loaded sentences: what it returns, why to call it, and the underlying endpoint. Nothing is padded or redundant.

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 annotations covering the safety profile and a fully documented schema, the main gap is the absence of an output schema – the description partly compensates by naming the returned fields. Pagination/response-shape behavior is left to the schema, which is acceptable.

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 page, page_size, sort_by, sort_direction and location_ids all documented in the schema, so baseline 3 applies. The description adds no parameter-level detail (e.g., what sort_by accepts) beyond that.

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 (list) and resource (employees) with scope ('active'), and enumerates the returned concepts (role, contact details, permissions). It is clearly distinguishable from the sibling list tools (customers, jobs, estimates, invoices, tags).

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 their ids to assign or dispatch jobs' gives a downstream purpose, which helps an agent see why it would call this. But it does not state when to prefer this over sibling list tools or any prerequisites, so usage is only 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.

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

readOnlyHint=true already establishes the safe-read profile, so the description's main added value is the note that each record carries its customer, address, schedule and options. It says nothing about pagination behavior, default page size, or result caps despite there being page/page_size parameters.

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 short sentences, front-loaded with the purpose and filters, with no padding. The trailing 'Housecall Pro: GET /estimates' is mildly useful for traceability but is the one element that does not help an agent decide or invoke.

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 sketches the return shape (customer, address, schedule, options), which is the main gap it needed to cover. Remaining omissions (pagination defaults, sort defaults) are minor and largely covered by the documented 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 description coverage is 100%, so field meaning is already fully documented in the schema. The description's mention of scheduled window, customer, employees and work status maps onto those params but adds no syntax or format detail beyond them, 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 specific verb and resource ('List estimates') plus the filterable dimensions and the backing endpoint (GET /estimates), which is concrete. It implicitly separates itself from the singular housecall_get_estimate, but never names that sibling, so differentiation is left to inference.

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 filter list implies the retrieval scenarios the tool serves, but there is no explicit when-to-use guidance or an alternative named (e.g., 'use get_estimate for a single estimate'). Usage is inferable rather than 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?

readOnlyHint=true already establishes this as a safe read, so the bar is lowered. The description still adds genuinely useful behavioral context beyond the annotations and schema: the unit convention ('Amounts are in cents') and the underlying endpoint (GET /invoices). It stops short of describing pagination defaults or result ordering, which keeps it from 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 compact sentences plus a short endpoint tag. The core purpose and scope lead, the filter axes and example follow, and the unit caveat is placed last where it belongs. No filler.

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 read-only list tool with full schema coverage and no output schema, the description covers scope, filter axes, units, and the API mapping. It does not describe the shape of a returned invoice record or default paging behavior, a minor gap given the tool's straightforward list semantics.

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 13 parameters including enums and ISO-8601 formats are already documented in the schema. The description restates the filter categories at a higher level and adds one combined-filter example, but contributes no syntax or constraint detail the schema lacks. 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 and resource ('List invoices') plus a scope qualifier ('across the company') and enumerates the filter axes. The company-wide scope implicitly distinguishes it from housecall_list_job_invoices, but it never names that sibling, so the differentiation is inferential rather than explicit.

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 a concrete usage example ('everything open and overdue') and lists the available filter dimensions, which implies when the tool is useful. However it offers no when-not guidance and never mentions housecall_list_job_invoices as the narrower alternative, leaving the agent to infer selection.

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 annotation readOnlyHint=true already declares this as a safe read operation, so the description need not repeat that. The description adds useful field-level detail about what is returned and the underlying endpoint, but it does not disclose auth requirements, pagination behavior, rate limits, or output ordering.

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 compact sentences with no wasted words. The scope and return fields are front-loaded, and the API endpoint is placed at the end as supplementary context.

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 does a good job of listing the fields returned by the tool, which is the main thing an agent needs. Minor omissions such as pagination behavior or result limits prevent a perfect score for a list operation.

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 the single required parameter is already documented by the schema. The description implies that job_id scopes the result to one job, but adds no format, validation, or example beyond what the schema provides, making the baseline 3 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 states a specific verb (List), resource (invoices), and scope (for one job), making it clearly distinct from the company-wide list_invoices sibling. It also previews the returned invoice fields, which confirms the tool's purpose beyond the name alone.

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 phrase 'for one job' gives clear context for when to use this tool rather than a global invoice listing, and the endpoint path reinforces the job-scoped intent. However, it does not explicitly name alternatives such as housecall_list_invoices or state when this tool should be avoided.

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 readOnlyHint=true, so the description carries the rest — and it does disclose the shape of the payload (unit price, cost, quantity, amount in cents), which is meaningful given there is no output schema. It omits pagination/result-limit behavior, keeping it 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, front-loaded with the operation and payload, with zero filler. The trailing API endpoint note (GET /jobs/{job_id}/line_items) is marginally redundant but useful for tracing the underlying call.

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 tool with no output schema, the description supplies enough: scope, returned fields, and units. Only pagination/ordering behavior is absent, a minor gap for a simple list endpoint.

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?

With a single required parameter at 100% schema description coverage, the schema already documents job_id fully; the description only restates it as 'one job'. Baseline 3 is appropriate since there is little room to add meaning.

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 (List) and resource (a job's line items) and enumerates what the items are (services, materials, labor, discounts) plus the fields returned. This clearly separates it from sibling reads such as housecall_list_job_invoices or housecall_get_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?

The phrase 'on one job' implies the tool is used once you have a job_id, giving modest contextual guidance. However, it never names an alternative (e.g., get_job vs. this tool) or states when not to use it, leaving the agent to infer routing.

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?

readOnlyHint=true already establishes the safe-read profile, so the bar is lower. The description usefully adds the return payload contents and the underlying endpoint (GET /jobs), but says nothing about pagination behavior, default page size, or result caps despite page/page_size parameters being present.

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, with the action and its filters front-loaded, then the payload, then the API reference. The "Housecall Pro: GET /jobs" line is borderline redundant but is a compact source-of-truth pointer, so the text earns its place overall.

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 correctly compensates by describing what each returned job carries (customer, address, notes, schedule, employees, totals). For a 13-parameter list tool it is nearly complete, missing only pagination/default-sort behavior.

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 13 parameters are already documented and the baseline is 3. The description's phrase "scheduled window, customer, assigned employees and work status" loosely maps onto those params but adds no format, default, or interaction detail 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?

States a specific verb and resource ("List jobs") and enumerates the filter dimensions plus the payload shape, so an agent immediately knows this is the collection endpoint. It does not explicitly contrast itself with the sibling housecall_get_job, so the list-vs-single distinction is implied by "jobs" rather than stated.

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 filter list implies when to reach for this tool (e.g. filtered retrieval by window, customer, employee, status), but there is no explicit when-to-use guidance and no exclusion such as "use get_job for a single job" or any note about pagination defaults when omitting filters. Usage is inferable but not spelled out.

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?

readOnlyHint=true already declares the safe-read profile, so the description is not burdened with safety disclosure. It adds only the upstream API mapping (GET /job_fields/job_types); nothing about pagination, return shape, or whether the list is complete or truncated.

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 with the purpose front-loaded, then the practical use of the returned id, then the API endpoint mapping. Nothing is padded and each clause carries information.

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-optional-param, read-only list tool with no output schema, the description covers what the tool returns conceptually (job type names/ids) and how to use the id downstream. It stops short of describing the response structure or result 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 description coverage is 100% for the single optional 'name' filter, so the schema fully documents the parameter. The description adds no filtering syntax or behavior beyond the schema, making the baseline 3 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 and resource ('List the company's job types') and concretizes it with examples (Repair, Install, Maintenance). It doesn't explicitly contrast with any sibling, but no sibling lists job types, so the resource itself disambiguates.

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 second sentence tells the agent why this call matters in a workflow: 'Use an id as job_type_id when creating a job or estimate,' which links it to housecall_create_job and housecall_create_estimate. It gives clear context but no explicit when-not or fallback guidance.

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?

readOnlyHint=true already establishes the safe read profile, so the bar is lower. The description adds the API endpoint mapping but says nothing about pagination traversal, result limits, or ordering defaults beyond what the schema enums already 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?

Two short, front-loaded sentences: the core action first, filter scope second, API mapping last. No padding 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 read-only list tool with 10 optional parameters fully documented in the schema and no output schema, the description plus structured fields are nearly sufficient. Only the absence of any hint about the shape/volume of returned lead records keeps it from being fully 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 every parameter including enums is documented in the schema; the baseline of 3 applies. The description restates five of the filter dimensions but adds no syntax, multi-value semantics, or interaction rules 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?

States a specific verb and resource ('List leads') plus the filterable dimensions, and even anchors it to the underlying API call (GET /leads). It is clearly a read-list operation, though it does not explicitly contrast itself with the singular sibling housecall_get_lead.

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 by the name and the enumerated filters, but there is no explicit when-to-use/when-not guidance, no mention of pagination prerequisites, and no routing to the sibling get_lead or list_customers for related lookups.

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?

readOnlyHint=true already declares the safe-read profile, so the bar is lower. The description adds genuine value beyond that by disclosing the cents unit for price/cost and the default-empty nested lists, but says nothing about pagination limits, auth requirements, or result size.

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 dense sentence that front-loads the action and returned fields, followed by a short API endpoint reference. Every clause carries meaning, though the field enumeration makes it slightly long.

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, enumerating the returned fields and the optional nested expansions is exactly what the description should do, and all schema parameters are covered. It stops short of noting pagination or auth behavior for the API-backed call.

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 six parameters (q, page, page_size, expand, sort_by, sort_direction) are already documented in the schema. The description's only added parameter meaning is the cents unit for the monetary fields, which is marginal.

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 ('List or search the price book's services') and enumerates the returned fields (name, task number, price/cost in cents, taxable and online-booking flags). No sibling tool covers the price book, so there is no ambiguity to resolve.

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 'List or search' phrasing plus the optional 'expand' clause implies when to use it (browse or query services, optionally with nested materials/labor rates), but there is no explicit when-not guidance or named alternative among the many list_* 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?

The readOnlyHint annotation already declares this as a safe read operation. The description adds the backing endpoint (GET /tags), which is useful context but reveals nothing about pagination behavior, result ordering defaults, or response shape beyond what the schema hints at.

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 short sentences with the core purpose front-loaded and zero padding. The trailing API-endpoint reference is compact and earns its place as a disambiguating hint, though it is arguably redundant.

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 list tool with full schema coverage and a readOnlyHint annotation, the description is minimally adequate. With no output schema, it does not describe what a returned tag looks like (id, name, timestamps), leaving that gap unaddressed.

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 the four optional parameters (page, page_size, sort_by, sort_direction) are already fully documented in the schema. The description adds no parameter-level meaning, so the baseline of 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 ('List') and resource ('tags') scoped to the company, which distinguishes it from the many sibling tools that operate on customers, jobs, estimates and leads. It does not name a sibling directly, but no other sibling deals with tags, so the resource alone differentiates it.

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 guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. Usage is inferable only from the plain-language verb 'List', which is not explicit guidance.

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 supply only destructiveHint=true, so the description must carry the rest. It adds the valuable partial-update semantics (unmentioned fields are untouched) and the underlying REST verb/path. It does not disclose permissions/auth requirements, whether the operation is reversible, or what happens with an empty body, so it is only partially complete for a mutation.

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 mutation scope before the partial-update rule. The trailing "Housecall Pro: PUT /customers/{customer_id}" is slightly redundant but does anchor the operation to a known API surface, so little is wasted.

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 with no output schema and thin annotations, the description covers fields and the partial-update rule but leaves the return value, failure modes and auth requirements unaddressed. It is workable but not complete for a tool of this size.

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 33%, so the description must compensate, and it does partially by grouping first/last name, the four phone/contact fields, tags, lead source, notes and notifications_enabled into named concepts. It omits company entirely and gives no format expectations (e.g. phone formats, tags replace vs append), so the compensation is incomplete.

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?

Clear specific verb ("Change") plus resource (customer) and an enumeration of the mutable fields (name, contact details, tags, lead source, notes, notification setting). This clearly separates it from get_customer/create_customer. However, it never explicitly routes away from siblings, so it stops short of the top band.

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?

"Only the fields you pass are sent" usefully characterises the partial-update contract, which implies when to use it (targeted edits rather than full replacement). But there is no explicit when-to-use/when-not guidance, no mention that customer_id must already exist, and no pointer to create_customer for new records.

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 flag destructiveHint=true, and the description complements that by disclosing side effects the schema does not: dispatching employees and optionally notifying the customer and/or the pro. It still does not say whether dispatched_employee_ids replaces existing assignments or how scheduling conflicts are handled, so it is strong but not complete.

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, all front-loaded: capability first, exclusion second, endpoint last. No filler, no restating of the title, and each sentence contributes information.

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 mutation tool with no output schema, the description covers the key constraint (multi-day unsupported) and the optional side effects, which is most of what an agent needs. It omits what the call returns and any permission/precondition requirement, which is a minor remaining gap rather than a blocker.

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 every parameter is already documented (start/end time as ISO-8601, arrival window in minutes, notify flags, employee ids). The description names the same fields but adds no format, default, or interaction detail beyond the schema, so the baseline of 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+resource ('Set or change a job's scheduled start/end and arrival window') and even names the underlying API operation (PUT /jobs/{job_id}/schedule), so the agent can tell it apart from create_job, dispatch_job and list_jobs 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 an explicit negative condition ('Jobs with more than one appointment (multi-day) cannot be rescheduled here'), which is genuinely useful routing guidance. It stops short of naming the alternative tool an agent should use for those multi-day jobs, so it is clear context without full when/when-not coverage.

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