Nookal MCP by usefulapi

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

Annotations already declare readOnly/idempotent/destructive=false, so the safety profile is covered; the description still adds real value by disclosing Nookal's 60-day hard limit, that it books nothing, and the exact shape of each returned slot (date, 24h clinic-local start time, provider id, location id). It omits rate limits or pagination behavior for a potentially large multi-day result set.

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

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

A single dense paragraph that front-loads the main action and scope, with the 60-day constraint and read-only note placed early. Every sentence carries information, though the trailing GraphQL endpoint reference is nice-to-have rather than essential.

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

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

With no output schema, the description usefully enumerates the returned slot fields, and it covers the date-range constraint and optional filters. It leaves pagination/result-size behavior unaddressed for a query that can span 60 days, which is the only notable gap.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description names locations, practitioners and service but adds no syntax or format meaning beyond that, and never mentions slot_duration at all. 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 the free appointment slots per date between two dates') plus scope (max 60 days), clearly distinguishing it from nookal_list_appointments which returns booked appointments. An agent can tell immediately that this is a free-slot search.

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 useful context (60-day cap, optional location/practitioner/service filters, points to list_services for service_id) but never states when to choose this over a sibling like nookal_list_appointments, nor any exclusions or prerequisites.

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, idempotent and non-destructive, so safety is covered; the description adds genuinely new behavioral context that annotations cannot express — an explicit negative contract ('Health-fund, pension and online-booking codes are not returned') and the conditional side-effect of include_invoices. It stops short of noting pagination/volume limits, but the field-level disclosure is substantive.

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

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

Front-loads the operation and identifier, then the payload, then the negative contract — a sensible ordering in two sentences with no filler. Slightly dense in the field enumeration, but each item earns its place given there is no output 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 carries the burden of describing return contents, including what is deliberately omitted. Missing only secondary details like error behavior on a bad id or payload size, which is acceptable for a simple two-parameter 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 coverage is 100%, so the schema baseline is 3, but the description adds meaning on top: include_invoices is characterized as an optional 'summary of their invoices (totals and balances)' versus the base payload being a single client. That clarifies the trade-off of enabling the flag beyond the schema's field list.

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 one client (patient) by id') and enumerates the returned data surface (name, DOB, contacts, addresses, alerts, allergies, notes, occupation, referring doctor, treatment cases). The phrase 'one client ... by id' cleanly separates it from the sibling nookal_search_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?

The singular lookup 'by id' implies the post-search retrieval pattern, and the id provenance is only stated in the schema ('from search_clients'), not in the description. There is no explicit 'use this instead of X when Y' routing statement or exclusion guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so safety is covered. The description adds genuinely useful behavior context ('Dates are clinic local', GraphQL backing), but says nothing about result-set size, rate limiting, or the behavior of an unfiltered 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?

The tool's core action is front-loaded and the long parenthetical field list carries real information. The trailing fragment 'Nookal GraphQL: appointments.' is cryptic and contributes little, keeping 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 no output schema, the returned-field enumeration usefully substitutes for one, and the timezone note is valuable. However, for a 12-parameter tool with no required parameters, the description never explains default scope or paging behavior, which an agent needs before making an unfiltered call.

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

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

Schema description coverage is 100%, so every parameter is already documented and the baseline is 3. The description's filter list maps loosely onto the schema (client, practitioner, type, status) but adds no format or constraint detail beyond what the schema already provides.

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

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

The description gives a specific verb+resource ('List appointments'), enumerates the fields returned, and names the filter axes (date range, location, client, practitioner, type, status). It is unambiguous what the tool does, though it does not explicitly contrast itself with nearby siblings such as nookal_get_availability.

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

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

No when-to-use or when-not-to-use guidance is provided, and no alternative tool is named. The most important usage fact for a tool with zero required parameters — whether an unfiltered call returns every appointment in the clinic — is left unstated.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds only that results are filtered and which fields come back; it says nothing about pagination behavior or result volume beyond what the schema states.

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

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

