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

With destructiveHint=true and readOnlyHint=false set, the description explains exactly why: probing certain ids fetches detail, marks the message READ on OFW and stamps a co-parent-visible, irreversible 'First Viewed' time, and it notes OFW_ALLOW_MARK_READ as a server-wide ceiling. It also discloses the cost model (one request per folder plus one per messageId), which no annotation conveys.

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

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

Front-loaded with purpose, then cost, then return semantics, then exclusions — a sensible order. It is dense and longer than average, and a few clauses (e.g. the byte-identical/inSync example) could be tightened, but nearly every sentence carries non-redundant information.

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

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

No output schema exists, and the description compensates fully: it lists the returned fields (live vs cached count, state enum values, folder, sentAt, existsOnServer, inSync) and explains the surprising semantics of each. Nothing needed to call this tool correctly 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the per-folder live-vs-cached count comparison, the per-id lifecycle state field and why existsOnServer alone cannot distinguish draft from sent, and that content is compared by revision hash because draft timestamps do not change on edit.

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: cheaply confirm whether the local cache still matches OurFamilyWizard without a full sync. It is clearly distinguished from the sync tool and from ofw_status, and the 'freshness' framing is immediately actionable.

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

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

Explicitly says when to use it ('before asserting anything about current state — especially "draft X is still sitting unsent"') and names the alternative for a different need ('For draftKeys, or a full live draft inventory, use ofw_status'). It also states what it deliberately does not do (bodies, attachments, sync state).

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?

Goes well beyond the readOnly/destructive/openWorld annotations by disclosing the confirmation protocol, the two-step confirmToken fallback, the immediate visibility of shared events, and the ambiguous EVENT_UNCONFIRMED failure mode with its retry prohibition. This is precisely the kind of safety-critical behavior an agent needs and cannot get from structured fields.

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

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

Purpose is front-loaded in the first clause, and each sentence carries non-redundant operational detail. It is dense and somewhat run-on in the confirmation/fallback sentence, but 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?

For a complex mutating tool with 15 params and no output schema, the description covers the crucial gaps: confirmation, idempotency/retry safety, and visibility semantics. It leaves some parameters (notes, location, reminderMinutes) unexplained, but the higher-risk behavior is addressed.

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 67%, covering endDate, times, children, confirmToken, privateEvent, and the parent IDs, so most semantics live in the schema. The description adds meaning for privateEvent's visibility consequence and confirmToken's usage constraints but does not compensate for the undocumented params (notes, title, allDay, location, reminderMinutes). 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 ('Create a calendar event in OurFamilyWizard') and implicitly contrasts with siblings like ofw_update_event/ofw_delete_event/ofw_list_events by naming ofw_list_events as the verification path. An agent knows exactly what this tool does and how it relates to the other event tools.

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 strong conditional guidance: shared vs private visibility, no draft stage, do NOT retry on EVENT_UNCONFIRMED until ofw_list_events confirms absence, and the confirmation flow. It names one alternative (ofw_list_events) but does not explicitly route to ofw_update_event/ofw_delete_event for other operations, so it stops short of full when/when-not/alternatives coverage.

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 flag destructiveHint=true and openWorldHint=true, and the description adds substantial context beyond them: the expense appears in the co-parent's ledger immediately, this server cannot delete it, the EXPENSE_UNCONFIRMED partial-failure state, and the confirmation-preview-with-confirmToken protocol. This is exactly the behavioral disclosure a mutation tool needs.

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?

Dense and front-loaded, leading with the action and required fields before the safety/confirmation caveats. Every sentence is load-bearing, though the run-on confirmation paragraph is somewhat heavy and could be split for readability.

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 10-parameter destructive mutation with no output schema, the description covers required fields, receipt dependency, visibility semantics, irreversible ledger effects, partial-failure handling, and the confirmation protocol. Nothing an agent needs to call it correctly 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 coverage is 100%, so baseline is 3, but the description adds cross-field meaning: payerId is characterized as 'the parent who owes', children requires at least one id, receiptFileId should originate from ofw_upload_expense_pdf, and privateExpense's true-vs-default effect is restated with the shared-expense consequence. More than mere repetition.

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 ('Log a new expense in OurFamilyWizard') and scopes it to the 'current web-app expense contract', clearly distinguishing it from siblings like ofw_update_expense and ofw_list_expenses. An agent knows exactly what this tool produces 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?

Explicitly names required fields, routes receipt attachment through ofw_upload_expense_pdf, and gives a precise when-not-to-retry rule (after EXPENSE_UNCONFIRMED, wait for ofw_list_expenses). It also documents the two-step confirmation flow and its fallback, leaving little to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: no note on visibility/audience of the entry, no confirmation that it is an additive write despite the destructiveHint flag, and no auth or side-effect context.

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 front-loaded sentence with zero filler. It is efficient, though the brevity borders on under-specification for a mutation tool rather than being a model of tightness.

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 write tool with no output schema, the description should say what happens on success, whether the entry is published immediately, and any permission requirements. It supplies none of that, leaving the agent with only the tool name and the schema.

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?

