AgendaPro MCP by usefulapi

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

Beyond the annotations, the description discloses irreversibility through the API, merchant-policy refusal conditions, HTTP 422 behavior, and the instruction not to retry. This is strong behavioral context for a destructive write tool.

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 front-loaded with "WRITE: cancel a booking" and then packs confirmation, policy, error handling, and endpoint details without filler. Every sentence contributes operational guidance.

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

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

For a one-parameter destructive action with rich annotations and no output schema, the description covers the essential behavior: irreversibility, policy constraints, error handling, and user confirmation. 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 coverage is 100% and the single booking_id parameter is already documented in the schema. The description adds no additional parameter semantics beyond the endpoint path placeholder, 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?

The description states a specific verb and resource: "cancel a booking," and marks it as a WRITE operation. This clearly distinguishes it from read/list/update siblings such as agendapro_get_booking and agendapro_update_booking.

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

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

It gives clear usage context: confirm with the user before calling, and do not retry on HTTP 422 because merchant policy refuses the cancellation. It does not explicitly name alternatives such as using update_booking for rescheduling, 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.

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description backs those with concrete consequences ('calling twice books twice'), plus two facts the annotations cannot express: no email/SMS/WhatsApp notifications fire from API-created bookings, and status_id must be a non-cancelled status.

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 'WRITE:' and the core action, then prerequisites, then side effects, then the endpoint. Every clause carries information an agent would otherwise get wrong.

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-param mutation with no output schema, the description covers prerequisites, side effects, and mutation semantics well. It never states what is returned (e.g. the new booking id), which an agent needs in order to subsequently get or cancel the booking.

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 baseline is 3; the description adds real semantics by constraining status_id to a non-cancelled status and prescribing how to source its value from list_bookings. It does not touch the optional notes/price/time_resource_id fields, which the schema already covers.

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?

Opens with an explicit 'WRITE: create a booking' verb+resource and immediately scopes the entities involved (existing client, service, provider, location), which cleanly separates it from agendapro_update_booking and agendapro_cancel_booking.

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 ordered prerequisites: check agendapro_list_available_slots first, and obtain status_id by copying status.id from agendapro_list_bookings. Both named siblings come with the condition that selects them, leaving little 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 write/destructive/non-idempotent/open-world, so the description's real contribution is the AgendaPro validation rule (first_name plus at least one of last_name, email or phone) and the side-effect disclosure that no message is sent to the client. 'Not idempotent' restates the annotation, but the duplicate-creation and no-notification context adds genuine value for a mutation tool.

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?

Everything is packed into two short sentences with no filler: write intent, validation rule, dedupe guidance, side effect, endpoint. The most decision-critical facts (WRITE, search first) are 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 15-parameter mutation with no output schema, the definition covers the write semantics, the required-field rule, duplicate risk and the absence of client notification. It leaves unclear what is returned on success and what happens if a duplicate is submitted anyway, but nothing essential to calling 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 15 field descriptions already carry their own meaning (baseline 3). The description still adds a constraint the schema does not encode — the schema requires only first_name, yet the tool rejects calls without one of last_name/email/phone — which is exactly the kind of cross-parameter rule an agent would otherwise get wrong.

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?

Opens with an explicit 'WRITE: create a new client' verb+resource+operation-type framing, which immediately separates it from agendapro_get_client, agendapro_list_clients and agendapro_update_client. The API endpoint (POST /v3/clients) confirms the resource 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?

Explicitly tells the agent to call agendapro_search_clients first to avoid duplicates, and states the tool is not idempotent. It does not, however, name agendapro_update_client as the route for existing clients, so the boundary with the update sibling is left implicit.

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 underlying endpoint (GET /v3/bookings/{id}) and the set of returned fields, but says nothing about not-found behavior, rate limits, or expansion options for the linked sale.

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 payload summary is front-loaded and the endpoint follows as supporting detail. No filler and nothing 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 no output schema, listing the returned fields is genuinely useful in telling the agent what it gets back in one call. It stops short of describing the shape of those fields or what 'the linked sale' contains, so it is strong but not exhaustive for a single-parameter getter.

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

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

