Zenbooker MCP by usefulapi

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

Annotations already flag this as a non-read-only, non-idempotent, destructive, open-world write. The description adds real value beyond them: notes are appended and never replaced, cannot be deleted via this server, and the job should be verified first - all of which explain the consequences of the destructiveHint/non-idempotent profile. It stops short of stating what a retry produces or what the endpoint returns.

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 WRITE marker and the core action, followed by the behavioral caveats. The endpoint path is a useful compact anchor. 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 mutation with no output schema, the description covers action, irreversibility, and a precondition, which is enough to call it correctly. The only gap is the absence of any statement about the response (e.g., whether the created note is returned), which is minor given there is no output 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% with only two required parameters, so the schema already documents job_id and text fully. The description only echoes them via '(text)' and 'to a job' and adds no format, length, or sourcing detail beyond the schema. 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?

The description opens with a scoped verb+resource ('WRITE: add an internal note (text) to a job') and the word 'internal' distinguishes it from any customer-facing note concept. It is trivially separable from the read-oriented siblings (get_job, list_jobs, get_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?

It gives one concrete precondition ('check the job first'), which is genuine usage guidance. However, it names no alternative tools and gives no explicit when-not-to-use condition, leaving usage 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. With no output schema, the description carries the burden of the return shape and does so concretely (in_service_area plus matching/other/closest territories), which is meaningful added context. It omits auth needs, rate limits, and error/geocoding-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: the return-value behavior is front-loaded and the input options follow immediately, with the GET path appended as a compact reference. Nothing is padded, though the raw endpoint string is marginal for agents that never see the API 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 read-only, four-parameter lookup with full schema coverage but no output schema, the description supplies what the schema cannot: the response fields and the closest-territory fallback when the location is outside all areas. It lacks only failure-mode and authentication context.

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 schema already states that lat must be sent with lng and that address is only needed absent a postal code or coordinates. The description's 'postal code, address, or lat + lng' phrasing loosely implies these are alternative input modes, but adds no syntax, format, or precedence detail 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+resource ('Check whether a location is inside the business's service area') and enumerates the exact return fields (in_service_area, matching territory, other territories, closest territory when outside). This is clearly distinguishable from siblings like zenbooker_get_territory and zenbooker_list_territories, which retrieve territory data rather than testing a location against coverage.

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 accepted input forms ('Give a postal code, an address, or lat + lng'), which tells the agent how to invoke it, but never states when this tool should be chosen over get_territory/list_territories or any exclusion conditions. 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 cover the mutation/safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=true). The description adds meaningful context beyond that: it will not deduplicate, implying non-idempotent behavior and duplicate risk, and notes the underlying POST /v1/customers endpoint. It stops short of describing the return payload, which is a minor gap.

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 the write semantics front-loaded, followed by the duplicate-avoidance guidance. No filler text.

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?

Given a simple 3-parameter create tool with full schema coverage and annotations carrying the safety profile, the description is largely sufficient. It could note what the response returns (e.g., new customer ID), but that is a small 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 name/email/phone are already fully documented with types and length bounds. The description's restatement of name as required and phone/email as optional is accurate but redundant with the schema's required array.

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 an explicit verb (create) and resource (customer record) plus the service name, and the WRITE prefix signals mutation immediately. It is clearly distinguishable from siblings like zenbooker_list_customers and zenbooker_get_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?

Explicitly directs the agent to search with zenbooker_list_customers first to avoid duplicates, and explains why (the tool does not check for existing customers). This names both the alternative and the condition that selects it.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds value by naming the return payload (contact details, notes, addresses, job/recurring ids, Stripe link) in the absence of an output schema, though it says nothing about not-found behavior or auth.

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 covers the resource, identifier, and return contents, followed by the endpoint. No filler or repetition.

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

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

For a one-parameter read tool with no output schema, the field list gives the agent a good picture of what comes back. Missing only error/not-found semantics and the contrast with list_customers, which are minor 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?