Both parameters (title, body) have 100% schema description coverage, so the schema carries the semantics. The description does not add format, length, or content constraints beyond the schema, 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 ('Create a new journal entry') plus the product context (OurFamilyWizard), so the action is unambiguous. It stops short of differentiating from the sibling ofw_list_journal_entries or clarifying whether entries are private, shared, or family-scoped.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as ofw_list_journal_entries or ofw_save_draft. The agent must infer entirely from the name when this tool is appropriate.

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 flag destructiveHint=true, but the description goes well beyond them: it discloses the pre-delete re-read, the refusal-on-change behavior, that the current server body is returned so nothing is lost, and that the local cache is also purged. This is exactly the kind of context an agent needs before calling a destructive tool.

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

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

Front-loaded with the core action, then the collision-safety semantics. It is a dense single paragraph with em-dash clauses, but nearly every clause carries distinct information; the parenthetical is load-bearing rather than 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?

No output schema exists, and the description compensates by explaining what is returned on both paths (current server body on refusal, discarded version echoed when forcing). For a 3-param destructive tool with full annotation coverage, 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 coverage is 100% and the schema already documents all three params well. The description still adds framing value by presenting expectedRevision and force as an explicit either/or choice with the trade-off stated, rather than restating field definitions.

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 ('Delete a draft message from OurFamilyWizard') plus the local-cache side effect, which no sibling tool implies. It is trivially distinguishable from ofw_save_draft, ofw_list_drafts, and ofw_delete_event.

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 clear conditional guidance: pass expectedRevision to assert a version, or force:true to delete regardless. It does not explicitly name sibling alternatives (e.g., why not ofw_save_draft over an existing draft), but the when-to-use decision between the two modes is fully 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 flag destructiveHint=true and openWorldHint=true, but the description adds substantial behavior beyond them: pre-read of the event, confirmation preview with title/date/time, refusal if the event changed after preview, and the EVENT_UNCONFIRMED failure mode with an explicit no-retry instruction. These are exactly the operational traits an agent needs for a destructive tool.

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

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

Front-loaded with the action and its side effects, and every sentence carries operational content, but the two confirmation paragraphs overlap somewhat (elicitation vs. fallback restates the same preview-then-proceed contract). Slightly longer than strictly necessary, though nothing is wasted in a way that hurts selection.

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 annotations covering safety and no output schema, the description fully covers mutation semantics, the confirmation protocol, the failure mode, and retry policy. Nothing an agent needs to call this correctly and safely 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 coverage is 100%, so the baseline is 3; the description goes further by explaining the confirmToken lifecycle (first call performs no write, repeat call with the token proceeds) and the includeFuture-relevant confirmation flow. The remaining param detail (eventId source, includeFuture default) lives in the schema, which is acceptable.

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+resource ("Delete an OurFamilyWizard calendar event") and clearly distinguishes this tool from siblings like ofw_list_events, ofw_create_event, and ofw_update_event. An agent can identify exactly what this does without opening any 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 explicit when-to-use rules (after reading the event, after user confirmation), a when-NOT path (do not retry on EVENT_UNCONFIRMED until ofw_list_events confirms state), and names the sibling to consult. This is unusually complete routing 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?

Goes well beyond the annotations: it documents the 10 MiB inline ceiling, the tool-error behavior and its remediation, forcedInline on filesystem-less deployments, the no-overwrite-unless-force rule, the disk no-op on re-download, and saveTo path-containment. It also explains the `deliveredVia`/`deliveryAttempts` bookkeeping, which annotations cannot express.

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

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

Front-loaded with purpose, then the delivery ladder, then edge cases – a logical order. It is dense and long for a single tool, and some sentences (e.g. the inline/extract default interplay) partially restate the schema, but nearly every sentence carries operational 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 7-parameter tool with no output schema, the description supplies the response shape (`extracted`, `deliveredVia`, `deliveryAttempts`, `truncated`, `omitted`) plus failure and fallback behavior. An agent has everything needed to call it correctly and interpret the result.

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 cross-parameter meaning the schema does not: the OFW_INLINE_ATTACHMENTS default for `inline`, the interaction of `extract` with inline vs disk mode, and the containment rule for `saveTo`. It stops short of restating the enum-like `parts` syntax, which the schema already carries.

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 first sentence states a specific verb and resource ('Download an OFW message attachment by fileId') and adds the outcome ('return content you can actually read'). It is trivially distinguishable from the opposite-direction sibling ofw_upload_attachment and from ofw_get_message (which supplies the fileId).

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

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

