Healthie MCP by usefulapi

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

The annotation set only carries destructiveHint=true with no readOnly/idempotent hints, so the description must add behavioral context and does contribute the 'additive' framing and the underlying GraphQL mutation name. It says nothing about authentication requirements, whether the caller must be an org member for org_chat, or what happens on duplicate content. No outright contradiction with destructiveHint=true, since creating a record does mutate state.

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 compact sentence front-loads the action and the required argument, followed by the mutation signature. The trailing GraphQL fragment is extra but cheap and can aid debugging; nothing is padded.

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

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

All three parameters are documented and there is no output schema to explain, so the basics are covered. For a write tool with only a destructiveHint annotation, an agent still lacks the return value (e.g. the created note id), permission prerequisites, and confirmation that this is the correct entry point for chat versus note content.

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 schema already documents content, user_id and org_chat. The description restates these (required content; optional client or org-chat attachment) and usefully equates user_id with 'client', but adds no format, validation, or edge-case 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 description opens with a specific verb and resource ('Creates a note/chat entry in Healthie') and adds the qualifier '(additive)', which pins down the write semantics. It is clearly distinguishable from the read-only get_/list_ siblings, though it never contrasts itself with the nearest write sibling, healthie_create_task.

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 hints at the two usage contexts (a note about a client via user_id, or an organization chat via org_chat), which implies when each mode applies. However there is no explicit when-to-use/when-not guidance and no routing against healthie_create_task or the conversation/document 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?

The description's framing as "additive" conflicts with the annotation destructiveHint: true — under MCP semantics, an additive tool is exactly the case where destructiveHint should be false. The description does add some behavior (required content, optional attachments), but its safety framing directly contradicts the structured annotation.

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

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

Two tight sentences with the purpose front-loaded before the parameter list and GraphQL mapping. Every clause carries information; nothing is padded.

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

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

For a simple create tool with full schema coverage and no output schema, the description covers purpose, required vs optional inputs, and the underlying GraphQL mutation. The main gap is the undermined safety context, but operationally an agent has what it needs to call 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 all five parameters are already documented with types and meaning. The description mainly restates them (content as text, user_id as client, due_date, priority, created_by_id) and adds the required/optional grouping, which is marginal value beyond the schema — the 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?

"Creates a task in Healthie" gives a specific verb + resource, and the parenthetical "(additive)" distinguishes it from update/delete operations. It does not explicitly name list_tasks or create_note, but the create-vs-list and task-vs-note distinction is inherent enough for an agent to route correctly.

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 conveys implied usage by enumerating what is required (content) versus optional (user_id, due_date, priority, created_by_id). However, it never states when to reach for this tool over a sibling, nor any when-not condition or prerequisite, so guidance stops short of being 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?

The readOnlyHint annotation already declares the safety profile, and 'Read-only' in the description largely repeats it. The description does add useful context that the identity comes from the API key and that this call doubles as an auth check, but it says nothing about behavior on an invalid key or what the account payload contains. With annotations carrying the safety burden, 3 is appropriate.

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

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

Three short sentences with zero filler, and the identity of the resource is front-loaded ahead of the usage hint. Nothing could be cut without losing content.

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-parameter, read-only tool with no output schema, the description covers what it returns conceptually (the authenticated account) and how to use it. It does not enumerate the fields the account object carries, which is the only remaining gap, and that omission is minor given the tool's simplicity.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing to document beyond the implicit fact that the account is derived from the API key, which the description does state, so no compensation is required.

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

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

The description names a specific verb and resource ('Fetch the authenticated Healthie account') and pins down identity with '(the provider/user that owns the API key)'. That parenthetical is what separates it from the sibling healthie_get_user, which retrieves an arbitrary user rather than the caller. An agent can choose between them without opening either schema.

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

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