Two sentences, no filler: the operation and returned fields come first, the filter dimensions second. The parenthetical field list is information-dense and earns its space given there is no output 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 usefully enumerates returned fields, and annotations handle the write-safety question. Pagination defaults live in the schema, so little is missing; only the absence of sibling routing keeps it 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% and every parameter already carries a description including limits (up to 100 ids, page_length 1-100). The description's mention of client/case/practitioner filtering maps directly onto case_ids, client_ids, and primary_provider_ids without adding format or syntax detail. 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 (treatment cases), plus enumerates the returned fields and the three filter axes. The resource is clearly distinct from sibling list_* tools (appointments, classes, invoices), though it does not explicitly name any sibling to avoid.

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 axes (client, case, practitioner) imply when the tool is useful, but there is no explicit when-to-use/when-not guidance and no routing against siblings like nookal_search_clients or nookal_list_appointments. Usage 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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the useful scoping fact that results are class definitions rather than sessions, but says nothing about pagination behavior or result volume.

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 with a parenthetical field list and no filler. The scope disambiguation is front-loaded immediately after the verb+resource, so nothing important is buried.

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

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

There is no output schema, so enumerating the returned fields in the description is genuinely valuable and compensates well. Combined with the scope clarification and full schema coverage, an agent has enough to call this correctly, though pagination expectations remain 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 five parameters (page, class_ids, page_length, location_ids, online_bookings) are already documented in the schema. The description only echoes 'location' and 'online-booking settings' as returned fields, adding no filter syntax or semantics beyond the schema — the baseline 3.

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

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

States a specific verb+resource ('List the class types offered') and enumerates the attributes returned (id, name, category, duration, price, location, online-booking settings). It also explicitly disambiguates scope — 'the class definitions, not individual sessions' — which is the key distinction an agent needs in this domain.

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 context is implied by the scope statement (definitions, not sessions), but no alternative tool is named and no when/when-not condition is given. With siblings like nookal_list_services and nookal_get_availability, an explicit contrast would have helped route the agent.

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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered by structured data. The description adds useful context about what is returned (line items, payments, totals, balance), but says nothing about pagination behavior or result-size limits beyond what the schema already carries.

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?

Purpose and filter scope are front-loaded, followed by the sibling routing hint; two sentences, no padding. The parenthetical field list is long but each item earns its place by describing the return shape in the absence of an output 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 usefully discloses the returned fields including nested line items and payments, and lists the available filter dimensions for a 7-param, all-optional tool. It is complete enough to call correctly; only pagination/ordering behavior is 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 all seven parameters (page, page_length, created_from/to with their time-boundary semantics, invoice_ids, location_ids, voided_only) are already documented. The description only restates the filter dimensions at a high level, adding no syntax or default details beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ('List invoices'), enumerates what each record includes (line items, payments, and the fields in parentheses), and scopes it to three filter axes. It also distinguishes itself from the sibling path for per-client invoices, so an agent can identify it without opening the schema.

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

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

Gives an explicit alternative and the condition that selects it: 'For one client's invoices use get_client with include_invoices.' That is real routing guidance, though it does not contrast with the other list_* siblings (payments, appointments) that could overlap with invoice-adjacent queries.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds non-obvious behavioral context beyond that: results are restricted to locations the API client was granted, which is a permission-scoping constraint the agent cannot derive from the schema or annotations.

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

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

Three short sentences, each earning its place: purpose plus returned fields first, then the dependency hint, then the permission caveat. Fully front-loaded with no filler.

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

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

