Semble MCP by usefulapi

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

Annotations already declare readOnly=false, destructive=false, and idempotent=true. The description reinforces the additive, non-removing semantics and tells the agent where ids come from, adding real context. It stops short of describing auth or response behavior, so a 4 rather than 5.

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

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

Two short sentences with zero waste, and the additive constraint is front-loaded alongside the provenance pointer.

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

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

For a simple two-parameter write tool with rich annotations and no output schema, the description covers purpose, id source, and additive semantics adequately. Minor gaps in permission or error behavior are excused by the annotations.

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 both parameters are documented in the schema. The description only restates the label_id provenance already in the schema, adding no new meaning. 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 (puts/adds) and resource (label on a patient), plus the provenance of the label id. It clearly distinguishes assignment from creation, though it doesn't explicitly name a sibling it replaces.

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?

"label ids from semble_list_labels" routes the agent to the right sibling for obtaining the required id, and "Adds only; nothing is removed" clarifies the operation's intent. No explicit when-not-to-use case is given, so it falls 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 readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds a non-obvious behavioral trait: the tool does not check for an existing patient, which is important for duplicate prevention; it still does not describe success/failure or return behavior.

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

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

Two sentences, front-loaded with the primary action and followed by the duplicate caveat. Nothing is wasted 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?

For a 12-parameter create mutation, the description covers purpose, duplicate-risk guidance, and points to the correct prerequisite tool. The remaining gap is that no output schema exists and the description does not explain what is returned on success, but the schema and annotations cover most invocation needs.

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

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

Schema description coverage is 100% and all 12 parameters, including required first_name and last_name, are documented in the schema. The description only says 'from the details you give' and adds no parameter-level meaning, so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource—'Creates a new patient record'—and adds scope '(personal data)' plus a duplicate-check caveat. It names the sibling semble_list_patients, so an agent can distinguish this from read/list tools 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?

It explicitly tells the agent to search with semble_list_patients first to avoid duplicates, which is a clear when-to-use and when-not-to-create rule. The alternative is named directly, leaving little 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?

Adds value beyond the annotations by spelling out the practical consequence of idempotentHint=false: 'Creates a new record each time it is called', warning against retry-driven duplicates. It doesn't cover permission requirements or failure behavior for invalid patient_id/assigned_to.

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, front-loaded with the action and the non-idempotency caveat at the end where it is most likely to be read as a warning.

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, yet the description never says what is returned (e.g. the new task id), which an agent needs for follow-up calls like semble_update_task. Safety metadata is covered by annotations, but the return contract is a real 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 already 100%, so the baseline is 3, but the description adds meaning the schema lacks: that assigned_to must be a staff user id sourced from semble_list_users and that patient linkage is optional. Field enumeration overlaps the schema but the id-sourcing hint earns the bump.

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: 'Creates a task in Semble'. It enumerates the supported fields, which makes the scope concrete and separates it in spirit from semble_update_task and semble_list_tasks, though it never names those siblings.

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

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

Gives an explicit prerequisite workflow: assigned_to requires a staff user id obtained via semble_list_users, which is genuine routing guidance. It stops short of stating when to prefer semble_update_task over creating a new task.

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, openWorldHint=true). The description adds the payload composition — patient, doctor, location, appointment type, status, journey — which is meaningful behavioral context given there is no output schema. It does not cover not-found or error behavior, so it stops short of full transparency.

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 sentence, front-loaded with the resource and retrieval key, with every clause (the field list) earning its place by substituting for a missing output schema. 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 single-parameter read tool with annotations and no output schema, the description supplies the main missing piece: what the returned booking contains. It omits failure behavior (unknown id, permissions), which keeps it from a 5.

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

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

Schema coverage is 100% with a single required 'id' parameter, so the schema carries the burden. The description only restates 'by id' without adding format, source, or validation detail, 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 resource ('One booking') and the access key ('by id'), which clearly separates it from sibling list tools like semble_list_bookings. It does not explicitly name the alternative, but the singular/plural contrast makes the intent 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?

'by id' implies the precondition that the caller must already hold a booking id, and the singular framing distinguishes it from the list siblings. However, there is no explicit when-to-use guidance or pointer to semble_list_bookings for discovery, so routing is left to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered; the description adds real value by disclosing the shape of the response (line items, computed totals, outstanding balance), which an agent cannot get from annotations or an absent output schema. It does not mention not-found or error behavior, which keeps it below a 5.

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

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