Schema description coverage is 100% and there is a single parameter, so the schema already explains customer_id as 'the id field of a list result.' The description's 'by id' phrasing only restates this, adding no format or lookup detail.

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 ('One customer by id') and enumerates the fields returned, which clearly separates it from list_customers. It does not name the sibling alternative explicitly, but 'one customer' vs. a list is unambiguous.

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: fetch a single customer when you already have its id. There is no explicit when-to-use/when-not guidance, no mention of list_customers as the alternative for enumeration, and no note on what to do if 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds the response contents (line items, discounts, tax, totals, status, transactions) and the underlying route, which is real value given no output schema exists.

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 terse fragments, front-loaded with the resource and scope, followed by the returned fields and route. No filler sentences.

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 with no output schema, the field enumeration gives the agent enough to know what comes back, and the route string aids traceability. Only minor gaps remain (no mention of not-found behavior or id source beyond the schema note).

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 invoice_id parameter is fully documented in the schema as 'the id field of a list result'. The description adds no format or sourcing detail beyond that, 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 and resource ('One invoice by id') and enumerates the payload it returns, which cleanly separates it from the sibling zenbooker_list_invoices. An agent can tell what this does 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 phrase 'by id' implies this is the single-record lookup used when an id is already known, which implicitly routes against zenbooker_list_invoices, but no explicit when-to-use or alternative is named. Usage is inferred 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, openWorldHint=true, and destructiveHint=false. The description adds useful behavioral context by listing what job information is returned and naming the REST endpoint, though it does not discuss auth, rate limits, or errors.

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

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

The description is a single front-loaded sentence listing the returned fields, followed by the endpoint. Every element is relevant and there is no wasted text.

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 get-by-id tool with annotations and a fully documented parameter, the definition is nearly complete: it identifies the resource, lists key return fields, and gives the endpoint. The main minor gap is lack of any note about invalid or missing ids.

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 job_id parameter is documented in the schema as the Zenbooker id from a list result. The description says 'by id' but adds no further syntax beyond what the schema provides, so baseline 3 is appropriate.

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

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

States the specific resource and scope: one job by id, and enumerates the job data returned. It is clearly distinguishable from sibling list_jobs by its singular by-id scope.

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 'One job by id' gives clear usage context: call this when a job id is known. It does not explicitly name alternatives such as zenbooker_list_jobs, but the use case is unambiguous for a get-by-id tool.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered without the description. The description adds the return-field inventory (first job date, status, territory, pricing, job ids), which is useful behavioral context, but says nothing about auth, rate limits, or missing-id 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?

A single compact sentence enumerating the returned fields followed by the endpoint path; purpose is front-loaded and nothing is wasted. The endpoint token is slightly redundant for an agent but costs little.

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 return-shape burden and does so by listing the key fields, which is appropriate for a simple single-record read. Minor gaps (no error/not-found semantics) are acceptable given the annotations and one-parameter surface.

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 100% schema coverage and a single required parameter, the schema already documents recurring_booking_id and even clarifies it is 'the id field of a list result'. The description adds no syntax, format, or sourcing detail 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 and resource ('Get recurring booking') and scopes it to a single record 'by id', which distinguishes it from the sibling zenbooker_list_recurring_bookings without opening either schema. It does not name that sibling explicitly, keeping it 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 'One recurring booking by id' — the agent can infer this is the lookup for a single known id. However, there is no explicit when-to-use guidance, no mention of the list sibling as the alternative for discovery, and no prerequisites or conditions.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered by structured data. The description adds the underlying endpoint (GET /v1/services/{id}) and the shape of the returned detail, which is modest but real added context; no error or permission behavior is described.

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 zero filler; the purpose and returned contents come first and the endpoint path is relegated to the tail. Every 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?

