LovedOne Soft MCP

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds meaningful behavioral context beyond annotations: a copy is posted to a linked LovedOne family inbox, and notes may be health-related so only family-approved content should be recorded.

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 four short sentences, front-loaded with the core action and side effect. Each sentence contributes useful information without unnecessary detail.

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 write tool with annotations and no output schema, the description covers the key side effect and privacy consideration. It leaves minor gaps around permissions, error behavior, and the undocumented agencyId parameter.

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 75%, and the description does not add parameter-level meaning beyond the schema. It does not explain the agencyId parameter, which is the one parameter lacking a schema description.

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: "Logs a note on an agency client." It also clarifies the cross-posting behavior to a LovedOne family inbox, distinguishing this write tool from the read/list and scheduling siblings.

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

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

The description implies usage by saying it logs a note on an agency client and includes a privacy constraint for health-related notes. It does not explicitly state when to use this tool versus alternatives, nor does it name any sibling tool as an alternative.

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 establish that this is a read-only, idempotent, non-destructive, closed-world call. The description adds useful detail about the returned fields and authenticated-provider scope, but does not add much about auth behavior, multi-agency resolution, or error cases.

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 and return fields, followed by usage guidance. There is no unnecessary text.

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

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

For a simple read-only profile tool with rich annotations, a fully described schema, and no output schema, the description covers both the returned data and the intended usage context. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, and the single optional agencyId parameter is fully documented in the schema. The description does not mention the parameter or add semantics beyond the schema, so the baseline of 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?

The description uses a specific verb and resource and enumerates the exact fields returned: id, name, slug, plan, and caller role. This clearly distinguishes it from the sibling list/get tools without needing to inspect 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 gives a clear usage context: "Use this first when building a vendor dashboard." That tells the agent when to reach for this tool, though it does not name alternatives or explicit when-not conditions.

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

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

The annotations already declare this a safe, idempotent, closed-world read. Beyond that, the description discloses two useful traits: the response bundles recent visits/notes rather than returning a bare client record, and cross-agency requests fail rather than leaking or returning empty. It does not say how much 'recent' data is included.

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

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

Two short sentences, no filler, with the core purpose stated first and the failure condition appended. Nothing is redundant with the title.

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

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

For a read-only two-parameter lookup with no output schema, the definition covers scope, bundled data, and the authorization failure mode. The remaining gap is the semantics of 'recent' (window or count), which affects how the returned visits/notes should be interpreted.

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?

At 50% schema coverage, the schema documents clientId's origin ('Agency loved-one id from list_clients') but leaves agencyId bare. The description only indirectly touches agencyId through 'owned by this agency' and the cross-agency rejection rule, so the compensation for the undocumented parameter is partial.

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 ('Returns one client') and states the payload includes recent visits/notes. The singular 'one client ... owned by this agency' implicitly separates it from the sibling list_clients, but it never names that alternative outright.

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

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

Usage is only implied: fetch a single known client, presumably after list_clients supplied the id. The 'rejected if the client belongs to another agency' line hints at the eligibility precondition, but there is no explicit when-to-use or when-to-prefer-alternatives guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/non-open-world, so the safety surface is covered. The description adds real value beyond them: it says each row carries a linked-to-family-inbox flag and that emails of family members are withheld, which tells the agent not to expect contact details.

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, with the identity and scope stated first and the exclusions last. Every sentence contributes a distinct fact (scope, included flag, withheld data).

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 with one optional parameter and no output schema, the description covers scope, one notable returned field, and data exclusions. It stops short of saying what other fields appear per client or whether pagination applies.

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, including the 'required only if multi-agency' rule. The description adds nothing about agencyId, so the baseline 3 applies.

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

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

States a specific verb and resource ('Lists ... clients') and narrows scope to one agency's clients, explicitly excluding other agencies' clients and family-member emails. That scoping separates it from the singular get_client sibling, though the sibling is never named.

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

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

Usage is only implied: an agent can infer this is the enumerate-all endpoint versus get_client for a single record, but the description never states when to prefer one over the other or what prerequisite (multi-agency membership) triggers the agencyId parameter.

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 read-only, idempotent, non-destructive, but the description adds real domain semantics: these are ledger records and LovedOne does not move money, and payment handles are contact pointers rather than credentials. That prevents an agent from treating invoice data as a payment capability — context the annotations cannot supply.

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

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

Three short sentences, front-loaded with what is listed and what is returned, followed by two clarifying caveats. Every sentence earns its place; 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?