A single clause with zero filler, and the key information (which record, what comes back) is front-loaded.

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

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

For a simple read-only lookup with full schema coverage, the description supplies the missing piece — the contents of the returned invoice — which stands in for the absent output schema. Only edge-case behavior (invalid id, empty invoice) is left 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?

With one parameter at 100% schema coverage, the schema already documents 'Invoice id.'; the description only reiterates that lookup is keyed by id. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

States a specific verb and resource (fetch one invoice by id) and enumerates the payload (line items, totals, outstanding), which cleanly separates it from semble_list_invoices. It stops short of naming the list sibling 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 this is the single-record lookup and that liste_invoices is the bulk alternative, but the description never says when to prefer one over the other or what to do if the id is unknown. Usage is inferable but not guided.

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 the safety profile is covered. The description adds valuable substance beyond that by spelling out the returned data categories, which matters because there is no output schema. It stops short of noting behavior on unknown ids or cross-practice access implied by openWorldHint.

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 action and scope, followed by the sibling exclusion. No redundant restatement of the title or annotations.

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 with full schema coverage and no output schema, the description's enumeration of returned fields fills the largest gap. Minor omissions remain: behavior for a nonexistent id and pagination/absence of it are unstated, though neither is critical here.

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

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

Schema description coverage is 100% and the single parameter's schema text already says where the id comes from (semble_list_patients). The description adds no format or constraint detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource (fetch one patient by id) and enumerates the concrete data returned: demographics, phones, address, numbers, custom attributes, labels, comments, status. It also explicitly scopes out appointments, invoices and tasks by noting they have their own tools, so an agent can distinguish it from siblings like semble_get_invoice or semble_list_patient_bookings.

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

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

The closing sentence routes the agent away from this tool for appointments, invoices and tasks, which is real exclusion guidance. However, it does not contrast with semble_list_patients (the natural alternative for finding patients) nor state any prerequisite such as needing a valid id first — the schema carries that hint instead.

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 meaningful context beyond that: results are scoped to the calling token's practice, and the call doubles as a connection/auth sanity check. It does not state what happens with an invalid token, but the added scope/auth framing 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?

Two short sentences: the first front-loads what the resource is and what it contains, the second gives the usage hint. No filler, no redundancy.

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

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

There is no output schema, so the description carries the return information—and it does, by listing the returned fields. For a simple zero-arg, read-only getter with annotations covering safety, nothing essential is missing.

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

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

The tool takes no parameters, and the schema is empty, so there is nothing for the description to disambiguate. A baseline of 4 applies for zero-parameter tools.

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

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

The description names the specific resource (the practice bound to the API token) and enumerates its contents: name, timezone, locations, appointment types, medical specialties. That clearly separates it from sibling getters like semble_get_user, semble_get_patient, or semble_get_invoice. It stops short of an explicit verb, relying on the title 'Get the practice' to supply it.

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

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

'A good first call to check the connection' gives an explicit, actionable context for when to reach for this tool—token/connectivity validation before other calls. No exclusions or named alternatives are provided, but for a zero-parameter root-object getter the guidance is sufficient.

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 does add one useful fact — the id space covers products, services and appointment types, not just products — but says nothing about behavior on a missing id or what the record contains.

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

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

A single nine-word fragment with nothing superfluous, and the resource is front-loaded. It is under-specified rather than bloated, so brevity itself is not the problem.

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 annotations and full schema coverage this is close to sufficient, but the agent is left guessing what distinguishes an invalid id from an id belonging to a different entity type, and whether the response includes related records.

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 the schema already documents it at 100% coverage ('Product id.', minLength 1, maxLength 100). The description's 'by id' repeats the schema rather than adding format, source, or lookup semantics. 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 fragment names the resource (product, service or appointment type) and the retrieval key (id), and 'One' implicitly distinguishes it from the sibling semble_list_products. But there is no verb, so the agent must infer 'retrieve a single record' rather than being told it.

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

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

