LovedOne Family MCP

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

Adds real value beyond annotations: the code is short-lived and single-use, and the call is permission-gated to owner/coordinator. Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the 'This is a write' line is redundant but harmless. It leaves open what happens to a previously issued code when a new one is minted, which matters given idempotentHint=false.

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 action and output artifact, followed by the downstream use and the authorization gate. No filler; each sentence carries distinct information.

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

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

For a single-parameter write tool with no output schema, the definition covers purpose, audience, authorization, and lifespan of the code. The minor gaps are the return shape (does it return the code string, an expiry?) and the actual TTL of 'short-lived'.

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 description coverage ('loved one id from list_loved_ones'), the schema already carries the semantics, so the baseline is 3. The description adds only a mild constraint that the loved one must be in 'this household'.

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 precise verb+resource: mints a short-lived, single-use provider/vendor link code for one loved one in the household. That is clearly distinguishable from the read-oriented siblings (list_loved_ones, get_inbox_message) and from invite_family_member, which targets a different audience.

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 concrete when-to-use ('Hand the code to a LovedOne Soft agency so they can link that person as a client') and an explicit exclusion ('Owner or coordinator only — viewers are rejected'). It does not name a sibling alternative for adjacent cases, so it falls just short of 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 this as a safe read-only, idempotent operation. The description adds useful behavior beyond annotations: plaintext with no HTML, workspace rejection, and a PHI handling warning. It does not describe not-found or other error 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?

Four short sentences, each carrying a distinct operational fact. The most important details, return format and messageId prerequisite, are front-loaded with no 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?

For a simple read-only get tool with no output schema, the description covers return format, prerequisite, ownership enforcement, and PHI sensitivity. It is nearly complete, though error handling for missing or inaccessible messages is not detailed beyond workspace rejection.

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 both parameters are already documented. The description adds provenance for messageId, but lovedOneId is only indirectly covered by the workspace rejection note and the schema already calls it an ownership check.

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: returns one Family Inbox message. The singular scope and the requirement to get messageId from list_inbox_messages clearly distinguish it from the sibling list tool.

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?

Explains that messageId must come from list_inbox_messages and that workspace ownership is enforced. It gives clear context for use but does not explicitly state when not to use it versus list_inbox_messages or reply_to_inbox_message.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered; the trailing 'Read-only' is redundant. What the description does add beyond the structured fields is the shape of the returned state, including the presence of ordered nextSteps, which tells the agent the response is directional and should drive the next action.

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

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

Three tight sentences, front-loaded with the return contents, then the trigger condition, then the safety tag. No filler, no restatement of the title, and every clause carries either routing or payload 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?

There is no output schema, so describing the returned state is mandatory here and the description does it item by item, including ordered nextSteps. With zero parameters and rich annotations, nothing an agent needs in order to call this correctly is left out.

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 there is nothing to disambiguate and the baseline of 4 applies. The description correctly makes no claims about inputs and instead spends its words on output 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?

