housecall-pro

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

The annotation set only declares destructiveHint=true, so the description carries the remaining burden. It reveals the operation is a POST (a write), which is consistent with the annotation, but says nothing about whether the note is customer-visible, whether it notifies anyone, whether it can be edited/deleted, or what permissions are required.

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, purpose front-loaded, nothing redundant. The trailing 'Housecall Pro: POST /jobs/{job_id}/notes' is mildly useful for API-level traceability but is closer to filler than essential behavior.

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 write tool with no output schema this is nearly adequate, but a mutation flagged destructiveHint=true warrants at least a word on side effects or reversibility that is absent here.

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?

Both parameters (job_id, content) are fully documented in the schema at 100% coverage, so the schema does the heavy lifting. The description adds no format, length, or tagging semantics beyond what the schema already provides, which is the baseline 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 states a specific verb and resource ('Add a text note to a job'), and no sibling tool touches job notes, so it is trivially distinguishable from the create/get/list/update family. An agent knows exactly what this does.

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 framing, no when-not-to-use, and no named alternative. Usage is only implied by the name and the single sentence; nothing helps the agent decide between this and, say, updating a job's fields.

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 provide destructiveHint=true, which already signals a state-mutating operation. The description adds nothing about required fields, authentication, side effects, or what happens to the embedded addresses, so it does little beyond the structured data.

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 action and scoping constraint, plus the API endpoint reference. Nothing 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 creation tool with no output schema and sparse schema coverage, the description omits which fields matter, whether any are required, and what the tool returns. An agent cannot reliably populate this call from the definition alone.

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 12 parameters and only 33% schema description coverage, the description is expected to compensate, but it only references the addresses parameter. The name, contact, notes, tags, and notification fields are left 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?

The description states a specific verb and resource ('Create a new customer') and clarifies scope by noting addresses are optional and embedded. It does not explicitly distinguish itself from the sibling housecall_create_customer_address or update_customer, 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?

There is no guidance on when to use this tool versus alternatives such as housecall_create_customer_address, housecall_update_customer, or housecall_create_lead. The optional-addresses note implies usage but no explicit conditions or exclusions are given.

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 only annotation is destructiveHint=true, which is itself counterintuitive for an address-creation operation, and the description neither explains nor reconciles it. It does add useful post-condition info (returns the address id for downstream job/estimate creation) that no output schema provides, plus the raw endpoint, but omits auth/permission and failure 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?

Two tight sentences, front-loaded with the action and followed by the return-value purpose. The trailing endpoint path is slightly gratuitous but not wasteful.

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?

Return semantics are covered (no output schema exists), but with 7 parameters at 29% schema coverage and a mutation-implying annotation, the description leaves field-level requirements and the destructiveHint meaning 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 only 29% across 7 parameters, and the description supplies no parameter-level detail beyond implying customer_id refers to an existing customer. It fails to compensate for the undocumented fields like street/zip/state or the optional street_line_2.

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 ('Add') and resource ('service address to an existing customer'), and names the underlying Housecall Pro endpoint. It is clearly distinguishable from siblings like housecall_create_customer or housecall_update_customer.

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?

Establishes context: the customer must already exist, and the returned address id is what you feed into job/estimate creation. No explicit alternatives or exclusions are given, but the use context 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?

The annotation already declares destructiveHint=true, so the write/mutation profile is covered. The description adds the API endpoint (POST /estimates) and confirms pricing units, but does not disclose side effects such as whether the customer is notified, what the created estimate state is, or auth/permission requirements.

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 core action, then address handling, then the API reference. The final 'Housecall Pro: POST /estimates.' line is largely metadata but cheap; 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 12-parameter, nested-object tool with no output schema and a destructive hint, the description conveys the essential conceptual model (customer -> options -> line items) but omits scheduling, notification behavior, and most optional-parameter meaning. Adequate but with clear gaps given the tool's complexity.

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

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