With no output schema, the description helpfully enumerates returned fields and clarifies the data's nature, but it leaves the two undocumented parameters underspecified — especially limit and any truncation/ordering behavior — which an agent needs to call it correctly.

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

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

Schema description coverage is 0% across two parameters, so the description must compensate and largely does not. 'This agency' hints that agencyId scopes the result, but limit (1-100) — including its default and whether results are truncated — is unaddressed in both schema and description.

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 with scope: invoices this agency issued to families, and enumerates the fields returned (amounts, status, assignment). No sibling overlaps on invoices, so no differentiation is needed, but the scope nuance ('this agency') is the only narrowing signal.

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 it should call this to see an agency's invoices, but there is no statement of when to prefer it over narrower lookups like get_client or when it is inappropriate. No prerequisites or pagination-triggered caveats.

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 this as a read-only, idempotent, non-destructive, closed-world operation. The description adds valuable context beyond annotations by warning that notes may contain health information logged by staff, which is important for an agent handling sensitive data; it does not, however, describe pagination 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 sentences with no wasted words. The primary listing behavior is front-loaded, and the health-information caveat follows naturally without bloating the description.

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 listing tool with rich annotations and no output schema, the description covers purpose, scope, and the sensitive nature of note content. It is nearly complete, though a brief mention of the limit/pagination behavior 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 only 33%, so the description must compensate. It clarifies that clientId is optional and scopes results to one client, and 'for this agency' implies agencyId, but it says nothing about the limit parameter or its maximum of 100.

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: it 'Lists LovedOne Soft visit/note events,' and it scopes that listing to the agency or a single client. This clearly distinguishes it from write-oriented siblings like add_visit_note and schedule_visit, though it does not explicitly name those alternatives.

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 for one client' gives useful scope context, but there is no explicit guidance on when to use this versus related tools, no when-not conditions, and no notes on pagination or the limit parameter. Usage is 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 readOnly, idempotent, non-destructive, and closed-world. The description adds useful disclosure beyond that: the exact response payload (pong, uid, tenant, auth method) and the 'No PHI' assertion, which is material in a healthcare-adjacent toolset. 'No side effects' is somewhat redundant with destructiveHint=false/idempotentHint=true.

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

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

Three short sentences, front-loaded with the tool's identity, then its return value, then its safety profile. Every sentence carries information an agent would want; 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?

No output schema exists, and the description compensates by enumerating what comes back. With annotations covering safety semantics and no parameters to explain, an agent has everything needed to call and interpret this tool.

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?

Zero parameters, so there is nothing to document and the baseline of 4 applies. The schema is a closed empty object and the description correctly implies no inputs are needed.

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: a smoke-test tool that returns 'pong' plus caller identity fields. This is instantly distinguishable from every sibling, which all operate on care data (inbox, family members, providers), so an agent can route to it without opening the schema.

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

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

'Smoke-test tool' makes the intended use case clear: verifying connectivity and auth. There is no explicit when-not guidance or named alternative, but no competing tool occupies this niche, so the implied usage is sufficient. It falls short of a 5 only because it doesn't say what a healthy vs. unhealthy result looks like.

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 the write/safe/closed-world profile, so 'This is a write' earns nothing, but the description adds genuinely non-obvious context: the record is stored as an agency_events entry with fixed type/status, and notes may contain health information (a sensitivity flag an agent should surface). It misses the natural follow-on of idempotentHint=false — that repeated calls create duplicate visits.

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?

Four short sentences, front-loaded with the core action and the accepted datetime formats. 'This is a write' is filler against annotations that already say so, but overall there is little waste.

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

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

With no output schema and a non-idempotent create, the definition should cover what a successful call returns or how to detect a duplicate, and it does not. The optional agencyId is left completely undocumented in both schema and description, so an agent cannot tell when to supply it.

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

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

Schema coverage is 80%, so parameters are largely self-documented. The description's scheduledFor guidance ('ISO-8601 datetime or Unix milliseconds') and the scheduledAt storage note restate what the schema already says, adding no new semantics; agencyId remains unexplained in both places.

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 and resource ('Creates a scheduled visit for an agency client') and pins the internal representation ('agency_events type scheduled, status scheduled'), which lets an agent distinguish it from add_visit_note and list_visits without opening a 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 implies the usage context (creating a new visit for an existing agency client) and points at list_visits as a verification path, but never states when to prefer this over siblings like add_visit_note, nor any prerequisite such as needing a clientId from list_clients first.

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