Explicitly tells the agent how to source fileId ('from attachments[].fileId on ofw_get_message') and lays out when each mode applies: inline vs disk, the hosted-deployment fallback, when extract defaults on or off, and when to set force. The alternative paths are named and conditioned rather than left to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description contributes only the '(owed/paid)' characterization of the returned totals; it says nothing about scope (date range, per-child breakdown), freshness, or auth requirements.

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 front-loaded phrase with no filler, which is appropriately sized for a zero-argument read tool. It is arguably too terse, but nothing is wasted.

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 parameters, no output schema, and annotations covering only safety, the description should explain what the totals cover (time window, per-child or per-category breakdown). Because it does not, an agent cannot predict the scope of the returned summary.

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 for the description to disambiguate and the baseline of 4 applies. No parameter syntax or defaults 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 ('Get') plus resource ('OurFamilyWizard expense summary totals') and narrows it with '(owed/paid)'. It is distinguishable from ofw_list_expenses by the 'summary totals' scope, though it never names that sibling to sharpen the contrast.

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

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

There is no when-to-use or when-not-to-use guidance; the agent must infer from the phrase 'summary totals' that this is an aggregate view rather than the itemized list returned by ofw_list_expenses. No prerequisites, scope, or alternatives are 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 annotations (readOnlyHint=false, destructiveHint=true) only flag that something mutating can happen; the description supplies the crucial specifics — that fetching an unread inbox message marks it read, stamps a co-parent-visible 'First Viewed' time, and that this is irreversible and cannot be undone. It also discloses cache-vs-fetch behavior and the OFW_ALLOW_MARK_READ=false ceiling, well beyond structured data.

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

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

Front-loaded with the core purpose, then the destructive mark-read warning, then draft nuances — a sensible priority order. It is dense but nearly every sentence carries information; there is minor redundancy with the schema on allowMarkRead that keeps it from a 5.

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

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

With no output schema, the description carries the return-shape burden and does so: it explains folder values ('inbox'/'sent'/'drafts'), the absence of fromUser on drafts, how sentAt/fetchedBodyAt mirror modifiedAt, and the compact/full field differences. An agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100%, so the schema already documents view, messageId, and allowMarkRead thoroughly. The description largely restates the allowMarkRead semantics and draft-ID routing rather than adding new parameter-level detail, so 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?

The description opens with a precise verb+resource ('Get a single OurFamilyWizard message OR draft by ID') and immediately distinguishes itself from the sibling list tools (ofw_list_messages, ofw_list_drafts) by scope. An agent can tell exactly what this retrieves without opening the schema.

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

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

It gives clear conditional guidance: use allowMarkRead:false to refuse a fetch that would mark an unread inbox message read, and notes that cached/sent/already-read reads are unaffected. It also explains the drafts-routing path. It stops short of explicitly naming which sibling to call instead for listing or syncing, so it's strong context rather than a full when/when-not/alternatives map.

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 discloses the non-obvious side effect — 'updates your last-seen status' — which explains the destructiveHint=true / readOnlyHint=false annotations rather than contradicting them. It stops short of stating downstream consequences (e.g., whether unread counts change on subsequent calls) or any auth requirements.

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

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

Two sentences, zero filler: the payload of the summary comes first and the side-effect caveat is a clearly marked trailing note. Nothing needs to be trimmed or moved.

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 parameters, no output schema, and only three annotations, this simple tool is fully covered: the description states what is returned and the one behavior the annotations flag. An agent has everything needed to decide to call it and what to expect.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. The description correctly avoids inventing parameters or inlining an argument shape.

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 ('Get') plus a named resource ('OurFamilyWizard dashboard summary') with the three aggregates it returns spelled out (unread messages, upcoming events, outstanding expenses). That enumeration distinguishes it from sibling list tools such as ofw_list_messages, ofw_list_events, and ofw_get_expense_totals without needing to open any schema.

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

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

The 'dashboard summary' framing implies the use case (a quick overview rather than a full listing), but there is no explicit when-to-use statement and no alternatives named. The agent must infer that this is the aggregate shortcut versus the individual list 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=true and openWorldHint=true, so the safety profile is covered. The description adds essentially nothing beyond the annotations—no detail on what 'profile information' includes, whether it requires an active session, or failure modes with no parameters.

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

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

A single concise sentence with no filler, front-loaded with the action. It is efficient, though it could have afforded one more clause to clarify the returned 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 zero-parameter read-only tool with annotations and no output schema, the description is minimally adequate. It doesn't explain the return shape or co-parent edge cases, which would matter for an agent consuming the response.

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

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

The tool takes zero parameters, so the baseline for parameter semantics is 4 per the rubric. The description correctly implies no input is needed to fetch the current profile, and the empty schema is self-consistent.

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 verb and resource ('get...profile information') from a named system, which is clearer than a tautology. But 'current user and co-parent profile information' is vague about what fields are returned, and it doesn't differentiate why to pick this over the sibling listing/retrieval tools.

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

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

There is no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of the lack of parameters or what happens if the user has no co-parent linked. The agent must infer usage entirely.

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?