No output schema exists, but the description names the substantive fields returned (pricing, duration, option sections), which is enough for an agent to know a single-service lookup is the right call. It stops short of describing error behavior for an unknown id or any field-level structure.

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 one parameter and schema description coverage is 100%, with the schema explaining that the id is 'the id field of a list result'. The description's 'by id' adds no format or sourcing information beyond that, 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 ('One service by id') and enumerates the payload it returns (pricing, duration, option sections and their options), which is far more specific than a tautology. The contrast with the list_services sibling is implied by 'One service by id' rather than named outright, so it lands just 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?

Usage is only implied: an agent can infer you call this when you already hold a service id and need full detail rather than a list. There is no explicit when-to-use/when-not statement and no prerequisite or alternative tool named.

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, destructiveHint=false and openWorldHint=true, so the read-only safety profile is covered. The description adds the field list but says nothing about auth needs, rate limits, or behavior when the id does not exist. With annotations carrying the safety burden, this is adequate but thin.

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 scope front-loaded before the endpoint reference. No filler text.

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?

There is no output schema, so the description's enumeration of returned fields carries real weight and is largely sufficient for a single-entity fetch. It could note what happens on a missing id, but coverage is good for a simple read.

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 parameter and its provenance are already fully documented in the schema. The description adds only 'by id' on top of that, which is baseline-level value.

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 ('One team member by id') and enumerates the payload an agent can expect (contact details, role, status, territories, skill tags, work hours). This clearly separates it from the sibling list_team_members, which returns many members.

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 you need an existing id, and the schema documents that id comes from a list result, so usage is inferable. However, there is no explicit when-to-use or when-not statement, and no named alternative for situations where the agent lacks an id.

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, destructiveHint=false, and openWorldHint=true, so safety is fully covered by structured fields. The description adds nothing beyond that — no note on auth requirements, rate limits, error behavior for a missing/invalid id, or return 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?

Two short fragments, front-loaded with the resource and scoping ('One service territory by id'). The trailing REST path is mildly redundant but cheap for an API-aware 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 one-parameter read-only getter with full schema coverage, this is minimally sufficient, but with no output schema the agent gets no sense of what a territory object contains or what happens on 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 coverage is 100% and the single required parameter carries its own description ('The Zenbooker id...'). The description's 'by id' merely echoes that, 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: fetch one service territory by id, and pins it to a concrete REST path. It is clear what the tool does, but it never names list_territories or otherwise distinguishes itself from the sibling that returns the same resource in bulk.

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' weakly implies single-record retrieval versus a list, but there is no explicit when-to-use guidance, no mention of list_territories as the alternative, and no prerequisite such as needing an id obtained from that list call.

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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the prerequisite inputs and the grouped-by-day return structure, which matters because there is no output schema. It omits rate limits, pagination/cap behavior, and the drive-time effect of lat/lng.

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 that front-load the resource and return shape, then the prerequisites. The trailing 'GET /v1/scheduling/timeslots' is mildly redundant with the tool name but not wasteful enough to penalize heavily.

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 ten parameters, two required, and no output schema, the description does the important work: it identifies the required inputs, their source, and the response nesting. Optional filters (providers, skills, templates, min_providers_needed) are left entirely to the schema, which is acceptable given full coverage.

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 schema already documents all ten parameters, including the lat/lng pairing and defaults. The description only restates that territory and duration are needed, adding no syntax or format detail beyond the required list. 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 resource ('available booking time slots for a service territory') and even the response shape ('days[].timeslots[] with start, end and id'), so an agent knows exactly what it gets back. No sibling tool returns timeslots, so differentiation is not a meaningful gap, but the statement is descriptive rather than sharply verb-led.

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 concrete prerequisites and routes the agent to the right siblings for the territory id ('zenbooker_list_territories or zenbooker_check_service_area'), plus the required duration. It stops short of stating when not to use this tool or how it relates to any competing availability path.

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 annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. Beyond that, the description enumerates what the response contains (status, type, method, amount, invoice and customer ids, Stripe references), which is genuinely additive given there is no 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 compact sentences, front-loaded with what is returned. The trailing 'GET /v1/transactions/{id}' is largely redundant with the tool name and schema, which keeps it from a 5.

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 one simple required parameter, no nested objects, no enums and annotations covering the safety profile, the description is nearly complete; the response-field list compensates for the absent output schema. Only error/not-found behavior is left unstated, which is a minor gap.

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

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