There is no statement of when to use this tool, when not to, or any pointer to semble_list_products for browsing versus fetching a known id. The only hint is the word 'One'.

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 structurally. The description adds nothing beyond that: it doesn't mention what happens on a missing/invalid id, permission requirements for staff records, or what fields come back — notable since there is no output schema.

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

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

Five words with zero filler and the identifier key is front-loaded, so nothing is wasted. However, the brevity crosses into under-specification rather than efficient communication for a tool the agent must select among 18 siblings.

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?

The tool is structurally simple (1 required param, full schema coverage, read-only annotations), but with no output schema the description is the only place return shape could be described and it says nothing. Nor does it clarify the staff-vs-patient distinction that the sibling set makes necessary.

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 sole 'id' parameter is documented in the schema, so the baseline of 3 applies. The description only echoes 'by id' and adds no format, prefix, or sourcing detail beyond the schema.

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

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

The phrase 'One staff user by id' does signal a single-record retrieval keyed by id, which implicitly separates it from semble_list_users. But it is essentially a compressed restatement of the title 'Get a user (staff)' rather than a statement of action with scope or return semantics, leaving the agent to infer the verb.

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

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

There is no explicit guidance on when to use this versus semble_list_users or semble_get_patient — the agent must infer the contrast purely from the word 'staff'. No prerequisites, no conditions, no stated alternatives.

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 and openWorldHint, and the description adds meaningful behavior: the overlap semantics for date ranges and the journey states returned. It does not mention pagination constraints, deleted-record handling, or permissions, so it is helpful but not fully transparent.

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

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

Two tightly written sentences with no waste. The scope and date semantics are front-loaded, and the return fields are listed compactly.

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

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

For a read-only list tool with a fully documented schema and no output schema, this is nearly complete: scope, date-range behavior, and returned fields are covered. The only gaps are explicit guidance on alternatives and pagination behavior, which the schema largely handles.

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 does add the non-obvious overlap rule for start/end, but it says nothing about page, page_size, or include_deleted beyond what the schema already documents.

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 identifies the resource (bookings/appointments) and its scope ('the whole practice'), which implicitly separates it from semble_list_patient_bookings. It doesn't name that sibling explicitly, but an agent can still infer the difference in scope.

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

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

It explains the date-range inclusion rule (starts or ends inside the range), which is useful context, but it never says when to use this instead of semble_list_patient_bookings or semble_get_booking. Usage is implied (practice-wide listing) 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 openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context by enumerating which fields `search` matches against (name, email, phone, specialty and numbers), but says nothing about pagination behavior or result ordering, which matter for a paged list.

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, with the resource definition front-loaded and the search behavior immediately after. Every clause carries information.

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

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

No output schema exists, so the returned record shape is left implicit, and pagination defaults live only in the schema. For a simple read-only list tool with full schema coverage, the description plus schema are nearly sufficient; a note on what a contact record contains would close the remaining 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 the baseline is 3, and the description earns a bump by specifying the search fields that 'Free-text search.' does not convey. It still does not clarify whether is_payor and is_doctor are mutually exclusive or whether they can be combined with search.

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

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

The description names the resource and defines what a contact is in this domain (referring doctors, insurers and other payors), which distinguishes it from semble_list_patients and semble_list_users. It does not itself state the verb 'list', relying on the tool name to carry that, but the resource definition is specific and unambiguous.

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

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

Usage is implied: fetch contacts, optionally narrowing by free-text search or by the is_payor/is_doctor flags. There is no sibling that performs the same listing, so no routing guidance is strictly needed, but the description never states when to prefer search over the boolean filters or how they combine.

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 genuinely useful behavior context (what fields come back, that amounts are in the practice currency), but omits sort order, default range behavior, and total/result limits for an open-world list.

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, both front-loaded with the highest-value information: scope first, then filters, then the currency caveat. No filler or redundancy.

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

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

With no output schema, the description usefully discloses the return shape (patient, totals, outstanding). For a six-parameter paginated list it is nearly complete, but the default behavior when no date range is supplied is left unexplained.

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

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

Schema coverage is 100%, so the baseline is 3. The description contributes one real clarification — that the start/end filters apply to the invoice date specifically — but otherwise restates the status and paid_or_outstanding enums without adding meaning beyond the schema.

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

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