Goes well past the readOnlyHint/openWorldHint annotations: it discloses that reads come from a local cache, that an unverified-fresh empty SENT cache is REFUSED with result:"UNVERIFIED_EMPTY" rather than reported as empty, and that autoRefresh costs OFW requests when it fires. This is exactly the behavioral context annotations cannot convey.

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 sentences, no filler, and the most decision-relevant fact (cache-sourced unread sent mail) leads. The refusal/autoRefresh caveat is compact and specific rather than hedged.

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 still tells the agent what comes back (`complete`), and it fully covers the failure mode and its remedy. For a zero-required-param read tool, nothing needed to call it correctly 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 coverage is 100%, so page/size/autoRefresh semantics (including the OFW_AUTO_REFRESH default) are already documented in the schema. The description reinforces autoRefresh's role and its cost but adds no syntax or meaning beyond what the schema states; 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 with a precise scope qualifier: 'sent messages that have not been read by one or more recipients.' That scope alone separates it from ofw_list_messages (all messages) and ofw_get_message (single message), so an agent can route 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?

Gives a concrete conditional remedy: pass autoRefresh:true to sync and answer instead of receiving a refusal, and names the refusal result value. It does not compare against alternatives such as ofw_sync_messages or ofw_check_freshness, which is the only gap.

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, openWorldHint, and idempotentHint. The description adds valuable behavioral context: it explicitly states 'Read-only; never returns the credential itself' and describes the exact outputs (source, acceptance, round-trip time, and a plain-English hint distinguishing failure modes). It also mentions that it makes one authenticated request, which is a side effect not covered by annotations. No contradiction with annotations.

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

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

The description is approximately 70 words and front-loads the core action ('Resolves the credential... makes one authenticated request') before listing outputs and usage. Every sentence adds value: the credential resolution, the request, the reported metrics, the read-only/never-returns-credential note, and the when-to-call guidance. There is no redundancy.

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

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

For a zero-parameter diagnostic tool with no output schema, the description adequately explains what it does, what it reports, and when to use it. It specifies the three failure categories and mentions round-trip time, giving the agent a clear expectation of the result. No critical information is missing.

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

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

The tool has zero parameters, and the schema coverage is 100% (vacuously). The description does not need to explain parameters because there are none. The baseline for 0 params is 4, and no additional parameter semantics are required or provided.

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 clearly states the tool's purpose: resolving the credential as real tools do and making an authenticated request to test upstream reachability. It explicitly distinguishes this healthcheck from the sibling tools (messages, expenses, etc.) by naming it as a diagnostic that reports credential source, acceptance, and round-trip time. The verb 'resolves' and 'makes' are specific, and the resource is 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?

The description provides explicit guidance on when to call: 'Call this when a real tool fails and you want to know which hop broke.' This gives a clear trigger condition and implies it's for troubleshooting, not routine use. It does not mention alternatives, but the context is sufficient because this tool is unique among siblings for diagnostics.

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?

Goes well beyond the annotations by disclosing side effects (a sync of one list page plus one detail per draft runs first), cost implications ('Costs OFW requests when it fires'), a refusal path with a specific result code, and the stability guarantee of draftKey. This is exactly the behavioral context an agent needs before calling.

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

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

Front-loads the single most important fact (one-call verification) and stays on topic throughout. It is dense and slightly repetitive ('ONE call' / 'without a second call' / 'in one call'), which costs a bit of tightness.

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

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

With no output schema, the description correctly carries the return semantics: the `complete` boolean over the result set, the `draftKey` field, and the `result:"UNVERIFIED_EMPTY"` case. It omits other error/edge results and any note on pagination interaction with `complete`, which is a minor gap for a 5-param list 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?

Schema coverage is 100%, so the per-parameter docs already carry the baseline. The description still adds value by explaining the interaction between verify and autoRefresh and tying them to the refusal behavior, which the isolated schema entries do not connect.

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 draft messages') and immediately scopes it ('verified against OurFamilyWizard in ONE call'). It is clearly separable from the sibling write tools ofw_save_draft and ofw_delete_draft, and the verification framing distinguishes it from a plain cached list.

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 explicit conditions: verify:true (default) for server-confirmed answers, verify:false for pure cache reads, and autoRefresh:true to escape the UNVERIFIED_EMPTY refusal. It does not name adjacent siblings (ofw_check_freshness, ofw_sync_messages) as alternatives, so the routing is internal to the tool rather than cross-tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the date-range scoping constraint, but says nothing about pagination, result caps, or how the default detailed=false affects the payload, leaving real behavioral gaps for a list operation.

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 front-loaded sentence with no filler; the scope constraint (date range) immediately follows the verb and resource. Nothing is wasted or buried.

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

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

For a simple three-parameter read tool with a fully documented schema and no output schema, the description covers what the tool returns conceptually (calendar events). Only pagination/result-limit behavior is unaddressed, a minor gap 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?