Schema description coverage is 100% and the single parameter is fully documented ('The Zenbooker id (the id field of a list result)'). The description adds nothing further about the id format, 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 and resource ('One payment transaction by id') and enumerates the fields returned, so the agent knows it is a single-record fetch rather than a list. It only implicitly distinguishes itself from the sibling zenbooker_list_transactions by the phrase 'by id', so differentiation is not made 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?

No when-to-use guidance and no alternatives named. The agent must infer that this is for retrieving one transaction when an id is already known, rather than calling zenbooker_list_transactions first.

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, openWorldHint=true and destructiveHint=false, so safety is covered; the description goes beyond them by disclosing the response envelope { results, count, has_more, next_cursor } and the underlying GET /v1/customers endpoint, plus the cursor-based pagination contract. It does not mention rate limits or ordering of results.

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 first front-loads the filter capabilities, the second gives the return shape and endpoint. Nothing is redundant and no sentence 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 usefully supplies the return keys and paging fields, and the cursor parameter's meaning is anchored to next_cursor. Only minor details (result ordering semantics, behavior when multiple filters combine) are 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 all ten parameters are already documented — baseline 3. The description's only marginal additions are restating the filter groupings and the location+radius coupling (including miles), which the schema itself already spells out for radius.

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/search customers) and enumerates the actual search modes — name/email/phone, creation time, and geographic proximity — which clearly separates it from get_customer and create_customer among its siblings.

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 search modes imply when this tool is appropriate, but there is no explicit routing guidance such as 'use get_customer when you already have an ID' or any condition under which this tool should not be used. Usage is inferable but never 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 and destructiveHint=false, so the safety profile is covered. The description goes further by disclosing the return envelope ({ results, count, has_more, next_cursor }) and that each invoice embeds line items, totals, amount paid/due and transactions — useful context given there is no 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?

Three tight sentences: what it lists, how it can be filtered, and what comes back, ending with the endpoint. No filler and the core purpose 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?

With a 9-parameter, zero-required, fully documented schema and read-only annotations, the remaining burden is the response shape, which the description supplies since no output schema exists. Pagination is also addressed via next_cursor. Only the absence of explicit sibling routing 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% and every parameter is documented in the schema, including the enum values, defaults and cursor semantics. The description restates the same filters (status, customer, territory, creation time) without adding format or constraint detail 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 (List) and resource (invoices) plus the full filter surface (status, customer, territory, creation time). It is clearly distinct from the singular get_invoice sibling by the plural listing semantics, but it never names an alternative explicitly, so differentiation is implicit 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?

Usage is implied by the filter list — an agent can infer this is the bulk/query tool versus get_invoice for a single record — but there is no explicit when-to-use or when-not-to-use guidance, and no mention of the related list_transactions tool for invoice transactions.

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 readOnly and non-destructive, so the description adds genuine extra context: default ordering by start time, the returned envelope {results, count, has_more, next_cursor}, and how to paginate via next_cursor. It stops short of noting any limits beyond the schema's max of 100, but the pagination and response-shape disclosure is real 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?