A specific verb ('Returns') plus a precise resource ('the caller's LovedOne setup state'), followed by an enumeration of exactly what is included: workspace existence, loved ones and @lovedone.app inbox addresses, member counts, and ordered nextSteps. That is enough to separate it from list_loved_ones or list_family_members, which return raw collections rather than onboarding state.

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 trigger and sequencing rule: 'Call this first whenever a user wants to set up, resume, or check on LovedOne.' That covers both the when and its position in the workflow. It does not name a sibling as the alternative for the non-onboarding cases (e.g. list_loved_ones for plain listing), so it stops just short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so safety is covered. The description adds meaningful value by enumerating the payload contents (uid, email, tenant type, linked family workspace), which substitutes for the absent output schema; it does not cover auth failure behavior or empty-workspace 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?

A single sentence with the verb and scope front-loaded and zero filler; every clause (returned fields) earns its place by compensating for the missing output schema.

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

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

With no output schema, the description's brief field listing is sufficient to tell the agent what comes back for a trivial zero-param read. Minor gaps remain around error/unauthenticated behavior and null-workspace handling, but nothing blocks 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is required by anchoring on the signed-in user, with no misleading parameter language.

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 ('Returns the signed-in user's LovedOne profile') and enumerates the returned fields, so the agent knows exactly what it retrieves. It does not explicitly contrast with siblings like list_family_members or list_loved_ones, but the 'signed-in user' scoping makes the distinction largely self-evident.

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

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

The phrase 'signed-in user's' implies the context in which this tool applies (current authenticated user, no arguments needed), but there is no explicit when-to-use/when-not guidance or named alternative for looking up other users' profiles. Usage is inferred 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=false and destructiveHint=false, so 'This is a write' is redundant but harmless. The description adds real value beyond annotations: required caller role, rejection of viewers, and the side effect of sending a LovedOne invite email. It does not note that the call is non-idempotent (re-inviting may duplicate emails), which the annotations flag but the text never clarifies.

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 action, then the authorization constraint, then the write nature. Zero 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 4-param mutation with no output schema, the description covers the key needs: who may call it, what side effect fires, and what roles mean. It doesn't say what the response contains (e.g., invite ID or status) or what happens on an already-invited email, a minor gap.

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

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

Schema coverage is 100% and the enum plus all four fields are already documented in the schema, so the description adds nothing new about parameters beyond the role names. Baseline 3 is appropriate when the schema carries the load.

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 (invites) and resource (family member to this household) plus the two role options and the transport (email). It does not name the read counterpart (list_family_members) as a contrast, but the operation 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?

Gives the gating condition clearly: 'Owner or coordinator only — viewers are rejected,' which tells the agent when the call will fail. It stops short of naming alternatives or when-instead-of guidance versus sibling tools.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: workspace-level scoping and the fact that limit is applied per loved one when aggregating. Gaps remain around result ordering and what 'recent' means chronologically.

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 purpose, then scoping mode, then the limit constraint. No redundant or filler 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?

Complete enough for correct invocation given the rich schema and annotations. However, with no output schema and no description of return shape or ordering, an agent cannot anticipate what a 'recent care event' record contains or how results are sorted.

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 both parameters are already documented, including the default and the per-loved-one limit behavior. The description restates rather than extends that information, so baseline 3 applies.

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

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

States a specific verb and resource ('Returns recent care events') plus the scoping domain ('caller's family workspace'). The name and description are unambiguous, and no sibling tool operates on care events, so differentiation is not needed.

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?

Explains the two usage modes clearly: scope to a single lovedOneId, or omit it to aggregate across all loved ones on the workspace. There is no explicit when-not or alternative-tool guidance, but for a list tool of this shape the mode selection is the key decision and it is 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 readOnlyHint, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds real value beyond that: it names the returned attributes (role, relationship, invite status) and gives an operational constraint about not logging member emails in third-party traces. It does not mention ordering, pagination, or whether the caller's own row 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: the first front-loads what is returned, the second is a distinct operational caution. No filler, no restatement of the title.

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

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

For a zero-parameter read tool with no output schema, the description does the important work of enumerating return fields and flagging the PII handling concern. It stops short of saying whether the result is empty for a solo account or how large the list can get, which would complete the picture.

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 schema baseline is 4 and there is nothing for the description to compensate for. It correctly implies the workspace membership is derived from the caller's identity rather than passed in.

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 people on the caller's family workspace') and enumerates the fields returned (role, relationship, invite status), so the agent knows exactly what comes back. It doesn't distinguish itself from the nearby sibling list_loved_ones, which reads like a related listing tool, so sibling differentiation is missing.

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 read-only listing framing, but there is no explicit when-to-use guidance and no mention of the alternative (list_loved_ones) or of invite_family_member as the paired write operation. Adequate but leaves the agent to infer routing.

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 read-only, idempotent, non-destructive behavior, so the bar is lower; the description still adds real context by warning that PHI may appear in subjects and previews and that HTML bodies are excluded. It does not cover ordering guarantees or pagination beyond what the schema states.

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

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

Three compact sentences: what is returned first, then the payload boundary, then the scope/PHI caveats. Every sentence carries distinct information with no repetition of the name or title.

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

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

With no output schema, the description compensates by enumerating returned fields and the PHI exposure, and the single required parameter is schema-documented. Minor gap: ordering of 'recent' messages and paging behavior beyond limit are not described.

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 lovedOneId pointing to list_loved_ones and limit bounded 1-50 default 20, so the schema carries parameter meaning. The description reinforces that exactly one loved one is in scope but adds no syntax or format 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?

Specific verb (Lists) + resource (messages in one loved one's Family Inbox) + explicit field set returned (subject, sender, category, preview). It is clearly distinguished from the singular sibling get_inbox_message by being a list over one loved one's inbox.

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 scope constraint ('caller's family workspace only') and the note that HTML bodies are not returned implicitly steer the agent to get_inbox_message for full content, but no sibling is named and there is no explicit when-to-use/when-not statement. 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, idempotentHint, non-destructive and closed-world, so the safety profile needs no restating. The description adds real value by naming the returned fields and explicitly excluding date of birth and medications, but says nothing about ordering, result size limits, or visibility scope within the family.

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

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

Two short sentences, zero filler, with the returned fields front-loaded and the exclusion clause placed immediately after. Every clause earns its place.

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

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

With no output schema, the description compensates by enumerating the returned fields (id, name, Family Inbox address), which is exactly what the agent needs. The remaining gap is the unresolved overlap with list_family_members, which a routing sentence would have closed.

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 schema carries no semantics to supplement; baseline 4 applies. The description correctly implies no filtering or identifier input 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?

Names a specific verb (lists) and resource (loved ones) plus the scope (caller's family workspace) and the exact fields returned. It does not, however, distinguish itself from the sibling list_family_members, leaving the agent to guess which listing tool to use.

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 the verb; there is no explicit statement of when to prefer this over list_family_members or get_user_profile, and no prerequisites are given. An agent can infer it is the enumeration call for loved ones, but must infer it.

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 say write, idempotent, non-destructive, and the description independently adds what those annotations cannot: the exact artifacts created, that a repeat call returns the existing record rather than erroring, that lovedOneEmail is never auto-contacted, and that PHI must not be solicited. It even restates 'This is a write' for emphasis, consistent with readOnlyHint=false.

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 front-loaded sentences: purpose, idempotency, precondition, PHI prohibition, then email caveat and the write marker. Everything is load-bearing, though the closing note about lovedOneEmail largely repeats the schema field description and could be trimmed.

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 9 parameters, no output schema, and a multi-step side-effecting operation, the description covers safety, consent, PHI, and idempotency well. It never says what identifiers the successful response returns for follow-up calls (e.g. lovedOneId for list_care_events), which is the main remaining hole given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by adding cross-parameter context the per-field text can't carry, notably that attestAuthorized must be confirmed verbally with the caller before being set and that dateOfBirth is PHI accepted only when volunteered. Minor redundancy with the schema on the email-forwarding and defaulting rules keeps it from a 5.

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

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

The description gives a concrete verb and resource ('sets up a loved one on LovedOne') and enumerates the three side effects: workspace creation/addition, @lovedone.app inbox allocation, and attestation recording. It never names the near-miss sibling invite_family_member, so an agent must infer which of the two people-oriented tools applies to a given request.

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 states a hard precondition ('confirm attestAuthorized with the user in plain words') and explicit prohibitions ('Do NOT ask for date of birth, medications, or SSN'; dateOfBirth only if volunteered). That is strong when-to-use guidance, but it offers no routing to alternatives such as list_loved_ones or get_onboarding_status when setup has already occurred.

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?

Beyond the annotations, it discloses the authorization model (owner/coordinator, viewers rejected), the exact sending identity and reply-to routing the web app uses, and flags that the body may contain health-related content — a compliance-relevant trait no structured field carries. 'This is a write' mildly restates readOnlyHint=false, but the added context is substantial.

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 verb and resource, and every clause except the slightly redundant 'This is a write' contributes a distinct operational fact. Sizing is appropriate for a mutation with an access gate.

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 all five parameters documented in the schema, annotations covering safety hints, and no output schema to explain, the description supplies everything else an agent needs: access requirements, identity/addressing behavior, and data sensitivity. Nothing material 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 subject, toEmail constraints, messageId provenance, and lovedOneId ownership check are all already documented in the input schema. The description adds no parameter-level detail (e.g., length limits or formatting) beyond what the schema provides, so baseline 3 applies.

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

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

The opening clause gives a specific verb (Sends a plaintext reply) and resource (a Family Inbox message), immediately distinguishing it from read-oriented siblings such as get_inbox_message and list_inbox_messages. It further pins down the mechanism by naming the from address and reply-to identity used.

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 states a hard precondition — 'Owner or coordinator only — viewers are rejected' — which tells the agent exactly when the call will fail. It does not, however, name the sibling to use for the read side or say what to do if the agent only has viewer rights, so the routing guidance stops short of explicit alternatives.

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