Schema description coverage is 100% (startDate, endDate, detailed all documented with format and default), so the schema carries parameter semantics. The description only restates the date-range concept and adds nothing about the detailed flag, which is the correct baseline of 3.

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

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

The description states a specific verb (List), resource (OurFamilyWizard calendar events), and scope (in a date range), which cleanly separates it from ofw_create_event, ofw_update_event, and ofw_delete_event. It does not name those siblings explicitly, but the read/list framing is unambiguous.

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

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

Usage is only implied: the agent can infer 'call this to enumerate events over a period,' and the date-range phrase hints at the required startDate/endDate. There is no explicit when-to-use, when-not-to-use, or alternative named, so it lands at minimum-viable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the 'Read-only' sentence largely restates structured data. What the description does add beyond the annotations is the composition of the result set (preset plus custom categories, each carrying responsibility-split metadata), which is genuinely useful context, but nothing about ordering, volume, or freshness 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?

Two short sentences, front-loaded with the verb and resource, with no filler. The trailing 'Read-only' sentence is minor redundancy against the annotations, which keeps it 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 parameters, no output schema, and annotations covering the safety profile, the description's job is narrow. It adequately conveys what the tool lists and what the entries contain; only return-shape specifics like ordering or pagination are absent, and those are minor here.

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

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

The tool takes zero parameters and schema description coverage is 100%, so the baseline of 4 applies. There are no arguments whose semantics the description could clarify or omit.

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 a precise resource ('OurFamilyWizard expense categories'), and the resource is clearly distinct from siblings like ofw_list_expenses, ofw_get_expense_totals, and ofw_create_expense. The added detail that the result includes preset and custom categories with responsibility-split metadata further pins down what is returned.

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 never says when to reach for this tool versus ofw_list_expenses or ofw_get_expense_totals, nor does it state prerequisites or typical workflows (e.g., call this before creating an expense to obtain a valid category). 'Read-only' is a safety trait, not usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, setting a lower bar. The description adds valuable non-obvious behavior: pagination quirks (old start/max ignored, always page 1) and response structure leading with hasMore and nextPage. It doesn't cover auth or rate limits, but for a read operation, this is strong added context.

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 sentences, each earning its place: purpose, pagination caveat, and continuation instruction. Front-loaded with what the tool does. Slightly dense with technical details, but efficient and no wasted words.

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 annotations covering read-only and open-world behavior, and no output schema, the description provides the critical missing piece: pagination mechanics and continuation. It doesn't describe return fields beyond nextPage/hasMore, but that's reasonable given no output schema and the focus on 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 coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that the older start/max parameters are ignored and that continuation should use nextPage from the response. This directly informs parameter usage beyond the schema's formal definitions.

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 clear verb+resource: 'List OurFamilyWizard expenses.' An agent can distinguish it from siblings like ofw_get_expense_totals (totals vs. list) and ofw_create_expense (create vs. list). No explicit sibling naming, but the verb+resource is specific enough to differentiate from most.

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 when to use pagination by explaining nextPage continuation, which is useful guidance. However, it doesn't explicitly state when to use this tool vs. alternatives like ofw_get_expense_totals or mention any exclusions. Usage is implied rather than 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?

With no output schema, the description carries the burden of return-shape disclosure and does so richly: it explains that the response leads with `hasMore` and `nextStart`, that `nextStart` is null when exhausted, and that a truncated response still signals whether more remain. This is substantial behavioral context beyond what the readOnlyHint/openWorldHint annotations provide.

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 purpose is front-loaded, followed by paging mechanics and then the caution about not asserting counts from one page. Three sentences, each carrying distinct information, though the paging-state exposition is somewhat dense for a two-parameter list 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?

For a paged list tool with no output schema, the description covers the critical unknowns: pagination mechanism and the return envelope (hasMore/nextStart). It stops short of describing the journal entry fields themselves, so it is strong but not exhaustive.

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

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

Schema description coverage is 100%, so the schema already documents `start` (1-based, continue via `nextStart`) and `max` (default 10). The description only restates that paging is offset-based and 1-based, adding no semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'List OurFamilyWizard journal entries.' This clearly separates it from the write-side sibling ofw_create_journal_entry and from other list tools (messages, events, expenses) by its resource noun. It doesn't explicitly name an alternative tool, which keeps it off 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 description tells the agent how to continue paging and warns against stating counts or absence from a single page, which is genuine usage guidance about interpreting results. However, it never says when to choose this list tool over related ones or states prerequisites, so the routing guidance is only implied by the verb/resource.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuine behavioral context beyond that: data is fetched LIVE so counts are current, and it explicitly bounds scope with 'Does NOT return message content.' That freshness and boundary detail is exactly what annotations cannot convey.

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, zero filler, and the core purpose plus unread-count payload is front-loaded. The workflow link and scope boundary follow in priority order.

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-only list tool this is complete: it describes what is returned (folders, unread counts, folder IDs), how fresh the data is, and what is excluded. The absence of an output schema is fully compensated by the description's return-value summary.

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 for the description to disambiguate. Baseline of 4 applies; no parameter semantics are needed or missing.

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 OFW message folders), scopes it with examples (inbox, sent), and adds the differentiating payload (unread counts). An agent can distinguish it from ofw_list_messages, which lists messages rather than folders.

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

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