Schema coverage is 67%, below the 80% threshold, so the description must compensate. It clarifies the address_id-versus-new-address choice and the cents pricing convention, but says nothing about the many other params (schedule, notify_customer, lead_source, business_unit_id, assigned_employee_ids), leaving the gaps unfilled.

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 an estimate for a customer') and adds concrete domain detail (options like Good/Better/Best, line items priced in cents) that clearly separates it from create_job or create_lead. It stops short of naming any sibling as an alternative, so sibling differentiation is implied by the resource 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 only guidance offered is parameter-level ('Give an existing address_id or a new address'), not tool-selection guidance. It never says when to use create_estimate versus create_job, create_lead, or create_customer, nor any prerequisites for creating an estimate.

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 destructiveHint=true so the write nature is already flagged, and the description adds the concrete endpoint (POST /jobs) and the cents convention. It does not disclose any post-creation side effects, permission requirements, or validation behavior such as invoice_number uniqueness unless supplied.

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 with the mandatory preconditions and the dependency lookup front-loaded, followed by the endpoint. 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 an 11-parameter nested mutation with no output schema, the description covers the essentials an agent needs before calling: required ids, where to get the address id, and units. It omits what comes back (presumably a job id) and how to proceed afterwards, which limits it slightly.

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 55%, but the description only loosely summarizes the optional surface ('optionally scheduled, assigned, tagged and with line items') and repeats the cents convention already documented on unit_cost/unit_price. It does not clarify ambiguous fields like lead_source, business_unit_id, or anytime_start_date.

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 job') plus hard scope constraints: the customer and address must already exist. That implicitly separates it from housecall_create_customer, housecall_create_estimate and housecall_create_lead, though no sibling is named explicitly.

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

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

Gives a clear precondition (existing customer, existing address) and routes the agent to housecall_get_customer for address ids, which is genuine when/how-to-use guidance. It stops short of stating when NOT to use it (e.g. estimates vs jobs, dispatch) or what the alternatives are.

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 already flags this as a mutating operation, so the bar is lower, and the description usefully adds that line items are priced in cents. It does not disclose auth requirements, required fields, what happens if neither customer nor customer_id is supplied, or what the response contains.

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, front-loaded with the core action and the either/or customer mode, followed by optional fields and the API endpoint. Every clause carries information, though the endpoint reference is largely 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 9 params, nested objects, no required fields and no output schema, the description covers the shape of the call adequately but omits validation rules (e.g., what happens with neither customer form), permissions, and any sense of the returned lead. Adequate, not 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 coverage is only 44%, so the description must compensate. It enumerates most top-level params (address, lead source, assigned employee, tags, note, line items) and clarifies the cents unit, but the nested customer and line-item fields remain undocumented in both places, leaving gaps it does not close.

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 ("Create a lead") and maps it to the underlying operation ("POST /leads"), and it splits the two supported creation modes (existing customer via customer_id vs. inline new customer). It does not explicitly differentiate itself from siblings like create_customer or create_estimate, 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?

It clarifies the internal either/or choice between customer_id and customer, which is useful, but it never states when to create a lead rather than a customer or a job, nor any prerequisites. Usage context 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 declare destructiveHint=true, and the description adds the crucial specifics: it REPLACES the current dispatch list, so omitted employees are removed. This explains exactly what gets destroyed, which is more than the annotation conveys on its own.

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 plus an API reference; the destructive replacement warning is front-loaded and 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?