It gives an explicit when-to-use context: 'Good first call to verify auth.' That is a clear situational cue for an agent starting a session. It stops short of an explicit exclusion ('use healthie_get_user when you need another user's record'), so it lands at 4 rather than 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?

The annotations already declare readOnlyHint=true, so the description's 'Read-only' adds nothing new, and the 'GraphQL: query appointment(id)' detail is an implementation note rather than agent-relevant behavior. It says nothing about return shape, auth scope, or error behavior for a nonexistent id.

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 fragments with the core action front-loaded and no filler. The trailing GraphQL line is largely waste for an agent, which keeps this 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?

There is no output schema, so the description carries the burden of hinting at what comes back, and it does not. For a one-parameter read tool with annotations covering safety, it is adequate but leaves the return value and failure mode 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 sole parameter's schema already says 'The appointment id.' The description's 'by id' restates rather than extends that, so the high-coverage 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 states a specific verb ('Fetch') and resource ('a single appointment') and constrains it to lookup by id, which cleanly distinguishes it from the sibling healthie_list_appointments. It stops short of naming that sibling, so it is clear but not fully 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' tells the agent it needs a known identifier, and 'single' implies it is not for enumeration. No explicit when-to-use statement or reference to healthie_list_appointments as the alternative for browsing.

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

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

The annotation already declares readOnlyHint=true, so the description's 'Read-only' is largely a restatement. It does add modest value by disclosing the returned field set and mapping to the underlying 'query organization' GraphQL operation, but says nothing about permissions, whether it errors/null-returns when no org exists, or scoping.

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

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

Three compact fragments with the core verb+resource front-loaded and no filler. The trailing 'GraphQL: query organization' is borderline implementation trivia that an agent doesn't need, keeping this just short of ideal.

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 input schema fields, no output schema, and only a readOnly annotation, the description usefully compensates by listing the returned fields. It is nearly complete for a simple getter, though it omits edge-case behavior such as what is returned when no organization is configured.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter syntax or meaning for the description to clarify. Nothing here misleads about inputs.

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 concrete verb ('Fetch') and resource ('current organization / practice') and enumerates the returned fields (name, NPI, contact, user counts). No sibling tool name overlaps with 'organization', so an agent can immediately separate it from healthie_get_user and healthie_current_user.

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 explains what the tool returns but never says when to reach for it versus alternatives such as healthie_current_user or healthie_get_user. For a zero-argument tool the usage is somewhat inferable, but the definition itself offers no routing guidance or exclusions.

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

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

The annotations already declare readOnlyHint=true, and 'Read-only' merely restates that. The only added behavioral detail is the GraphQL mapping 'query user(id)', which aids implementation understanding but says nothing about not-found behavior, permissions, or which user types are actually resolvable.

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, all front-loaded with the core action first and zero filler. Every sentence carries distinct information (purpose, safety, call mapping).

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 covering safety and no output schema, the description is nearly sufficient. The minor gap is that it does not hint at what the returned user object contains or whether the id namespace is shared between patients and providers.

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 id parameter is documented in the schema, so the baseline is 3. The description's only added semantic is that the id may identify a patient or a provider, which is marginal value over the schema.

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

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

States a specific verb and resource ('Fetch a single user') and clarifies that the entity may be a patient or a provider, which helps separate it from healthie_list_patients and healthie_current_user. It does not explicitly name those siblings, so differentiation is implicit rather than stated.

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

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

'by id' plus 'Read-only' implies this is the lookup path when you already have a user id, and the singularity of the fetch rules out the list tools. However, it never states when to prefer this over healthie_current_user or healthie_list_patients, and gives no preconditions.

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 the description simply repeats 'Read-only', which earns no credit. It adds the underlying GraphQL query signature but discloses nothing about pagination, result limits, default date behavior (the 'future' default lives only in the schema), or result shape. With no output schema, behavioral disclosure is thin.

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

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

Two compact sentences: purpose and filter dimensions first, then the read-only and GraphQL details. Every clause carries information and nothing is padded.

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

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

For a six-parameter list tool with no output schema and no required args, the description covers what can be asked but not what comes back — no mention of pagination, ordering, or result fields. Adequate but with a visible gap for an agent planning to consume the results.

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 each parameter is documented with its accepted values in the schema itself. The description's GraphQL argument list merely restates the same names without adding syntax, defaults, or interaction rules, 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?

Names a specific verb and resource ('List appointments') and enumerates the filter dimensions available, which clearly separates it from the singular sibling healthie_get_appointment. It never explicitly contrasts itself with siblings, 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?

The phrase 'optionally filtered by patient, provider, date range, time-filter or status' implies when the filters matter, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative sibling. 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?

The 'Read-only' claim simply restates the readOnlyHint=true annotation, earning no extra credit. The GraphQL signature reveals the backing query and a should_paginate arg not present in the schema, which is mildly informative, but no return-shape, default-result-count, or truncation behavior is disclosed.

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 clauses with the core purpose front-loaded and no filler. The trailing GraphQL signature is arguably redundant with the schema, but it costs little and keeps the definition compact.

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, zero-required-param read tool with no output schema and full schema coverage, the description covers what is listed and how to filter. An agent has enough to invoke it correctly, though nothing explains result ordering or 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 schema fully documents offset, page_size, and keywords, including defaults. The description only echoes the parameter names in the GraphQL signature and adds no syntax, format, or matching semantics beyond the schema.

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

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

States a specific verb and resource ('List the practice's appointment types (services)') and clarifies domain terminology by equating appointment types with services. It is distinguishable from siblings like healthie_list_appointments, though it never explicitly contrasts with them.

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 mention of optional keyword filtering implies how the tool is typically used, but there is no explicit when-to-use/when-not guidance or reference to alternative tools (e.g., healthie_list_appointments for actual bookings). Usage is inferable but not 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?

The only behavioral claim is 'Read-only', which merely restates the readOnlyHint=true annotation already provided. The description adds no context beyond structured data—no pagination, ordering, result limits, or auth requirements for a tool with 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?

One sentence of purpose plus a short scope note, with the core action front-loaded. Nothing is padded; even the GraphQL hint is compact and informative.

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-optional-parameter read-only list tool with no output schema and annotations covering safety, the description gives enough to call it correctly. It lacks any note on result volume/pagination, which is the only 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 100%, so the baseline is 3, but the description adds genuine meaning: the phrase 'optionally between the current user and a given user' communicates that omitting user_id widens the scope, which the schema field text alone ('between the current user and this user id') does not state.

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 messaging conversations') and clarifies the scoping option. It is clearly distinguishable from the sibling list_* tools (patients, appointments, tasks, documents) by resource. It stops short of explicitly naming a sibling alternative, so it does not reach 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?

'optionally between the current user and a given user' implies when to supply user_id versus omit it, giving implied usage context. There is no explicit when-not guidance, no mention of alternatives, and no prerequisites for this read call.

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

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

Annotations already declare readOnlyHint=true and the description simply repeats 'Read-only', earning no extra credit there. It does add the underlying GraphQL query shape, which is useful for debugging, but it omits behavioral traits such as pagination defaults/limits and what a page of results contains. Notably the GraphQL signature lists should_paginate, a parameter absent from the input schema, which an agent cannot act on.

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

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

Three short sentences with the scoping behavior front-loaded and no filler. The trailing GraphQL query restatement is mildly redundant with the schema but short enough to be defensible.

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 says nothing about the return shape (what a document record contains) or pagination totals, and it does not resolve the extra should_paginate parameter appearing only in the GraphQL string. For a simple read-only list tool keyed off annotations this is adequate but not complete.

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

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

Schema description coverage is 100%, so offset, page_size, keywords and viewable_user_id are already fully documented in the schema; that sets the baseline at 3. The description names viewable_user_id and keywords but adds no syntax, 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?

States a specific verb+resource (list documents) and adds the two optional scoping modes (patient via viewable_user_id, or keyword search), which is more than a restatement of the title. It does not explicitly differentiate itself from the many sibling list_* tools, though none of them overlap on the document resource, so confusion risk is low.

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

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

The description implies usage (scope to a patient, or search by keyword) but never states when to use this tool versus an alternative, nor any prerequisites such as required permissions or needing a patient context. For a zero-required-parameter list tool the implied context is workable but thin.

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

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

The readOnlyHint annotation already declares the safe-read profile, so 'Read-only' is largely redundant. It adds some value by exposing the underlying GraphQL query and its arguments, which hints at the supported filters and pagination, but says nothing about page size, result ordering, or volume of returns.

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

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

Two compact sentences, front-loaded with the core purpose then the filtering scope and the query mapping. No filler, though the third clause is mostly implementation detail an agent does not need to select the tool.

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

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

No output schema exists, so the description is not obliged to explain return values, and the schema fully documents the filters. The only gap is pagination behavior: an offset is accepted but no page size or default result count is described, so an agent cannot predict how much data comes back.

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 each of the three parameters is documented in the schema, so the baseline is 3. The description mirrors the same argument names in the GraphQL signature without adding format, default, or semantics beyond what the schema already states; it also lists should_paginate, which is not an exposed parameter.

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 (completed form submissions) and disambiguates the domain jargon by equating submissions with 'charting notes / filled intake forms'. This implicitly separates it from the sibling healthie_list_forms (templates), but the distinction is left to inference 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?

'optionally scoped to a patient or a form template' tells the agent the two filtering modes, which is real usage guidance. However, no alternative tool is named (e.g. list_forms for templates) and no when-not condition is given, so guidance remains implied.

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

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

The readOnlyHint annotation already declares the safety profile, and the description's 'Read-only' merely repeats it. It does add the underlying GraphQL query name and argument list, which is mild context for debugging, but says nothing about result caps, default page size behavior, or ordering 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?

Two short sentences plus a compact GraphQL reference, with the core purpose front-loaded before the filter and read-only notes. The GraphQL signature sentence is marginally useful and does not bloat the definition much.

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, filter-only list tool with 100% schema coverage, the description covers purpose, filters, and read-only status adequately. With no output schema present, it could have described the shape of returned form templates, which is the only 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 description coverage is 100%, so all four parameters (keywords, category, offset, page_size) are already documented in the schema. The description only restates keywords and category and omits the two pagination parameters, adding no meaningful semantics beyond the schema 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 gives a specific verb ('List') and resource ('custom module form templates'), and parenthetically clarifies the domain with 'charting notes, intake forms', which helps an agent map the ambiguous word 'forms'. It does not explicitly distinguish itself from the nearby sibling healthie_list_form_answer_groups, so it falls 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 'optionally by keyword or category' implies when the filters are useful, but there is no explicit when-to-use guidance, no exclusion criteria, and no pointer to an alternative tool (e.g. list_form_answer_groups) when the agent wants submitted responses rather than templates.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' in the description restates structured data rather than adding context. The GraphQL signature (query goals(user_id, offset, per_page)) discloses the underlying query and its argument shape, which is mild added value, but nothing about pagination behavior or return characteristics is described.

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

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

Three short clauses, front-loaded with the core action before the GraphQL detail. It is efficient, though 'Read-only' duplicates the annotation and the GraphQL signature is arguably schema echo rather than added value.

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 tool with full schema coverage and readOnlyHint annotations, the description is sufficient to invoke correctly. It does not explain pagination traversal beyond the offset/per_page defaults, but no output schema exists and the operation is low-risk, so the gap is minor.

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%: offset, user_id, and per_page are all documented with defaults and constraints in the schema. The description's GraphQL signature mirrors the same three parameter names without adding format, unit, or meaning beyond what the schema already 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 (List) and resource (goals) with an optional scope modifier, so the agent can distinguish it from other list_* siblings by resource alone. It does not explicitly name sibling alternatives, but the resource 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?

The phrase 'optionally scoped to a patient' implies the user_id filter is the main branching decision, which is useful context. However, there is no explicit when-to-use guidance, no exclusions, and no routing to related tools such as healthie_list_patients.

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

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

The description says 'Read-only', which merely restates the readOnlyHint=true annotation, so no credit for that. It does add useful context by naming the underlying GraphQL query and its argument signature, which helps an agent reason about the call shape, but it discloses nothing about pagination limits or result ordering 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 tight sentences with the scope stated first and the technical GraphQL mapping second. Nothing is wasted, though the parenthetical example list is marginally expendable.

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

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

For a read-only, zero-required-parameter list tool with a fully documented schema and no output schema, the description covers purpose, filters, and underlying query adequately. Only explicit pagination behavior in prose is missing, and the schema already carries the defaults and max of 500.

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 four parameters (offset, category, client_id, page_size) are already documented with defaults and bounds. The description only echoes the parameter names in GraphQL form, adding no new semantic detail. 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 tracked metric entries') and gives concrete examples (weight, blood pressure) plus the scoping dimensions. It is unambiguous what the tool returns, though it does not explicitly distinguish itself from other list_* 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?

'Optionally scoped to a client or a category' implies when each filter applies but gives no explicit when-to-use guidance, prerequisites, or named alternatives. 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?

The annotation already declares readOnlyHint=true, and 'Read-only' merely restates it. The added value is the underlying GraphQL query mapping (query users(...)), which aids debugging, but nothing is said about pagination behaviour, result limits beyond the schema caps, ordering, or what is returned when no matches exist.

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, zero padding, and the purpose plus filter scope is front-loaded before the technical GraphQL line. The 'Read-only' clause is redundant with annotations but 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 simple read-only list tool with fully documented parameters, no nesting, and no output schema to explain, the description covers what the agent needs to call it correctly. Only the absence of any note on return shape or pagination sequencing 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 description coverage is 100%, so all four parameters (offset, keywords, page_size, active_status) are already documented with defaults and bounds — baseline 3. The description only echoes the same argument names and notably lists a 'should_paginate' argument that does not exist in the input schema, which adds no usable 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 ('List patients/clients') with the filtering scope attached, and the resource is clearly distinct from every sibling (list_appointments, list_tasks, get_user, current_user). An agent can select this tool 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?

'Optionally filtered by keyword search or active status' implies the retrieval use case, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g., get_user for a single record, or any dedicated search tool). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' largely repeats structured data. The GraphQL signature ('query tasks(client_id, completed_status, offset, per_page)') does add useful implementation insight, but nothing is said about default ordering, result caps, or total counts for a list endpoint.

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

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

Two short sentences with the core behavior front-loaded and the API signature trailing. No wasted prose; the only questionable element is whether the GraphQL line earns its place for an agent that already sees 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?

For a read-only list tool with no output schema, the description covers filtering and pagination but omits anything about what a returned task looks like or how results are ordered. Combined with minimal annotations, this leaves small gaps an agent might want filled.

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 four parameters are already documented with defaults and constraints in the schema. The description only restates the parameter names inside the GraphQL signature and adds no format or value semantics beyond what the schema provides.

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

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

States a specific verb and resource ('List tasks') plus the two optional scoping dimensions (client, completion status). It clearly differentiates itself from unrelated siblings like healthie_list_patients or healthie_list_appointments, though it never explicitly points at healthie_create_task as the mutation counterpart.

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 'optionally scoped to a client or filtered by completion status' implies when each filter applies, which is useful context. However, there is no explicit when-to-use/when-not guidance and no named alternative tool for related needs (e.g. fetching a single task or creating one).

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