Explicitly links this tool into a workflow by stating it returns the folder IDs needed to call ofw_list_messages, so the agent knows why and when to invoke it. It does not name an exclusion or a when-not-to-use case, which keeps it short of a 5.

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

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

Goes well beyond the readOnly/openWorld annotations: it explains the `complete` boolean as a result-set guarantee tied to freshness.asOf, discloses the UNVERIFIED_EMPTY refusal for stale-cache empty results, notes that autoRefresh costs OFW requests, and describes how sort decides which end a truncated page keeps. These are exactly the behavioral facts an agent cannot infer from annotations.

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

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

Front-loaded with purpose and dense with useful detail, but long; the sort sentence partially restates the schema's sort description and the final autoRefresh sentence is a heavy compound. Nearly every clause earns its place, with minor redundancy.

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

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

For a 9-parameter, no-output-schema read tool, this covers the crucial contract: what `complete` means, when results are refused rather than reported empty, and how to recover. Nothing an agent needs to call it correctly 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 coverage is already 100% with rich per-parameter text, so the baseline is 3. The description adds strategy-level meaning (filters over paging, 1-based page, sort's effect on truncation, autoRefresh as the remedy for refusals) that a per-parameter schema alone does not convey.

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 messages') and immediately scopes it ('from the local OurFamilyWizard cache'), which separates it from the direct-fetch sibling ofw_get_message and from ofw_get_unread_sent. The description of filtering, pagination, and the result-set contract makes the aggregate-listing role 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 real operational guidance: prefer filters over walking pages because the cache may hold 1000+ messages, and use sort:"oldest" to start at the old end of a range. It never explicitly names an alternative sibling tool or states a when-not-to-use condition, so it falls short of full routing 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?

Far exceeds what the annotations provide (destructiveHint/openWorldHint/idempotentHint only). It discloses that recipients are not persisted, that replacement destroys the old draft and produces a new id, that the update-in-place endpoint is never used, that replyToId may be normalized, and that writes can be refused with serverBody returned. This is exactly the behavioral context an agent needs.

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

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

Front-loaded with the action, then organized under RECIPIENTS/IDENTITY/THREADING/SAFETY headings, so it is navigable. It is still dense and occasionally over-explains (e.g. the parenthetical about what is 'noted once in the response, not warned about'), but nearly every sentence carries actionable constraint 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?

Covers identity, replacement/conflict handling, threading, attachments, and safety for an 8-parameter destructive mutation tool with no output schema. Nothing an agent needs to call it correctly 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 coverage is already 100%, but the description adds real meaning beyond the schema fields: recipientIds are accepted-but-dropped, myFileIDs come from ofw_upload_attachment, messageId triggers a re-read and conflict check, and omitting expectedRevision does not mean 'overwrite anyway'.

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 ('Save a message as a draft in OurFamilyWizard') and immediately scopes it against siblings like ofw_send_message and ofw_delete_draft by clarifying draft semantics. An agent can identify this tool without opening any schema.

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

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

Gives explicit routing rules: use recipientIds at send time rather than on drafts, pass messageId to replace, pass expectedRevision when replacing a known version. It also states when NOT to overwrite and how to recover (merge into serverBody and retry).

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 flag destructiveHint=true and openWorldHint=true, but the description goes well beyond: server-side re-read semantics, expectedRevision guard with refusal behavior, automatic draft deletion only on confirmed send, draftRetained on failure, and the SEND_UNCONFIRMED ambiguity state. This is exactly the extra context needed for an irreversible operation.

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

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

Front-loads the key fact (irreversible) and then walks the scenarios in a logical order, but it is very long and re-states several details already carried verbatim in the schema descriptions (myFileIDs override, deleteDraftOnSuccess, expectedRevision). The all-caps emphasis aids scanning but the density costs it.

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 correctly carries the return contract itself: sentMessageId, draftKey, threaded, draftDeleted, draftRetained with reason, and the SEND_UNCONFIRMED outcome. Nothing an agent needs to call or interpret this 11-parameter tool 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 coverage is 100% so the baseline is 3; the description still adds cross-parameter workflow meaning — that recipientIds is usually required even for drafts (OFW does not persist recipients), how expectedRevision interacts with omission, and when force is permissible. Some of this duplicates the schema's own per-field text, so it is not a full 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?

States a specific verb+resource ('Send a message via OurFamilyWizard') and immediately frames it as the one irreversible operation, which distinguishes it from the reversible siblings ofw_save_draft and ofw_delete_draft. An agent can tell it apart from every sibling without opening the schema.

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

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

Gives explicit routing: send-existing-draft via draftId as the safe default vs compose-from-scratch with subject/body/recipientIds, plus when not to retry (SEND_UNCONFIRMED until a sent-folder sync confirms). It also names the confirmation prerequisite and the confirmToken fallback path.

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

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

Adds real context beyond annotations: the top-level `complete` flag is true ONLY when everything was verified live, with an explicit instruction not to state draft counts or lifecycle claims when false. It also discloses the create-then-delete id churn and that a draftKey keeps resolving after the draft is sent. It does not surface the irreversible/co-parent-visible mark-read side effect in prose (that lives only in the schema), which is the one gap.

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

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

The core claim is front-loaded in the first sentence and the remaining sentences each carry distinct information (state enum, complete flag, draftKey identity). It is dense and runs long, with a couple of colloquial asides ('what happened to the thing I was working on?') that 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 no output schema, the description carries the return-value burden and does so: it enumerates the `state` enum, `sentAt`/`viewedAt`, `sentMessageId`, and the `complete` verification flag. Combined with a 100%-documented 4-param schema, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what a draftKey actually is — a stable identity that resolves to the chain's current id and survives sends — and how ids/draftKeys combine. It stays silent on allowMarkRead, so it does not fully pre-empt the schema's most consequential 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+resource: a single live call that resolves current draft/message lifecycle state ('where does everything stand?'), returning a full draft inventory verified against OurFamilyWizard. It explicitly carves itself out from session memory and cached reads, so an agent can distinguish it from list/check siblings.

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

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

Gives explicit when-to-use ('should back any status summary about drafts or specific messages') and when-not ('never session memory, and never a cached read alone'). It also explains the two calling modes — bare call for full inventory vs. passing ids/draftKeys for targeted probes.

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

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

Adds substantial behavior beyond the annotations: the mark-as-read side effect on OFW and the irreversible co-parent-visible 'First Viewed' stamp, the per-call request budget and env override, the newest-page-first re-check ordering, and the hosted-vs-local boundedness difference. This is exactly the kind of irreversible-consequence disclosure the destructiveHint=true annotation only hints at.

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

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

Front-loaded with purpose and return values, then budget/resume semantics, then local-install behavior — a sensible ordering. It is dense and long for a single paragraph, with some repetition around done:false, but nearly every sentence carries distinct operational information.

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

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

No output schema exists, yet the description describes the response (per-folder counts, list of unfetched unread messages, done flag plus note) and covers resumability, budget sources, side effects, and environment-dependent defaults. An agent has everything needed to call it correctly and to interpret a partial result.

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 already 100%, so the schema carries the parameter definitions; the description adds operational meaning on top, notably that maxRequests exhaustion produces done:false and requires a resume call with identical arguments, and that re-checking the newest page happens before deep backfill spends budget. It adds less for folders beyond confirming default coverage.

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 with scope: 'Sync messages from OurFamilyWizard into the local cache', and immediately defines the return shape (counts per folder plus unread inbox messages whose bodies were not fetched). This clearly separates it from read-only siblings like ofw_list_messages or ofw_get_message, which the description explicitly routes to for reading bodies.

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 explicit when-to-use rules for each behavior: deep:true only to backfill suspected gaps, fetchUnreadBodies only when mark-as-read is acceptable, and 'call again with the SAME arguments to resume' when done:false. It names the alternative tool (ofw_get_message) for the deferred-body case and clarifies that done:false does not mean recent messages are missing.

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?

Goes well beyond the annotations (destructiveHint/openWorldHint): it discloses read-modify-write merging, optimistic-concurrency refusal when the event changed on OFW, the EVENT_UNCONFIRMED failure mode with an explicit do-not-retry instruction, and the elicitation vs confirmToken confirmation paths. This is exactly the behavioral context an agent needs for a destructive mutation.

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

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

Front-loaded with purpose, then the concurrency and confirmation behavior in rough priority order. It is dense but nearly every sentence carries load-bearing information; the final confirmation sentence is somewhat jargon-heavy (MCP_CONFIRM_MODE) for its payoff.

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 16-param destructive mutation with no output schema, the description covers the safety-critical surface: merge semantics, stale-write refusal, unconfirmed-write handling, and the confirmation protocol. Only the shape of a successful response is left implicit, which the absence of an output schema makes acceptable.

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 69%, so the schema carries most parameter documentation. The description adds one meaningful general rule ('writes the merged result back', i.e. omitted fields are preserved) but does not clarify the undocumented params (title, notes, allDay, location), so it neither fully compensates nor is empty.

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 ('Update an existing OurFamilyWizard calendar event') and immediately clarifies the implementation posture (fetch, merge, write back, no partial update). This clearly separates it from ofw_create_event / ofw_delete_event / ofw_list_events.

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 strong operational context: it directs the agent to ofw_list_events to determine whether an EVENT_UNCONFIRMED write landed, and explains the confirmation requirement before any shared-event change. It never states explicit exclusions against sibling tools, so it stops short of a 5.

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

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

Annotations only reveal that this is a destructive, open-world write; the description goes far beyond that, disclosing the read-then-merge implementation, the EXPENSE_FIELDS_UNREADABLE refusal with field naming, receiptFileId replacing all receipts, privateExpense=false publishing, optimistic-concurrency refusal if the expense changed, and the EXPENSE_UNCONFIRMED ambiguity with retry guidance. This is exactly the behavioral context annotations cannot carry.

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

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

Front-loaded with purpose and the merge rule, then layered with error and confirmation semantics. It is dense and lengthy, but nearly every sentence carries actionable information; the confirmation fallback paragraph is the only place that reads as heavier than strictly necessary.

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 an 11-parameter destructive mutation with no output schema and no elicitation guarantees, the description covers merge semantics, failure modes, concurrency, and the two-step confirmation fallback. An agent has everything needed to invoke it safely.

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

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

Schema coverage is 100%, so the schema already documents each parameter, but the description adds cross-field semantics the schema lacks: every omitted field keeps its current value, receiptFileId REPLACES all receipts, and the null-sentinel convention for clearing description/receiptFileId. The only minor gap is that confirmToken's schema text already covers most of what the description repeats.

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?

Opens with a specific verb+resource ('Change an existing OurFamilyWizard expense') and immediately adds the distinguishing semantic: partial update via merge. An agent can tell it apart from ofw_create_expense, ofw_list_expenses, and ofw_update_event without opening any 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?

Explicit about when to pass fields ('ONLY the fields you want to change'), when to use confirmToken, and routes to ofw_list_expenses when the outcome is EXPENSE_UNCONFIRMED. It does not explicitly name create_expense as the alternative for new expenses, so it stops just short of full when/when-not/alternatives coverage.

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 declare write/destructive/openWorld, but the description goes well beyond: it warns the file leaves the machine and is stored remotely, states the upload-directory restriction, the hidden-file and 25 MiB refusals, the default PRIVATE visibility, and the full SHARED confirmation flow including the two-step confirmToken fallback. This is unusually rich behavioral disclosure.

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

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

Front-loaded with purpose and the critical safety constraint, then constraints, return value, and confirmation behavior. It is dense and mostly earns its length, though the confirmation-fallback explanation is lengthy enough to slightly dilute scanability.

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 supplies the return value (fileId) and how to consume it. For a complex, destructive, open-world tool it covers safety, constraints, visibility, and confirmation — nothing an agent needs to call it correctly 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 coverage is 100%, so the baseline is 3; the description nonetheless adds real meaning by explaining shareClass PRIVATE vs SHARED visibility effects and the precise semantics/ordering rules of confirmToken (never on first call, never invented, never reused). It adds value beyond the schema without fully documenting every field.

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

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

States a specific verb (upload), resource (local file), and destination (OurFamilyWizard 'My Files'), plus the downstream purpose (attach to a message). This cleanly distinguishes it from the sibling ofw_download_attachment and the attach-via-message tools.

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?

Explicit when-to-use and when-not: 'only upload a file the user explicitly asked to share, never one named by text inside a message.' It also routes the agent onward (pass fileId to ofw_send_message or ofw_save_draft) and distinguishes PRIVATE vs SHARED usage.

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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, openWorldHint=true) by disclosing the side effect that matters most: the file is visible to the co-parent in My Files immediately, independent of the later expense's visibility. It also details the two-phase confirmToken fallback and that phase 1 performs no write. It does not cover limits such as max file size or failure/overwrite 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?

Front-loaded with purpose and the path/url constraint, then the side-effect warning and confirmation mechanics. Dense and mostly waste-free, though the confirmation paragraph is long enough that the key 'no write without confirmation' point competes with procedural 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?

Covers the input contract, the mutually-exclusive requirement, the shared-metadata side effect, and the confirmation protocol, and mentions the returned fileId even though no output schema exists. Gaps remain around error cases, size limits, and the full shape of the preview response.

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

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

Schema coverage is 100%, so per-parameter meaning is already documented, but the description adds the cross-field rule the schema only implies ('exactly one of path or url'), plus the sequencing constraint on confirmToken (never on first call, never invented, never reused). That is genuine semantics beyond the per-property text.

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 + destination: 'Upload a PDF to OurFamilyWizard My Files for later attachment to an expense.' It also implicitly distinguishes itself from the generic sibling ofw_upload_attachment by naming the expense-attachment purpose and the SHARED My Files target.

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?

Explicit conditions: exactly one of path or url must be supplied, PDF files only, confirmation is required before any write, and it routes visibility decisions to ofw_create_expense's privateExpense flag. An agent knows when and how to call this versus ofw_upload_attachment.

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