Two compact sentences: the primary behavior and filter surface first, then the return shape and pagination instruction. No filler, every clause carries information relevant to calling 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 and 14 optional parameters, the description supplies the missing pieces: the return envelope, the has_more/next_cursor paging contract, and the default sort. Nothing an agent needs to invoke a read-only filtered list correctly is absent.

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 and ISO date patterns is already documented, which sets the baseline at 3. The description's prose filter list largely restates the schema keys without adding format, interaction, or defaulting details 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 and resource ("List jobs (booked appointments)"), declares the default sort and the full filter surface, and is clearly distinguishable from the singular zenbooker_get_job sibling. An agent knows immediately this is a filtered collection read.

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 the tool is useful (narrowing by customer, member, territory, status, time window), but there is no explicit guidance on when to prefer it over siblings like zenbooker_list_recurring_bookings or zenbooker_get_timeslots. Usage must be inferred from the parameter enumeration.

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 cover the safety profile (readOnly, non-destructive, openWorld), so the bar is lower. The description still adds real value: the 40-per-page ceiling, the exact return shape ({ results, count, has_more, next_cursor }), and the backing endpoint GET /v1/recurring. It omits rate limits and sort/default behaviors, which are left to the 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?

Three tight clauses: what it lists, what it filters by, page ceiling, return shape, endpoint. Front-loaded and waste-free, though the 'GET /v1/recurring' fragment is largely redundant given the name and openWorldHint.

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 9-parameter, all-optional list tool with no output schema, the description supplies the return keys and page cap that the structured fields do not. An agent has enough to call it correctly; only edge behavior (empty filters, default sort) 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 with type, bounds and semantics. The description echoes the filter set but adds no syntax, format, or defaulting detail beyond what the schema provides; 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 recurring bookings'), adds a clarifying synonym ('repeating job series'), and enumerates the filterable dimensions. It is clearly distinct from get_recurring_booking, though it never explicitly contrasts with the similar-looking list_jobs sibling.

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 the tool is useful (filtered browsing of recurring series by status/customer/assignee/territory/date), and 'Max 40 per page' hints at pagination. But there is no explicit when-to-use vs. get_recurring_booking or list_jobs, and no note on behavior when no filters are supplied.

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 and destructiveHint=false, so safety is covered. The description goes further by disclosing the response envelope shape ({ results, count, has_more, next_cursor }), which tells the agent pagination exists and how to continue, and it names the underlying endpoint. It does not cover ordering guarantees or rate limits, so it is not a 5.

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

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

Two sentences plus a bare endpoint reference; the purpose leads, details follow, and there is essentially no filler. The middle clause packing seven returned fields is dense but still readable.

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 carries the return shape and pagination signal, and annotations cover the safety profile, so an agent has what it needs to call this correctly. A brief note on default sort/filter interactions or listing combined with filters would make it fully self-sufficient.

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 8 parameters (limit, cursor, customer, territory, sort_order, request_type, created_after, created_before) are already fully documented in the schema. The description only loosely gestures at filtering by naming record fields such as customer, territory and requested dates, adding no syntax beyond the schema. 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) and resource (incoming service requests), and usefully classifies the resource as booking requests and quote requests, which separates it from generic job or booking listings. It enumerates the fields surfaced in each record. It does not, however, explicitly contrast itself with siblings like list_jobs or list_recurring_bookings.

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 only implied: an agent can infer this is the read path for service requests, and the filter-oriented framing hints at narrowing results. There is no statement of when to choose this over list_jobs/list_recurring_bookings, nor any prerequisites or exclusions.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered without the description's help. The description does add useful behavioral content by naming the returned fields (pricing method, base price, duration, option sections, recurring frequencies), which matters because there is no output schema — but it omits pagination behavior despite cursor/limit parameters existing.

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 return fields front-loaded; nothing is padded. The trailing 'GET /v1/services' is mildly redundant transport detail but harmless.

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 field enumeration is the right kind of compensation and covers the return shape adequately. What is missing for a seven-parameter, paginated list tool is any note about pagination behavior or how it relates to zenbooker_get_service, leaving the agent to reconstruct that from the 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 all seven parameters including cursor, limit, is_visible, category_id and the created_after/before bounds are fully documented in the schema itself. The description adds no parameter-level meaning beyond that, 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?