For a two-parameter mutation with no output schema, the description covers purpose, the destructive semantics, and the required payload convention — 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. The description still adds value by clarifying that employee_ids must be the complete list rather than an incremental addition, sharpening the semantics of the array beyond the schema's 'Every employee who should be dispatched.'

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 ('Set which employees a job is dispatched to') and even names the underlying API operation. No sibling tool covers dispatch, so the agent can distinguish it immediately.

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 clear usage context by instructing 'pass everyone who should be on the job', which tells the agent how to prepare the call. It does not name alternative tools or explicit when-not-to-use conditions, but none of the siblings overlap this function.

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 declare readOnlyHint=true, and the description reinforces this with a non-destructive, key-scoped read ('the company this key belongs to') plus a cost signal ('cheap'). With no output schema, its enumeration of return fields and the multi-location caveat adds genuine behavioral value.

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 core action and resource, followed by a short usage note and the endpoint reference. Slightly dense with a mildly awkward '(multi-location) its locations' clause, but every sentence 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 zero-param read with no output schema and readOnlyHint already set, the description covers enough: it names the return fields, notes key scoping, and flags multi-location behavior. Only the exact response structure remains unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to document and the baseline is 4. It correctly adds no spurious parameter discussion.

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 (the company this key belongs to) and enumerates the returned fields (name, contact details, address, time zone, zip codes, locations). No sibling tool targets the company resource, so an agent can route to it unambiguously.

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 an explicit use case: 'A cheap way to confirm the key works.' That gives clear context for when to reach for it, but offers no when-not guidance or named alternatives (none exist among siblings, which slightly softens the gap).

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's job is lighter. It adds real value beyond the annotation by disclosing that the response embeds the customer's addresses, which matters because there is no output schema. It stops short of covering pagination/error behavior, but this is a single-item lookup.

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, front-loaded with the verb/resource and then the usage hook. No filler, and the API endpoint note is a single cheap token that aids 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 two-parameter read with no output schema, the description covers what an agent needs: identity, scope, and the return payload. It could go one step further on the `expand` values, but nothing critical 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 description coverage is 100%, so both parameters are documented structurally and the baseline is 3. The description adds the reason the id matters (address ids downstream) but says nothing about the `expand` options beyond what the schema enum already provides.

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 customer by id) with a scope qualifier that separates it from housecall_list_customers. It also names the payload contents (addresses), so an agent knows exactly what it gets back.

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 downstream reason to call it: the address ids are needed to create a job or estimate, which routes the agent to housecall_create_job/housecall_create_estimate. It does not, however, explicitly say when not to use it (e.g. bulk lookup via list_customers).

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 covers the safety profile, so the description's real contribution is disclosing the response shape: a single estimate plus its options with per-option approval status. With no output schema present, that content-level disclosure is genuinely valuable, though it omits error/not-found 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?

Two tight sentences: the capability first, the underlying endpoint second. No filler, and the key scoping information is front-loaded.

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

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

For a one-parameter read tool with no output schema, the description supplies the essential missing piece by naming what the response contains. It is close to complete, lacking only a note on failure behavior when the estimate id does not resolve.

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 single estimate_id parameter is already documented there. The description only echoes the id-based lookup, adding no format, prefix, or sourcing guidance beyond the schema, so the baseline 3 applies.

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

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

States a specific verb ('Fetch') and resource ('a single estimate') scoped to an id, which cleanly separates it from siblings like housecall_list_estimates and housecall_create_estimate. The added detail about options and approval status further sharpens what kind of estimate payload is returned.

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 this is the single-record lookup as opposed to the list tool, but it never explicitly says when to prefer it over housecall_list_estimates or what happens if the id is unknown. 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?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the shape of the response (customer, address, schedule, employees, notes, totals), which is genuinely useful given there is no output schema, but says nothing about error behavior or missing ids.

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 with the payload enumeration front-loaded, followed by a compact endpoint reference. No filler, though the GET path adds little for an agent that already has the 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?

With no output schema present, the description compensates by listing what comes back, and annotations cover safety. Only the failure mode for a bad or missing job id is left unstated.

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 parameters are already documented in the schema, and the description only restates 'by id'. The optional expand parameter is not addressed in the description at all, so it adds no meaning beyond the structured fields.

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 (Fetch) plus resource (a single job by id) and an enumeration of the returned payload. It is clearly distinguishable from the sibling housecall_list_jobs, which returns many.

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 'by id' phrasing and the singular resource, but there is no explicit statement of when to prefer this over housecall_list_jobs or any note about what happens if the id is unknown. Adequate, not instructive.

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=true annotation already carries the safety profile, so the description's burden is reduced. It adds the returned field set and the API mapping, but says nothing about behavior beyond the happy path — no 404/not-found handling, permission requirements, or response envelope shape.

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, front-loaded sentence giving the action, identifier, and returned payload, followed by the endpoint mapping. No redundancy or 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?