The description names a specific verb+resource (list invoices), defines the scoping dimension (invoice date within a range), and previews the returned fields (patient, totals, outstanding). It is clearly distinct from the singular semble_get_invoice sibling, 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 filter dimensions mentioned (status, paid_or_outstanding), but the description never says when to use this list versus semble_get_invoice or semble_list_patient_bookings. It also doesn't say what happens when start/end are omitted, which matters since all six parameters are optional.

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 the safety profile is covered. The description usefully discloses the returned fields (id, title, colour), but it says nothing about pagination behavior or whether the full label set is returned, which matters given page and page_size parameters.

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

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

Two short sentences with zero waste. The resource and returned fields come first, and the actionable next step (use the id with semble_add_patient_label) follows.

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 small read-only list tool with no output schema, the description compensates by naming the returned fields and the key identifier to use downstream. The only material gap is pagination semantics, which the schema partially covers.

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, search, and page_size are fully documented in the schema. The description adds no additional meaning about how searching or paging interacts with the returned labels, leaving it 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?

The description names the specific resource ('labels that can be put on patients') and the fields returned (id, title, colour), which makes it distinguishable from siblings like semble_add_patient_label. The verb 'list' is only implied via the title rather than stated explicitly, keeping it just shy of a 5.

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

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

It gives a clear downstream use case ('Use the id with semble_add_patient_label'), which implies when to call it — before adding a label. However, it does not say when not to use it, does not mention the search parameter as a way to find a specific label, and does not address alternatives.

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 that both dates are mandatory and what fields are returned, but says nothing about the cancelled/deleted behaviour that the schema exposes (include_deleted, only_cancelled) or about pagination defaults.

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

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

Two sentences, scoped and front-loaded with the resource and the date constraint. Slight redundancy in repeating the YYYY-MM-DD format that the schema already enforces keeps it below 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 seven parameters, no output schema and read-only annotations, the description usefully enumerates the returned fields and flags the required date window. It could be more complete about how cancelled bookings are handled and how this differs from semble_list_bookings, but nothing critical to a correct call is missing.

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

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

Schema description coverage is 100%, so every parameter is already documented, including the deleted/cancelled semantics. The description's only parameter content – both dates required, YYYY-MM-DD – merely restates the schema and required array, adding no syntax or edge-case detail.

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

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

The description names the resource ('bookings (appointments)'), scopes it to one patient, and enumerates the fields carried back (doctor, location, type, status). This implicitly distinguishes it from the sibling semble_list_bookings (broader listing), 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 only implied via 'of one patient' – an agent can infer you need a patient_id and a date window. There is no explicit when-to-use statement, no exclusion, and no pointer to semble_list_bookings or semble_get_booking as alternatives.

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 real value on top: it flags that records contain personal and health data, enumerates the returned fields, and discloses the `pageInfo.hasMore` pagination signal – behavior that is not visible anywhere else given there is no output schema.

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

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

Three short sentences, zero filler: resource first, then filter behavior, then return shape and pagination. Every sentence carries information an agent needs to call or interpret the result correctly.

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 takes on the return-value burden and does it: fields returned, the data sensitivity, and how to detect more pages. Combined with the fully documented input schema, an agent has everything needed to invoke it and interpret the response.

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 three parameters (page, search, page_size) are already documented with defaults in the schema. The description restates the searchable fields rather than adding new semantics, so it earns the baseline 3 for a fully covered 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?

The description names the resource (patients of the practice) and the operation (list, optionally filtered by `search`), and the search fields are spelled out. It is clear what the tool returns, but it does not explicitly distinguish itself from the single-record sibling `semble_get_patient` or from `semble_list_contacts`.

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 sentence about what `search` matches, which tells an agent when the filter is appropriate. There is no explicit when-to-use/when-not guidance and no reference to the sibling tools that would be preferred for single-patient lookup or other entity lists.

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 the safety profile is covered. The description adds genuinely useful context beyond that by enumerating what each row contains (price, cost, duration, stock level) and explaining the search matching rule, though it says nothing about ordering or pagination behavior.

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

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

Two sentences, front-loaded with the resource identity and followed by the one operational detail an agent needs about search. No filler and nothing buried.

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

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