Specific verb ('List') plus resource ('services a business offers') and an enumeration of the fields returned, so the agent knows exactly what this retrieves. It does not, however, distinguish itself from the sibling zenbooker_get_service, leaving the single-vs-collection split to the agent to infer from 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?

There is no statement of when to use this tool versus zenbooker_get_service, nor any guidance on the filter parameters available (is_visible, category_id, date ranges) that would tell an agent when this list call is the right choice. Usage is only implied by the tool name.

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, destructiveHint=false, and openWorldHint=true, covering the safety profile. The description adds what fields are returned (role, status, territories, skill tags, work hours) and the endpoint, which is useful context but does not disclose pagination behavior, default filtering, or rate limits beyond what the schema already provides.

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

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

The description is two sentences, front-loaded with the core purpose before adding a usage hint and endpoint. It is efficient, though the trailing 'GET /v1/team_members' is a minor technical detail that could be omitted without loss.

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?

Given nine optional parameters but full schema descriptions and annotations covering safety, the description is largely complete. It lists key returned fields and a downstream use case, but does not explain pagination or the default behavior of filters, which would be helpful since there is no output 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 all nine parameters are fully documented in the schema. The description does not add any parameter-level semantics or syntax beyond what is already in the schema, making a baseline score of 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' and resource 'team members', and clarifies the scope by including staff and service providers. It does not explicitly differentiate from the sibling get_team_member, but the plural/list nature is clear from the name and description.

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 usage by saying 'Use the ids to filter jobs by assigned provider', which suggests a downstream purpose but does not state when to choose this tool over alternatives like get_team_member. There are no explicit when/when-not conditions or alternative tool recommendations.

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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the HTTP method (GET /v1/territories) and enumerates the returned fields, but says nothing about pagination behavior or result limits despite the cursor/limit params.

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 core purpose front-loaded, followed by the downstream-use hint and endpoint. No filler, though the trailing bare endpoint adds little 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 read-only list tool with no output schema, the description usefully enumerates the returned fields and points to downstream consumers of the ids, and annotations cover safety. It stops short of describing pagination or ordering semantics, which is the only meaningful gap.

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

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

Schema description coverage is 100% and all seven parameters (name, limit, cursor, enabled, sort_order, created_after, created_before) are fully documented in the schema. The description adds no syntax or filtering semantics beyond that, 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 and even defines the domain term ("areas a business serves") plus the fields returned: timezone, service area, providers, operating hours. It is clearly a list operation, distinguishable from siblings like get_territory and check_service_area, though it never names them 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?

It tells the agent what to do with the returned ids ("filter jobs and invoices or to look up time slots"), which implies downstream usage. However, it gives no guidance on when to prefer this over get_territory, check_service_area, or how the name/enabled filters should be chosen, 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuine context the annotations do not: the paginated response envelope { results, count, has_more, next_cursor } and the underlying GET /v1/transactions endpoint, which tells the agent how to page and what to expect.

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 carrying the filter dimensions, followed by the return shape and endpoint. No filler, no repetition of the title, and the most decision-relevant information (what is listed, what can be filtered) comes first.

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, zero-required list tool with no output schema, the description covers purpose, filters, pagination return shape, and endpoint; annotations cover the read-only safety profile. It is close to complete, with only the relationship to the single-transaction sibling 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%, so every parameter is already documented with enum values, defaults, and ISO 8601 patterns. The description restates the filter dimensions (type, status, customer, territory, dates) but adds no syntax, 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 and resource ('List payment transactions') and enumerates the filterable dimensions, which cleanly separates it from the singular sibling zenbooker_get_transaction and from list_invoices/list_customers. An agent can identify the tool's scope 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?

Usage is implied by the word 'optionally' plus the filter list, but the description never states when to prefer this over zenbooker_get_transaction (single lookup) or how it relates to other list tools. No exclusions or prerequisites are given.

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