With no output schema, the description usefully compensates by enumerating the fields returned. Combined with the readOnly annotation and fully documented single parameter, an agent has what it needs to invoke the tool correctly; only error behavior is 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?

There is only one parameter and schema description coverage is 100% ('The lead id.'), so the schema already documents it fully. The description's 'by id' adds nothing beyond the schema, which is the expected baseline of 3 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?

The description pairs a specific verb and resource ('Fetch a single lead by id') and enumerates what that lead contains (customer, address, source, tags, assigned employee, status, pipeline status), plus maps to the underlying endpoint. The phrase 'single ... by id' functionally distinguishes it from the sibling list_leads without the agent needing to open 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?

Usage is implied: you need a lead id to call it, so this is the lookup tool when the id is known. However, the description never states when to prefer this over housecall_list_leads, nor any exclusions or failure conditions (e.g. unknown id). Guidance is present only by inference.

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

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

readOnlyHint=true already declares this as a safe read, so the bar is lower. The description adds the returned field set and the upstream endpoint mapping (GET /customers), but says nothing about pagination behavior, result caps, or ordering defaults beyond what the schema covers.

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 zero filler, leading with the core action and result contents before the search semantics and endpoint reference.

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, zero-required-parameter list tool with full schema coverage and no output schema, the description covers purpose, search scope, and returned fields adequately. It could mention pagination defaults or result ordering, but nothing essential 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 description coverage is 100%, so all seven parameters are already documented, including the q search scope and location_ids note. The description repeats the q scope rather than adding format, default, or interaction detail, so 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 ('List or search') and resource ('customers'), and adds what the results contain (phone numbers, tags, addresses). It does not explicitly distinguish itself from the sibling housecall_get_customer, 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?

Usage is implied by 'List or search' versus the singular get_customer sibling, but the description never states when to use this tool versus that one, nor any exclusions. The q-search sentence is parameter guidance rather than routing 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 tells the agent this is a safe read. The description adds the useful scope constraint that only ACTIVE employees are returned, but says nothing about pagination behavior, rate limits, or auth requirements. Adequate but not rich, given annotations cover the safety profile.

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 efficient sentences with the purpose front-loaded and zero filler; the trailing 'Housecall Pro: GET /employees' is a minor but legitimate source reference. Slightly more than strictly necessary, but well structured.

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 helpfully names the returned fields (role, contact details, permissions) and the active-only scope. Pagination semantics for page/page_size are left entirely to the schema, which is a minor gap for a 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?