Only one parameter and schema coverage is 100% — the schema already documents booking_id as a positive AgendaPro booking id. The description adds nothing about id semantics or format beyond 'by 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+resource: fetch one booking by id, and enumerates the returned fields (status, service, provider, client id, location, prices, notes, linked sale). The singular 'One booking by id' implicitly separates it from agendapro_list_bookings, though no sibling is named.

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 by 'by id' — an agent can infer this is the lookup for a known booking id rather than a search. No explicit when-to-use, no mention of when to prefer list_bookings or search, and no preconditions 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by enumerating the fields returned, which matters because there is no output schema; what it omits is error behavior (e.g. response for a nonexistent id) and pagination/expansion options.

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 resource and scope, then the payload fields. The endpoint notation is the only mildly redundant element and costs almost nothing.

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, the description plus annotations plus schema cover nearly everything an agent needs, and listing returned fields compensates for the absent output schema. The only gap is behavioral edge cases such as not-found handling.

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

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

There is a single required parameter with 100% schema description coverage, so the schema already carries the semantics. 'by id' reinforces that the path parameter is the client identifier but adds no format or range detail beyond the schema's integer/exclusiveMinimum constraint.

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 client by id') and enumerates the substantive fields returned (contact details, address, birth date, record number, active flag), which clearly separates it from agendapro_list_clients and agendapro_search_clients. It stops short of naming those siblings explicitly, so the differentiation is implied 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?

'by id' implies you must already have a client id, which is the only guidance given about when to use it. There is no explicit statement that agendapro_search_clients or agendapro_list_clients should be used when the id is unknown, and no mention of prerequisites or failure modes.

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 concrete response contents and the underlying endpoint (GET /v3/locations/{id}), which helps with diagnostics, but says nothing about unknown-id failure behavior or rate limits.

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, zero filler, with the core behavior and returned fields front-loaded before the 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 simple one-parameter read tool with no output schema, listing the returned fields plus annotations covering safety is nearly sufficient. Only the not-found/error path 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% and the single location_id parameter is documented as 'AgendaPro location id.' with a positive-integer constraint. The description adds nothing about the id's origin or format 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?

Names a specific verb and resource ('One location by id') and enumerates the payload (address, coordinates, timezone, opening hours), which distinguishes it from agendapro_list_locations by cardinality. It stops short of explicitly naming the list sibling, so it lands at 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?

Usage is only implied: fetch a single location when you already have an id. There is no explicit statement of when to prefer this over list_locations or list_available_slots, nor any precondition guidance about needing a valid AgendaPro location 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 the safety profile is covered. The description adds the concrete endpoint (GET /v3/products/{id}) and the returned field set, but says nothing about error/not-found behavior or whether the response is a single object versus a wrapped envelope.

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 clause stating what is returned plus the HTTP route — no filler, nothing an agent must scan past. The endpoint is a compact, useful addition rather than padding.

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

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

For a single-record getter with one fully documented parameter and annotations covering the safety profile, the description is nearly sufficient; enumerating the returned fields compensates for the absence of an output schema. Minor gap: no mention of not-found handling or idempotency of the lookup.

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 product_id is already documented as 'AgendaPro product id' with an integer type and positive constraint. The description's 'by id' adds no syntax, format, or sourcing guidance 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 catalog product by id') and enumerates the fields returned (description, SKU, price, category, brand, display), which lets an agent distinguish it from agendapro_list_products by singular-vs-listing scope. It stops short of naming that sibling explicitly, so it's clear but not maximally differentiated.

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: 'by id' signals you need a known product identifier, and 'One catalog product' implies the lookup-vs-list split. There is no explicit statement of when to prefer this over agendapro_list_products, nor guidance on what to do if the id is unknown or not found.

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 value beyond that by disclosing the payload contents — biography, images, working hours including breaks — which tells the agent what data it will get back.

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 returned content before the endpoint path. The REST path is mildly redundant for an MCP caller but small and 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?