For a no-required-param list tool with rich annotations and a 100%-documented schema, the description covers purpose, returned fields, permission scope and downstream dependency. There is no output schema, but the field list effectively substitutes for 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 description coverage is 100%, so page, page_length, active and location_ids are already documented in the schema. The description adds no filtering syntax or pagination guidance beyond what the schema provides, 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 ('List the clinic's locations') and enumerates the returned fields (id, name, address, time zone, active), so the agent knows exactly what it gets. It is clearly distinguishable from the other list_* siblings by resource.

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?

'Location ids are needed by most other tools' supplies a concrete reason to call this tool first, which is real usage context. It stops short of stating when not to use it or naming an alternative, but for a base listing tool there is no real alternative among siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the returned field set and the underlying 'Nookal GraphQL: payments' mapping, but says nothing about pagination behavior or result limits beyond what the schema already states.

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 core purpose and the filter scope. The trailing 'Nookal GraphQL: payments' backend note is minor and slightly redundant with the title, but nothing is bloated.

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, but the description compensates by enumerating the returned fields, and the annotations carry the safety/idempotency profile. Pagination parameters are covered by the schema, so only behavioral details like rate limits or result ordering are missing.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description only restates that filtering is by invoice or payment date, mapping loosely onto invoice_ids and date_from/date_to without adding format or semantics beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List payments received against invoices') and enumerates the returned fields (method, amount, date, reference, invoice, client, location), which implicitly separates it from the sibling nookal_list_invoices that lists the invoices themselves. An agent can tell what this returns 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 description notes filtering by invoice or payment date, but gives no guidance on when to choose this over nookal_list_invoices or other list tools, nor any prerequisites. It is pure capability statement with no when-to-use framing.

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, idempotentHint, non-destructive and openWorld, so the safety profile is fully covered. The description adds the GraphQL source mapping ('Nookal GraphQL: services') but nothing about pagination limits or result-set size, so it adds only modest value beyond structured data.

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

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

Two short, front-loaded sentences with the field list first and the chaining hint second; no filler. The trailing 'Nookal GraphQL: services' is compact but somewhat cryptic metadata that an agent cannot act on, a minor waste of budget.

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

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

With no output schema, the description usefully compensates by enumerating returned fields, and annotations carry the safety profile. Pagination and total-count behavior are left to the schema, and filter-to-result relationships are implied rather than stated, so it is solid but not exhaustive.

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% – each of the five parameters (page, page_length, service_ids, location_ids, online_bookings) has its own documented semantics and bounds. The description mentions output fields rather than filters, so it adds no meaning 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 and resource ('List the appointment types / services offered') and enumerates the returned fields (id, name, category, duration, price, location, online-booking settings). That level of specificity lets an agent distinguish it from list_classes, list_locations, and the other list siblings without opening schemas.

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 sentence 'Use a service id in get_availability' gives explicit downstream chaining guidance, which is genuinely useful context. It stops short of naming when NOT to use this tool or how it relates to list_classes, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine context by naming the fields returned and by disclosing that the ids are portable identifiers for other tools. It does not mention pagination behavior or default ordering, which would be the remaining behavioral 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 sentences, zero filler. The identification of what is listed leads, and the highest-value operational fact (id reuse across tools) follows immediately.

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

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

With no output schema, the description usefully compensates by enumerating the returned fields and by explaining the cross-tool role of the ids. Pagination defaults and ordering are left to the schema, which is acceptable for a read-only list tool, though a note on result size handling would fully close the gap.

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

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

Schema description coverage is 100%, so page, page_length, active, providers_only, online_bookings, staff_ids, and location_ids are all documented in the schema. The description's mention of provider / bookable online / active merely echoes those existing boolean filter semantics and adds no format or behavior detail beyond them. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('List staff members and practitioners') and enumerates the returned attributes (id, name, title, speciality, email, location ids, provider/bookable/active flags), so an agent knows exactly what this call yields. No sibling in the list produces staff data, so differentiation is implicit but 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?

Explicitly routes the agent downstream: 'Use the staff ids as provider_ids in list_appointments and staff_ids in get_availability.' That is clear chaining guidance not present in structured fields. It stops short of when-not-to-use guidance or which filters to prefer for a given intent, so it is not a full 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description still adds real context beyond them: the exact return fields (id, name, DOB, location, active/deceased flags, contact details) and the partial_match matching rule, which annotations cannot express.

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 with no filler: purpose and searchable keys first, return shape second, the tricky partial_match caveat third, and the GraphQL mapping last. Each sentence carries distinct 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 14 optional parameters, no output schema and read-only annotations, the description covers what matters: it lists the return fields to compensate for the absent output schema and pins down the partial_match semantics. Pagination defaults are left to the schema, which fully documents them, so the only real gap is the missing comparison to nookal_get_client.

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 and the schema carries the parameter documentation. The description adds meaning on top by naming the searchable fields and giving a concrete partial_match example ('Sm' finds Smith), clarifying behavior the schema states only abstractly.

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 (patients)') and enumerates the searchable keys (name, date of birth, mobile, email, id). It is clear what the tool does, but it never differentiates itself from the sibling nookal_get_client, so an agent must infer the search-vs-single-lookup split.

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 filter list signals 'search when you don't have the exact client', and the partial_match clause explains one filter's behavior. There is no explicit when-to-use/when-not guidance and no mention of the natural alternative (nookal_get_client) for retrieving a known client.

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