Schema description coverage is 100%, so all five parameters (page, page_size, sort_by, sort_direction, location_ids) are already documented at baseline. The description adds no syntax or format detail beyond the schema, so the standard 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 and resource ('List the company's active employees') and enumerates what comes back (role, contact details, permissions). No sibling lists employees, so it is unambiguous against housecall_list_customers and housecall_list_jobs.

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' states a downstream intent but does not explain when to call this versus alternatives, nor any preconditions apart from the implicit active-employee scope. Usage is implied rather than 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 covers the safety profile. The description contributes genuinely useful context — that each result carries its customer, address, schedule and options, and the underlying GET /estimates endpoint — but says nothing about pagination behavior or default ordering. With annotations carrying the safety burden, a 3 is fair.

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 the resource and its filter dimensions front-loaded, plus a one-line endpoint reference. Efficient, though the endpoint citation is marginal value for an agent that only needs to call the 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, all-optional list tool with no output schema, the description covers the filter surface and hints at the shape of a returned record. It stops short of describing pagination defaults or the full return structure, but nothing required to invoke 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 description coverage is 100%, so all 12 parameters are already documented in the schema with enums and ISO-8601 format notes. The description restates a subset of the filters (customer, work status, employees, scheduled window) without adding syntax or semantics beyond the schema, so 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+resource ("List estimates") and enumerates the filter dimensions, so the agent knows this is a filtered collection read. It contrasts implicitly with the singular get_estimate sibling via plural 'list', but does not name 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 filterable dimensions (scheduled window, customer, employees, work status) imply when the tool is useful, but there is no explicit when-to-use vs when-not guidance and no named alternative to fall back on. Usage is left to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, and the description adds a genuinely useful non-obvious trait: 'Amounts are in cents.' That unit detail is not in the schema or annotations. It still omits pagination behavior and result shape, which keeps 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?

Front-loaded with purpose and filters in one dense sentence, then two short trailing fragments for the unit and the upstream endpoint. Nothing is wasted, though 'Housecall Pro: GET /invoices' carries little actionable value for an agent.

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 13-parameter read-only list tool with no output schema, the description covers scope, the filter dimensions, and the amount unit. The main remaining gap is pagination behavior (page/page_size exist but are only described in the schema), which is a minor omission.

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 in the schema; the baseline of 3 applies. The description adds the cents unit and summarizes filter categories but no syntax, defaults, or interaction details 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 ('List') and resource ('invoices') plus a scope qualifier ('across the company') that meaningfully separates it from the job-scoped sibling housecall_list_job_invoices. It does not name that sibling outright, so the distinction is inferable 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?

The concrete example 'everything open and overdue' anchors a real use case and the filter list implies when the tool applies, but there is no explicit when-to-use guidance and no mention of when to prefer housecall_list_job_invoices instead. Usage is implied rather than directed.

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 declare readOnlyHint=true, so the safety profile is already covered. The description adds real value by enumerating what the read returns (status, amounts, due/paid dates, items, taxes, discounts, payments), though it omits pagination or result-size behavior for potentially long invoice lists.

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?

One front-loaded sentence covering purpose and payload, plus a compact endpoint 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 usefully enumerates the returned fields, which an agent needs to know. It is nearly complete, with only pagination/limit behavior left unaddressed for a 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?

There is one parameter, job_id, and schema description coverage is 100%, so the schema fully documents it. The description adds no syntax, format, or sourcing guidance for the id, 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 (List) plus resource (invoices) and scopes it to a single job, which is what separates it from the sibling housecall_list_invoices. An agent can distinguish the two 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?

The 'for one job' scoping implicitly signals when to pick this over the all-invoices sibling, but there is no explicit when/when-not statement or named alternative. 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the returned fields (unit price, cost, quantity, amount) and critically that monetary values are in cents, which prevents unit misinterpretation. Pagination behavior is not mentioned, 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 tight sentences with no filler; the core purpose and the returned fields are front-loaded, and the API endpoint reference is compact. 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?

No output schema exists, so the description must describe returns, and it does list the meaningful fields plus the cents denomination. For a simple one-parameter read-only list tool this is nearly complete, with only pagination behavior left unspecified.

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 there is only one required parameter (job_id), so the schema already documents the input fully. The description implies a job target but adds no syntax or format details beyond what the schema provides, matching the baseline 3.

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 (line items on one job), and enumerates the kinds of items (services, materials, labor, discounts), which distinguishes it from siblings like housecall_list_job_invoices. An agent can identify the tool's function 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?

The scoping phrase 'on one job' implies usage context, but there is no explicit when-to-use guidance, no exclusions, and no named alternative (e.g., list_job_invoices for invoice-level data). 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 readOnlyHint=true, so the safety profile is covered, and the description adds the upstream endpoint (GET /jobs) and the shape of each returned job. It says nothing about pagination behavior or result volume despite exposing page/page_size, which limits how useful it is for a 13-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?

Three compact sentences: purpose and filters first, then return contents, then the API endpoint. No filler and nothing is 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, the description usefully enumerates what each job carries (customer, address, notes, schedule, employees, totals), and all 13 params are schema-documented. Only pagination/result-size behavior is 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 every parameter is already documented in the schema; the description only paraphrases the filter categories (scheduled window, customer, employees, status). Baseline 3 is appropriate since 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 and resource ('List jobs') plus the filter dimensions, so it is clearly a bulk-retrieval tool rather than a mutation. It does not explicitly contrast with the sibling housecall_get_job for single-job retrieval, 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?

Usage is implied by the enumerated filters ('filterable by scheduled window, customer, assigned employees and work status'), which tells an agent what scoping is available. There is no explicit when-to-use/when-not statement or routing to housecall_get_job for a single record.

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 useful context beyond that: concrete value examples and the underlying endpoint (GET /job_fields/job_types), which reinforces the read-only, static-reference nature of the data. It does not describe pagination or return shape, but for a small reference list that is minor.

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 examples, then the usage note, then the endpoint. No filler; every sentence 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 read-only reference-list tool with one optional param, full schema coverage, and readOnlyHint annotations, the description is nearly sufficient. It explains purpose, example values, and downstream use; a note on whether it returns all types by default or the response shape would make it 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% and the single optional 'name' filter is fully documented in the schema, so the baseline is 3. The description adds no extra syntax or matching semantics for the filter beyond what the schema already states.

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 gives a specific verb (List) and resource (the company's job types) plus concrete examples (Repair, Install, Maintenance), so the agent immediately knows what this returns. No sibling tool covers job types, so disambiguation is largely automatic rather than explicitly 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?

It states a clear downstream context: the returned id is used as job_type_id when creating a job or estimate. This tells the agent why it would call the tool, though it doesn't frame alternatives or exclusions, which is unnecessary here since no sibling overlaps.

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 description's only added behavioral signal is the filter surface. It says nothing about pagination behavior, default page size, result caps, or response shape, which matters for a list endpoint with page/page_size parameters. Some value added, but not rich 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, filter surface front-loaded, API mapping tucked at the end as a secondary detail. Zero 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 10-parameter read tool with no output schema, the description names the primary filter dimensions and identifies the backing endpoint, which is enough for an agent to select and call it. The gap is pagination/sort behavior and the location_ids conditional, but annotations and the 100%-covered schema carry most of the load.

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% across all 10 parameters, so the schema already documents enums, pagination, and sort options fully; baseline is 3. The description restates a subset of filters (status, customer, employees, tags, source) but omits sort_by, sort_direction, page, page_size, and the location_ids multi-location caveat, adding 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 (list) and resource (leads) plus the filterable dimensions, and the 'Housecall Pro: GET /leads' mapping pins the operation precisely. It is clearly distinguished from the singular housecall_get_lead and the write-side housecall_create_lead by name alone. It stops short of an explicit 'not this sibling' statement, so a 4 rather than 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?

The listed filter dimensions imply 'use this to browse/search leads', and the pairing with housecall_get_lead is inferable, but there is no explicit when-to-use, when-not-to-use, or named alternative. Usage is implied 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description still adds genuine behavioral value by disclosing the return payload (including that cost is in cents) and that nested materials/labor rates are empty unless opted in. It omits pagination defaults and any rate-limit or permission notes, which keeps 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?

One front-loaded sentence plus a compact API path reference; no filler. The semicolon-heavy clause listing returned fields makes it slightly dense to parse but nothing 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?

With no output schema, the description correctly compensates by naming the returned fields and the opt-in expansion behavior, so an agent knows what it will receive. Missing only secondary details like default page size and authentication expectations.

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 all six parameters (q, page, page_size, sort_by, sort_direction, expand) are already documented in the schema. The description only adds a gloss on expand ("materials and labor rates"), which is useful but marginal — 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 pair (list/search) and resource (price book services), then enumerates the returned attributes (name, task number, price, cost, taxable/online-booking flags). No sibling tool touches the price book, so the resource alone disambiguates it from list_customers/list_jobs/list_invoices.

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?

"List or search" implies the two entry modes, and the q parameter makes the search path clear, but there is no explicit guidance on when to reach for this tool versus a job/estimate line-item tool, and no stated prerequisites. Usage is implied rather than directed.

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 tells the agent this is a safe, non-destructive read, so the bar is lower. The description adds the company-level scope and a GET endpoint reference, but says nothing about pagination behavior despite page/page_size parameters, nor about result volume or ordering defaults.

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; nothing is padded. The trailing API endpoint note is marginally useful for debugging but adds little for an agent selecting the 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 read-only, zero-required-parameter list tool with full schema coverage and a readOnlyHint annotation, the definition is sufficient to invoke correctly. No output schema exists, so return values need not be described; only ordering/pagination defaults are 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 all four parameters (page, page_size, sort_by, sort_direction) are documented in the schema with enums, so the baseline of 3 applies. The description adds no parameter meaning beyond what the schema already provides.

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), resource (tags), and scope (defined in the company), so an agent immediately knows what it returns. It does not explicitly differentiate from sibling list tools like housecall_list_job_types, though the resource name makes the distinction reasonably clear.

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 no when-to-use context, prerequisites, or alternatives; it is purely a purpose statement. For a simple enumeration tool this is tolerable, but there is no guidance about when tags are needed versus other lookups such as job types or price book services.

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 risk is flagged structurally. The description adds genuinely useful context beyond that: 'Only the fields you pass are sent' tells the agent this is a partial update rather than a full replace. However, it never reconciles the destructive hint, says nothing about clearing fields, required permissions, or what an invalid customer_id does.

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 field list and the key partial-update rule front-loaded; every sentence earns its place. The trailing API route is minor but harmless metadata for agents that recognize the Housecall Pro surface.

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 33% schema coverage, the description covers the mutable field surface and the partial-update contract, which is the most important thing. It still leaves permission requirements, error behavior, and null/clearing semantics unspecified.

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% (tags, company, customer_id, notifications_enabled), but the description names most of the gap: name, contact details, lead source, notes, notification setting. That partially compensates without giving format or validation detail, and parameters like home/work/mobile_number are only loosely implied by 'contact details'.

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 clear verb ('Change') plus the resource ('a customer') and enumerates the mutable fields, so its purpose is unambiguous against siblings like housecall_create_customer or housecall_get_customer. It stops short of explicitly contrasting itself with the sibling that also edits customer data, but the verb makes routing obvious.

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 prerequisites (e.g. needing an existing customer_id or lookup via housecall_get_customer first), and no exclusions. The closest thing to guidance is the partial-update note, which is behavioral rather than a usage rule.

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 carry destructiveHint=true, so the description adds meaningful behavior: dispatch of employees, customer and/or pro notification, and the multi-day restriction. It states the underlying PUT endpoint, but does not say whether existing assignments are overwritten or what permissions are needed.

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 sentences, front-loaded with the action and options, followed by the restriction and the endpoint. Every sentence carries information an agent needs; 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 mutation tool with no output schema and a terse annotation set, the description covers scope, side effects and the key exclusion. It could still state what happens to existing schedule values or whether notify is defaulted, but nothing essential to a correct call 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 description coverage is 100%, so all seven parameters are already documented in the schema; baseline is 3. The description restates start/end, arrival window, dispatch and notification intent but adds no format, defaults, or interaction rules beyond what the schema provides.

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') with the optional side effects named, and explicitly carves out the multi-day/multi-appointment case that must use a different path. An agent can distinguish this from housecall_create_job and housecall_dispatch_job 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?

Gives clear context for invocation (set or change an existing job's schedule) and one explicit exclusion: jobs with more than one appointment cannot be rescheduled here. It does not name the alternative tool to use for that multi-day case, so it stops short of a 5.

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