For a one-parameter read tool with no output schema, the description covers what is returned and what the operation is. Nothing critical is missing, though a note on error behavior for unknown ids would complete it.

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 integer provider_id is documented in the schema, so the schema does the heavy lifting. The description only restates 'by id' without adding format, range, or lookup guidance, which is the expected baseline here.

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

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

States a specific verb and resource: fetch one service provider by id. The singular 'One service provider by id' implicitly contrasts with the sibling agendapro_list_providers, though it never names that sibling explicitly.

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

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

Usage is implied by the singular 'by id' phrasing — use this when you already have a provider id rather than browsing. There is no explicit when-to-use/when-not guidance and no reference to agendapro_list_providers as the alternative for discovery.

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 carry the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the lower bar applies. The description goes beyond them by describing the response shape – amounts, status, location, and nested payment transactions with amount/paid-at/method – which is genuinely useful since 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?

A single front-loaded sentence that names the resource, the identifier, the returned fields, and the underlying endpoint path, with no filler. Every clause earns its place.

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

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

For a one-parameter read tool with no output schema, the description compensates by enumerating the return payload, including the nested payment transaction fields an agent would otherwise have to guess. Minor gaps remain around error behavior for unknown ids, but the essential calling information is present.

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

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

There is a single required parameter with 100% schema description coverage ('AgendaPro sale id.'). The description adds only 'by id', which conveys no format, range, or sourcing detail beyond the schema, so the baseline 3 for full schema coverage is correct.

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 sale by id') and enumerates the returned content (amounts, status, location, payment transactions), which clearly distinguishes it from the list_sales sibling. It stops short of explicitly naming the alternative tool, so it falls just 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 the 'by id' framing – an agent infers this is the single-record lookup counterpart to agendapro_list_sales. However there is no explicit when-to-use, when-not, or prerequisite guidance, so it remains minimum viable rather than 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds value beyond them by disclosing the shape of the response payload (category, images, providers), which is otherwise undocumented since 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 short sentences, front-loaded with the resource and its scope. The trailing GET path is arguably redundant for an agent but is compact and 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?

For a one-parameter read tool with no output schema, the description covers what is returned, which is the most important missing structured information. It omits error behavior for a nonexistent id, 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 coverage is 100% and the single parameter already carries a description ('AgendaPro service id.') with type and bounds. The description only restates 'by id' without adding format, source of the id, or failure behavior, 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 and resource ('One service by id') and enumerates the returned substance (category, images, providers), which clearly separates it from list_services. It does not explicitly name the list_siblings as alternatives, 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?

The phrase 'One service by id' implies this is a single-record lookup that requires a known id, and the sibling set (agendapro_list_services) makes the alternative inferable. However, there is no explicit statement of when to prefer this over list_services or 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, openWorldHint=true and destructiveHint=false, so safety is covered. The description goes beyond them by describing the returned payload (start/end time, provider, service duration, slot count) and pinning it to GET /v3/available_slots, though it says nothing about empty results, timezone, or result limits.

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 clauses plus a one-line usage hint and the endpoint path; the scope and return shape are front-loaded with no filler. Every element 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?

With no output schema, the description carries the burden of describing returns and does so adequately (start/end, provider, duration, slot count). It omits edge behaviors such as response when no slots exist or pagination/limits, which keeps it just short of complete.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds meaning the schema does not, clarifying that service_id and provider_id are optional narrowing filters that can be combined ('one service and/or provider') and that start_date is single-date scoped.

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 specific verb and resource ('Free booking time windows at a location on one date') and names exactly what is returned (start/end time, provider, metadata summary). That is clearly distinguishable from siblings such as list_bookings, create_booking, and list_services without opening any schema.

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

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