With no output schema, describing the returned fields (price, cost, duration, stock level) is exactly the right compensation, and the search behavior is clarified. What's missing is pagination guidance — how to page through a large catalog — which matters for a list endpoint with a 100-row cap.

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 schema already documents page, page_size and search with defaults and ranges. The description's note that `search` matches the item code or name restates the schema's 'Item code or name' almost verbatim, so it adds little beyond the structured field.

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

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

The description names the resource concretely ('the practice's price list: appointment types, services and stock items') and lists the fields returned, which lets an agent distinguish this list call from semble_get_product. It never says 'list' explicitly, but 'price list' plus the enumerated item categories makes the operation unambiguous.

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

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

Usage is only implied: an agent can infer this is the way to enumerate catalog items, but the description never states when to use this versus semble_get_product for a single item, nor mentions that results are paginated so repeated calls may be needed. No exclusions or alternatives are given.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuine value by naming the returned fields (subject, due date, priority, assignee, patient) in the absence of an output schema, though it says nothing about pagination behavior or result ordering.

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

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

Two tight sentences: capability plus filters first, return shape second. 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 seven optional params, an output schema absent, and annotations covering safety, the description covers the essentials by stating both filter scope and the fields returned. Pagination defaults are left entirely to the schema, which is acceptable but slightly thin for a list endpoint.

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

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

Schema description coverage is 100% and all enum values are documented, so the schema carries parameter semantics. The description only restates the filter dimensions (patient, status, priority, type, assignee) without adding format or combination semantics, 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 resource (practice tasks) and the supported filter dimensions, so an agent knows this is a filtered read of the task collection. It does not explicitly distinguish itself from semble_create_task or semble_update_task, but the list/filter framing is unambiguous.

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

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

Usage is implied by the filter enumeration — an agent infers it should be called to browse or search tasks. There is no explicit statement of when not to use it, nor routing to alternatives such as semble_update_task for mutations or semble_list_patients for patient lookups.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds that staff include clinicians and admin and that ids are reused downstream, but says nothing about search behavior, pagination, or the include_deleted effect — context that would help an agent call it correctly.

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, resource definition front-loaded ahead of the workflow hint. Little waste, though the second sentence is more of a usage note than a purpose statement.

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

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

For a read-only list tool with full annotation safety coverage and 100% schema coverage, the definition is adequate. The enumerated return fields partly compensate for the absence of an output schema, leaving only minor gaps like pagination/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%, so the five parameters (page, search, page_size, clinicians_only, include_deleted) are fully documented in the schema. The description adds no parameter meaning beyond that, making the baseline 3 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?

The description identifies a specific resource — staff users of the practice (clinicians and admin) — and enumerates the fields returned, which distinguishes it from patient-facing siblings like semble_list_patients. It lacks an explicit list verb, leaning on the tool name, but the scope is unambiguous.

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

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

'Use the ids for bookings and tasks' gives a downstream workflow hint, implying this is the lookup step before create_task/list_bookings. However, it never states when to prefer this over semble_get_user or other list tools, so usage is only implied rather than spelled out.

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

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

Annotations already declare this as a write operation with destructive and idempotent hints, so the safety profile is covered. The description adds important behavioral context by stating that only passed fields are changed, which clarifies partial-update semantics, though it does not discuss permissions or reversibility.

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

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

The description is two sentences, front-loaded with the tool's purpose and followed by the key partial-update constraint. Every sentence earns its place with no redundant restatement of 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?

Given rich annotations, full schema description coverage, and no output schema, the description contains everything an agent needs to invoke the tool correctly. It explains the mutation scope, the fields affected, and the partial-update behavior without omitting critical invocation details.

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

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

Schema description coverage is 100%, so the schema already documents every parameter and baseline is 3. The description still adds value by mapping operations to parameters (e.g., close/reopen to status, reassign to assigned_to, notes to comments) and reinforcing that unspecified fields are untouched.

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 uses a specific verb and resource ("Changes a task") and enumerates the mutable fields, making the tool's scope unambiguous. The phrase "Only the fields you pass are changed" further distinguishes it from a create or list operation.

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 clearly indicates the situations in which the tool applies: closing/reopening, reassigning, changing due date, subject, priority, and notes. However, it does not explicitly name alternatives such as semble_create_task or semble_list_tasks, nor does it state exclusions or prerequisites.

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