'Use before creating a booking' gives an explicit workflow context that ties it to agendapro_create_booking. It stops short of naming when-not-to-use cases or alternative lookups (e.g. checking provider availability via get_provider), so no exclusions are covered.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower, yet the description still adds two non-obvious behaviors: the mandatory-filter rule and the warning that a sale may be a membership spanning several bookings so amounts must not be totaled by sale id. It does not describe result ordering or default date-window behavior, which is the remaining 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?

Three sentences, no filler, front-loaded with what comes back before the call constraints, and closing with the endpoint. The field enumeration doubles as return-value documentation since there is no output schema — 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?

With 10 parameters, no output schema and no enums, the description carries a lot of weight and does it well: it effectively describes the return shape and the call constraint. Missing only pagination guidance (deferred to the schema's next_page hint) and any note on default ordering or result size, so a 4.

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 3 is the baseline and the schema already documents each parameter. The description nevertheless adds semantics the schema lacks: which parameters satisfy the API's requirement, and that start_date/end_date only narrow rather than qualify the query. It says nothing about the scheduled or status_id filters, so not a 5.

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?

A specific verb (list) plus the exact resource (bookings, glossed as reservas/appointments) and an enumeration of returned fields — time, status, service, provider, client id, location, price, linked sale. That is more than enough to know what it does. It stops just short of a 5 because it never names a sibling such as agendapro_get_booking (single booking) or agendapro_list_sales as the alternative, so the boundary is inferred 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?

Gives the single hardest precondition outright: at least one of client_id, location_id, service_id or service_provider_id is required, and dates only narrow the result. That is a real when-to-use rule an agent would otherwise get wrong (the schema lists zero required parameters). No explicit exclusion pointing to a competing sibling tool, which keeps it at 4.

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 returned field shape and the underlying REST endpoint, which is modest added context, but says nothing about empty-result behavior, pagination, or whether attributes with no value are included.

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 fragments with the resource scope front-loaded; nothing is buried. The trailing raw endpoint is marginally redundant with the tool name but still gives useful API provenance.

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

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

For a single-parameter read tool with full annotation coverage and no output schema, the description conveys both the scope (one client) and the returned fields, which is close to sufficient. Only edge-case behavior (empty lists, missing client) is left uncovered.

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%, so the schema already documents client_id fully. The parenthetical '(id, name, datatype, value)' describes output fields rather than adding constraint meaning to the parameter, leaving this at the baseline.

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: retrieves custom attribute values for one client, and even enumerates the returned fields (id, name, datatype, value). It is distinguishable from agendapro_list_custom_attributes (which lists attribute definitions), though it never names that sibling to make the contrast 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 phrase 'stored for one client' implies the required context (you must already have a client id), but there is no explicit when-to-use guidance and no mention of the closely related agendapro_list_custom_attributes or agendapro_get_client. 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 and destructiveHint=false, so safety is covered; the description adds that paging must be driven with pagination.next_page and that results contain personal data requiring minimal use. It does not mention rate limits or result ordering, but for a read-only list tool the disclosed traits are solid.

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 purpose, then fields, then the alternative and endpoint – no filler sentences. The privacy note and endpoint citation are slightly tangential but short enough not to bloat the definition.

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 compensates by enumerating the returned fields (name, email, phone, identification, address, birth date, record number, active flag), and pagination is covered by the schema. Only minor gaps remain, such as result ordering and total-count behavior.

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

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

Schema description coverage is 100% and both parameters (page, per_page) are documented there with defaults and limits. The description's 'page by page' only implies the pagination parameters without adding format detail, so the schema does the heavy lifting and baseline 3 applies.

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

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

States a specific verb and resource ('List the business's clients (customers) page by page') and enumerates the fields returned, so the agent knows both scope and payload. It explicitly distinguishes itself from the sibling agendapro_search_clients and cites the underlying endpoint GET /v3/clients.

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

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

Gives an explicit routing rule: use this tool to enumerate the client base, but use agendapro_search_clients to find one person. It also adds a handling constraint ('only use it for the task at hand') that tells the agent how to treat the returned personal data.

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 structurally. The description adds the REST endpoint (GET /v3/custom_attributes) and the field list, but says nothing about ordering, pagination, or whether the list is bounded — minor gaps for a read-only enumerate call.

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: the payload description first, then the usage hint and endpoint. Nothing is wasted, though the trailing 'GET /v3/custom_attributes' is redundancy aimed at debugging rather than at an agent choosing a 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?

There is no output schema, so the description carries the burden of describing the return shape — and it does, by naming all six fields returned per template. An agent can call this with confidence; only ordering or emptiness behavior 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?

The tool takes zero parameters and the schema coverage is 100%, so there is nothing for the description to compensate for. Baseline 4 applies; no parameter-related confusion is possible.

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 concrete resource — the custom client field templates — and enumerates the returned fields (id, name, datatype, mandatory, group, choices), so an agent knows exactly what comes back. Combined with the title's 'List', the verb+resource is clear. It stops short of explicitly contrasting itself with the near-identically named sibling agendapro_list_client_custom_attributes, leaving that distinction to be inferred.

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 line 'Use the template ids when setting custom_attributes on a client' gives a genuine downstream-use hint, which is more than most list tools offer. However, it never states when not to use this tool or names the sibling agendapro_list_client_custom_attributes (which returns a specific client's values) as the alternative, so the choice between the two must be inferred.

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/openWorld/non-destructive, so safety is covered. The description adds the concrete field inventory (id, name, address, phone, email, timezone, hours, country) and the REST endpoint, which tells the agent this is a flat, cheap read with no side effects. Pagination behavior is left to the schema rather than spelled out.

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 what is listed, then why it matters, then the endpoint. No repetition of the title and 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?

With no output schema, the field enumeration is the right compensating move, and the 'ids are needed for' note covers the main downstream use. Only gaps are the absence of any paging note in prose and no tie-break against agendapro_get_location, both minor given 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% – page, active and per_page are all documented in the schema, including the pagination.next_page hint. The description adds no parameter meaning of its own, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the business's locations') and enumerates the fields returned, so the agent knows exactly what comes back. The 'List' prefix plus the sibling agendapro_get_location makes the plural/singular split inferable, but the description never names that sibling explicitly.

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

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

Explicitly tells the agent why to call it: 'Location ids are needed for bookings, slots and sales filters', which routes an agent that needs a location id here. It stops short of stating when NOT to use it (e.g. for a single known location, use get_location).

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 underlying endpoint (GET /v3/products) and the returned field set, but says nothing about pagination behavior, result caps, or rate limits even though the schema references pagination.next_page.

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 front-loads the resource and the payload contents, with no filler. Every clause (field list, endpoint) 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?

With no output schema, listing the returned fields is a genuine contribution, and the full schema documentation covers the parameters. It falls short only on pagination mechanics and on why one would choose this over agendapro_get_product.

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 filter (page, active, search, per_page, brand/category/display ids) is already documented in the schema, including the 'none' sentinel pattern. The description adds no filter semantics beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List retail products in the catalog') and enumerates the returned fields, so an agent immediately knows what it retrieves. It does not explicitly distinguish itself from the sibling agendapro_get_product (single product) or the other list_* tools, which keeps it below 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 only implied: the 'list' verb plus 'in the catalog' suggests browsing/enumerating, and the schema filters hint at searchable listing. There is no explicit when-to-use statement or pointer to agendapro_get_product when a single product is needed, and no mention of when filters should be preferred.

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/openWorld/non-destructive, so safety is covered; the description adds the concrete response fields (id, public name, location, active flag, online-booking flag, working hours) despite there being no output schema, plus the underlying endpoint. It omits any pagination or rate-limit behavior, which is the remaining 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 short sentences, front-loaded with what the tool returns and why it matters, closed by the endpoint. 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 8 optional parameters and no output schema, the description lists returned fields but never mentions that results can be filtered by service, location, active state or name, nor how sorting works. An agent reading only the description would not know the tool's filtering power, leaving meaningful capability undisclosed.

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%, including pagination guidance on `page` and filter semantics on `active`, `service_ids` and `location_ids`, so the schema does all the work. The description adds nothing about filtering or sorting, 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+resource ('List service providers') with a clarifying gloss ('the staff who take bookings') and an enumeration of the fields returned, which makes it distinct from agendapro_get_provider. It does not explicitly name the sibling, but the list-vs-get distinction is self-evident.

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?

'Provider ids are needed to book' implies the prerequisite workflow (enumerate providers, then create a booking), which is genuinely useful orientation. However, no condition is given for choosing this over agendapro_get_provider or agendapro_list_available_slots, and no exclusions or alternative routing is 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the shape of the response — the exact status values (partially_paid, paid, canceled, refunded), the paid/pending amount fields and included payment transactions — which tells the agent what data it will actually receive.

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 the endpoint: the verb and resource come first, then return fields, then filters. The parenthetical status enumeration is dense but earns its place; nothing is redundant or 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?

There is no output schema, so the description must carry the return-shape burden — and it does by naming the returned fields and payment transactions, while pagination is fully covered by the schema. Minor gaps (sort order, amount semantics, empty-result behavior) remain but do not block correct invocation.

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

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

Schema coverage is 100%, so all six parameters (including pagination and the date format pattern) are already documented. The description only restates the filter dimensions without adding semantics such as timezone handling for paid_at_start/paid_at_end or how ordering works, 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?

"List sales (ventas)" is a specific verb plus resource, and the description immediately enumerates the fields returned (status, amounts, paid-at, location, client id, transactions), so an agent knows exactly what entity it gets. It does not name the sibling agendapro_get_sale or explain the list-vs-single distinction, which keeps it just 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?

"Filter by paid date range, location or client" implies when this tool is useful, but there is no explicit statement of when to prefer it over agendapro_get_sale, nor any exclusion or prerequisite (e.g. required scopes, when results are empty).

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. The description adds real behavioral value by disclosing that results are returned in the business's custom arrangement rather than a default alphabetical or ID order. The endpoint reference is minor extra context.

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

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

Two short, front-loaded sentences with zero waste. The key scoping detail (custom ordering) comes before the 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 simple read-only list operation, annotations cover the safety profile, the schema covers pagination, and the description covers the ordering behavior. The only missing element is a brief note on the shape of returned category objects, but without an output schema this is a minor gap for an invocation decision.

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 fully documents page and per_page, including defaults, ranges, and the pagination.next_page hint. The description adds no parameter-level meaning beyond what the schema already provides, which makes the baseline 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?

States a specific verb and resource (list service categories) plus a meaningful scope detail (ordering set by the business). This clearly distinguishes the resource from sibling list_tools like list_services, though it does not explicitly name or contrast an alternative.

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 provides no guidance on when to use this tool versus alternatives, no prerequisites, and no conditions. An agent must infer its usage from the name alone.

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 still adds real value: the underlying endpoint (GET /v3/services) and the exact shape of the returned records, so an agent knows what it will get back and that service ids feed booking flows. It does not cover rate limits or total-count 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 front-loaded sentence carries the resource, the returned fields, and the workflow rationale, followed by the bare endpoint as a compact trailer. 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 read-only paginated list with full schema coverage and clear annotations, the description supplies everything an agent needs: what it lists, what fields come back, and why the ids matter. Absence of an output schema is offset by the inline field enumeration.

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 page, per_page, and provider_id are already fully documented, including the 'pass pagination.next_page' guidance. The description mentions no parameters at all and adds nothing beyond the schema, which is the baseline-3 case.

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

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

States a specific verb ('List') and resource ('services'), clarifies the domain vocabulary with '(treatments, classes, sessions)', and enumerates the fields returned. It does not explicitly say how it differs from close siblings like agendapro_get_service or agendapro_list_service_categories, 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?

The line 'Service ids are needed to book' is an implicit workflow cue pointing at create_booking, but there is no explicit when-to-use/when-not framing and no named alternative for looking up a single service or browsing categories. 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, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds useful behavior: results are ranked, the list is short, and each hit carries id, full name, email, phone (valuable since there is no output schema). It does not address what happens on zero matches or how ranking is computed, so it is solid but not rich.

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

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

Two compact sentences, front-loaded with the action and match surface, followed by the result shape and the endpoint. No filler, nothing redundant with the schema.

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 ranked/short nature of the result, echoing the schema's 1-25 limit. Minor gaps: no zero-result behavior and the ranking rule is unspecified, but an agent has enough to call it correctly.

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 earns a bump by explaining what q actually matches against (name, email, phone, identification or record number), which the schema's 'Search text' does not convey. The limit parameter's effect is left to the schema, which documents it fully.

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 (find clients), enumerates the matchable fields (name, email, phone, identification number, record number), and frames the outcome (a short ranked list to obtain a client_id). This is clearly differentiated from agendapro_list_clients (browse full listing) and agendapro_get_client (fetch by id).

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

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

'The fastest way to get a client_id' gives a concrete use case that tells the agent when to pick this over fetching or listing. It stops short of naming the sibling tools or stating exclusions, so the routing is implied rather than explicit.

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

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

Annotations supply destructiveHint=true and idempotentHint=true, but the description adds real behavioral context: partial-update merge semantics, merchant customer policy enforcement, and the 422-no-retry rule. It does not say what is lost when a time is moved (notifications, existing resource assignment) despite destructiveHint being set, and the no-retry rule sits slightly awkwardly against idempotentHint=true.

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 paragraph; every clause earns its place (scope, partial-merge rule, policy refusal, retry prohibition, endpoint). No filler or restatement of the title.

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 11 parameters, no output schema, and annotations that already declare the safety profile, the description covers the operation's semantics and failure mode well. The gaps are the two unmentioned scalar ids (client_id, time_resource_id) and any hint about what the response returns after the PATCH.

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 55%, and the description compensates for the unlabeled fields by grouping them semantically ('move it, switch service/provider/location, change status, price or notes'). However, client_id and time_resource_id get no mention in the description, and no format or constraint detail is added 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?

Opens with an explicit operation class ('WRITE') and a specific verb+resource ('change an existing booking'), then enumerates the dimensions of change (time, service/provider/location, status, price, notes). This is clearly distinguishable from siblings like agendapro_create_booking and agendapro_cancel_booking.

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?

States the key usage rule explicitly — partial update, only passed fields change — and gives a hard operational directive for the policy refusal (HTTP 422, do not retry). It stops short of naming alternatives for overlapping cases, e.g., that status changes cancelling a booking might belong to agendapro_cancel_booking.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds the crucial PATCH semantic ('only the fields you pass change') and warns that supplied values overwrite stored ones. It does not mention how to clear a field, permission requirements, or the response body, so it is good but not exhaustive.

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

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

Two compact clauses; the WRITE marker and partial-update rule are front-loaded, and the endpoint path is appended where it is easy to skim. 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 16-parameter mutation with no output schema, the description covers the highest-risk ambiguity (partial vs full replacement) and defers field-level detail to a fully documented schema. Missing are auth/prerequisite notes and whether custom_attributes are replaced wholesale, but nothing that would cause a wrong call.

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

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

Schema description coverage is 100% and every one of the 16 parameters is documented there, including the empty-string-clears behavior and enum-style gender codes. The description adds no parameter-level detail beyond the general 'fields you pass change' rule, 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?

Starts with an explicit WRITE marker, names the specific verb and resource ('change an existing client'), and pins the exact endpoint (PATCH /v3/clients/{id}). This separates it cleanly from agendapro_create_client and agendapro_get_client in the sibling list.

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 word 'existing' plus 'partial update' tells an agent this is the modify path, not the create path, and that omitted fields are left alone. It stops short of naming the alternatives (create_client vs update_client) or stating prerequisites such as needing a valid client_id first.

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