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 by documenting a three-rung delivery ladder, the 10 MiB inline cap, maxChars clipping, normalized MIME types, disk path defaults, and overwrite/no-op semantics. The destructiveHint=true annotation is consistent with disk writes and force replacement.

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 long and dense, but it is front-loaded and organized around a numbered delivery ladder. Some sentences repeat schema details, though most earn their place for a tool with many modes.

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 explains concrete return shapes (ImageContent, extracted JSON, EmbeddedResource, deliveredVia/deliveryAttempts) and failure modes. Complete enough for an agent to invoke it confidently.

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 descriptions already cover every parameter at 100%, so the description mainly reinforces defaults and interactions such as the env-var inline default, saveTo confinement, and no-op on re-download. It adds some cross-parameter value but little that is not already in the schema.

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

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

States a specific verb and resource ('Download an OFW message attachment'), names the required fileId, and explains the returned content modes. An agent can distinguish it from ofw_get_message, which only supplies fileId metadata.

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 covers when inline versus disk delivery is used, when disk is forced to inline on hosted deployments, when to use link for oversized files, and when extract:true is needed. It gives no alternative sibling tool for downloading, but none exists.

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?

Annotations already flag destructiveHint=true and readOnlyHint=false, and the description backs that up with specifics the annotations cannot convey: the unread-inbox fetch marks the message read and stamps a co-parent-visible "First Viewed" time that cannot be undone. It further discloses no-read-day withholding (body:null, bodyWithheld:true, readingBlocked) and the OFW_CONFIRM_MARK_READ preview/confirmToken mechanics.

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, but the body is a dense, em-dash-heavy block with nested parentheticals and a dangling pointer to MCP_CONFIRM_MODE. The content is largely valuable, yet the confirmation-flow material could be broken into distinct clauses rather than run together in one paragraph.

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 tool with no output schema and a possible irreversible side effect, the description does substantial work: it describes the response shape (folder=drafts, missing fromUser, sentAt mirroring modifiedAt, bodyWithheld/readingBlocked) and the two confirmation modes. The main gap is the unexplained "see MCP_CONFIRM_MODE" reference, which leaves the client-side branching underspecified.

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 each parameter is already documented, but the description adds cross-parameter interaction the schema does not: allowMarkRead only governs fetches that would stamp something, and confirmToken is only meaningful on a repeat call after a phase-1 preview. It also clarifies that messageId accepts draft IDs routed via the drafts cache.

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 and scope: "Get a single OurFamilyWizard message OR draft by ID." It also declares the data source (local cache, falling back to OFW), which distinguishes it from ofw_list_messages and ofw_list_drafts in the sibling set.

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 states when to pass allowMarkRead:false to refuse a read-stamping fetch, and which cases are unaffected (cached bodies, sent messages, already-read messages). It also gives a concrete operational instruction for the confirmation flow: show the preview and wait for the user's yes before repeating the call.

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

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

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?

Beyond the readOnly/openWorld annotations, the description discloses response-weight behavior (the custody grid is most of a response's weight), time semantics (OFW wall-clock times rendered with an offset per `timeZone`, defaulting to the server's DISPLAY_TZ), and format-specific behavior (ics returns a short JSON summary of what was included/excluded, then iCalendar text, with each custody period emitted as a 'Parenting time' event). This is the kind of 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 the resource and scope, then ordered by decision relevance: what to include, then format, then the sibling alternative. It is dense but nearly every clause carries information; the em-dash-chained single paragraph is slightly harder to scan than a bulleted structure would be.

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

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

With no output schema, the description takes on return-value explanation and does so for the ics path (summary block + iCalendar text) and the custody-grid weight. It is a 7-parameter read tool with sensible coverage of the high-value parameters, though the shape of the default JSON payload is left implicit.

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 why `types` matters (SCHEDULE dominates payload size), how `timeZone` is interpreted (OFW reports zoneless wall clock, this is the zone used to read and show it), and what `format:"ics"` actually changes about the output. The `view` and `detailed` parameters are only explained in the schema, not the description, keeping this below 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 opens with a specific verb and resource ('List OurFamilyWizard calendar items in a date range') and then enumerates exactly which item kinds are covered — events, connected/subscribed events, custody handoffs (TRANSITION), and the per-day custody grid (SCHEDULE). An agent can distinguish this from every calendar sibling (ofw_create_event, ofw_update_event, ofw_save_calendar_ics) without opening a schema.

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

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

It states the selection rule explicitly ('Pass `types` to keep only some of them') and gives a concrete exclusion with rationale ('leave SCHEDULE out unless you need who-has-the-children per day'). It also routes the agent to the right alternative for a different need: 'To get a file or download link instead, use ofw_save_calendar_ics.'

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 past the readOnlyHint/openWorldHint annotations: it explains the `complete` boolean's meaning against freshness.asOf, the UNVERIFIED_EMPTY refusal instead of reporting false absence, the precise `view` output shapes including the untrusted-data envelope for brief mode, and that autoRefresh costs OFW requests when it fires. These are non-obvious behaviors an agent could not infer 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 and the filter-over-paging heuristic are front-loaded, and the sentences are dense but purposeful. Some material duplicates the schema almost verbatim (notably the sort explanation and the autoRefresh remedy), which is mild waste for a description this long.

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 optional parameters and no output schema, the description carries the return-value burden itself: it explains the `complete` flag, the brief-mode line format and truncation marker, the compact vs full field trade-off, and the refusal result shape. An agent has enough to call this correctly and to interpret the response.

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

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

Schema description coverage is 100% and most of the description's parameter talk (sort ordering, view shapes, since/until inclusivity, autoRefresh) restates what the schema already documents. It adds a little framing — page is 1-based/offset-based and the cache can hold 1000+ messages, which motivates not paging — but that is usage motivation rather than new per-parameter meaning, 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?

Starts with a specific verb+resource ('List messages from the local OurFamilyWizard cache') and names the supported filter axes, so an agent immediately knows this is a filtered read of cached messages rather than a sync or single-message fetch. It never names the sibling tools (ofw_sync_messages, ofw_get_message, ofw_get_unread_sent) that would make the differentiation explicit, so it stops short of a 5.

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

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

Gives concrete when-to-use steering: prefer date-range/topic filters over walking pages on a 1000+ message cache, use sort:"oldest" to start at the old end instead of paging, and pass autoRefresh:true to sync and answer rather than accept a refusal. It offers no explicit 'use X tool instead when…' routing to siblings, which keeps it below 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 destructive=true, idempotent=false, and openWorld=true, and the description adds substantial operational context beyond them: irreversibility, recheck-before-write, post-write verification of paid status and unchanged fields, confirmation-before-write behavior, and the mayHaveLanded retry warning. This is unusually rich disclosure for a destructive financial 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?

The critical constraint (irreversible, full balance only) is front-loaded, and the remainder is dense but purposeful. For an irreversible financial mutation with a confirmation protocol, the length is justified and no sentence is 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?

With no output schema, the description still explains the preview/confirmToken response shape, the confirmation-required fallback, and the EXPENSE_REIMBURSEMENT_UNCONFIRMED error with mayHaveLanded. An agent has enough information to call, confirm, and handle failure 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 baseline is 3; the description still adds meaningful semantics by stressing that expectedRemainingAmount must match leftToPay rather than the full expense total. It also explains confirmToken's two-phase fallback and its relationship to MCP_CONFIRM_MODE, which goes beyond the schema's wording.

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 and resource: 'Irreversibly mark the FULL remaining expense balance reimbursed externally.' It immediately scopes the operation ('no partial amounts', 'does NOT send money') so an agent can distinguish it from ofw_update_expense and ofw_create_expense 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 states when to use it ('Records an already completed outside-OFW reimbursement only') and when not to ('does NOT send money or use bank/payment endpoints; no partial amounts'). It also gives precise preconditions for expectedRemainingAmount and a recovery path for EXPENSE_REIMBURSEMENT_UNCONFIRMED, 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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=true; the description adds far more: no overwrite of existing files, hosted branch uploads and returns an expiring private link (default 1 hour), local branch writes under OFW_ATTACHMENTS_DIR with a default path, and the output is a snapshot that does not track OFW changes.

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 verb and resource in the first clause, and every subsequent sentence carries real information (parenting-time inclusion, connector branching, no-overwrite, snapshot semantics). The single dense paragraph is long and the hosted/local details are interleaved, so structure could be tighter.

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, and the description compensates by describing both possible return values — a private expiring download link on hosted, a filesystem path locally. Combined with write behavior, defaults, and re-import semantics, an agent has everything needed to call it 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 ties the filter parameters to ofw_list_events ('Same filters as ofw_list_events') and separates hosted-only (linkMinutes) from local-only (saveTo) parameters, which the schema only states per-field. It still does not explain how types interact with the .ics output beyond the schema's own notes.

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 ('Save an OurFamilyWizard date range as an iCalendar (.ics) file') and names exactly what goes into it (events, all-day events, custody periods as 'Parenting time'). It also differentiates from a sibling by noting 'Same filters as ofw_list_events' and from OFW's native export, which 'leaves the parenting schedule out'.

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 context: which filter tool it mirrors (ofw_list_events), what happens on a hosted vs local install, and when to re-import (later exports update in place via stable UIDs). It does not state when to avoid this tool or when the JSON-listing alternative is preferable, so it falls short of a full when/when-not treatment.

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

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

The annotations already mark this as destructive, and the description explains exactly why: replacing a draft creates a new draft and deletes the old one, while OFW's update-in-place endpoint is a no-op. It further discloses that OFW does not store draft attachments, that this server holds them and folds them into revision, that draft ids change on every edit while draftKey is stable, and that conflicting edits can cause a refusal with serverBody returned.

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 long but front-loads the core action and then organizes caveats under clear labels like RECIPIENTS, ATTACHMENTS, IDENTITY, THREADING, and SAFETY. The density is justified for an 11-parameter destructive tool, though some sentences could be tightened.

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, but the description explains the important return signals: draftKey as stable identity, revision as authoritative state after re-fetch, attachments.held, serverBody on conflict, and notes about carried-over fields and thread normalization. For a complex destructive save/replace operation, an agent has enough information to invoke it correctly and recover from conflicts.

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?

Although schema coverage is already 100%, the description adds crucial meaning beyond the schema: messageId replacement changes the id, expectedRevision asserts a specific version and is not an overwrite flag, force should be used only after showing the conflict, removeFileIDs drops held attachments, and inlineAttachments/blobKeys are validated and uploaded as private files. These interactions are not apparent from the parameter descriptions alone.

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

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

The description opens with a specific verb and resource: "Save a message as a draft in OurFamilyWizard." It also distinguishes this from sending by explaining that held attachments are later attached with ofw_send_message(draftId), and it clarifies that passing messageId replaces an existing draft rather than creating an unrelated one.

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 usage paths: omit messageId to save a new draft, pass messageId to replace one, use expectedRevision from ofw_list_drafts/ofw_get_message, and use ofw_upload_attachment uploadSlots plus blobKeys for larger hosted-deployment files. It also warns to supply recipientIds at send time because recipients are not reliably kept on drafts.

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 say destructive/open-world/non-readonly; the description supplies the far richer behavior: server-side draft re-read, refusal on revision mismatch, automatic draft deletion only after confirmation, SEND_UNCONFIRMED on timeout, PRIVATE attachment handling, and a confirmation-preflight flow. This is exactly the 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 the irreversible-operation warning and organized into TO SEND / RECIPIENTS / TO COMPOSE / ATTACHMENTS / response blocks, which suits a 13-parameter tool. It is dense and capitalized throughout, and the confirmation/confirmToken mechanics are stated twice, so it is not maximally tight.

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 destructive send with no output schema, it covers everything an agent needs: preflight confirmation, what is deleted and when, failure retention semantics, retry prohibition, attachment verification, and the named response fields (sentMessageId, draftKey, threaded, draftDeleted, draftRetained).

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 non-obvious meaning — that recipientIds is usually required even for drafts, that omitting myFileIDs carries the draft's held files, and that omitting expectedRevision compares against the local cache rather than sending blind. Most of the rest is echoed from 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?

Opens with a specific verb and resource ("Send a message via OurFamilyWizard") and immediately distinguishes itself from every sibling by naming it as "the ONE irreversible operation here" versus ofw_save_draft, ofw_upload_attachment, and the read 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 explicit routing: "TO SEND AN EXISTING DRAFT (the safe default): pass draftId" versus "TO COMPOSE FROM SCRATCH: supply subject/body/recipientIds with no draftId", plus guardrails on when to use force and when not to retry (SEND_UNCONFIRMED). Alternatives and exclusions are both 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?

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?

With destructiveHint=true already declared, the description still adds substantial non-annotated behavior: per-call request budgets, done:false resumability semantics, no-read-day suppression via bodiesWithheld:true, and the irreversible co-parent-visible 'First Viewed' stamp from fetchUnreadBodies. The only shortfall is that the confirmation/confirmToken flow description is dense and duplicated from the schema rather than clarified.

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 constraints and continuation rules, with zero filler sentences. It is long, but the length is justified by a genuinely complex, resumable, side-effecting sync; a couple of clauses (confirmToken mechanics) repeat schema content.

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

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

For a resumable, budgeted, potentially destructive sync with no output schema, the description covers what is returned (counts per folder, unread list), continuation semantics, and the read-marking side effect. An agent has everything needed to call it correctly and 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 baseline is 3, but the description adds real meaning beyond the schema: it explains the consequence of fetchUnreadBodies (marks read, stamps First Viewed, refused when OFW_ALLOW_MARK_READ=false) and the resume contract for maxRequests. The confirmToken explanation largely restates the schema wording.

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 sentence names a specific verb and resource ('Sync messages from OurFamilyWizard into the local cache') and immediately distinguishes the tool from the read path by naming ofw_get_message(id) as the way to read bodies. The agent can tell it apart from ofw_list_messages without opening either schema.

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

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

Explicit when-to-use conditions are given: deep:true for backfilling suspected gaps, call again with the SAME arguments when done:false, and call ofw_get_message to read withheld bodies. It also names the alternative and the exclusion (unread inbox bodies withheld to avoid mark-as-read).

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?

Beyond the destructive/openWorld annotations it discloses the consequences that matter: bytes leave the machine and are stored on OFW, the upload-store copies are deleted once OFW has them, PRIVATE is the default while SHARED is immediately visible to co-parents, and a SHARED upload is gated behind confirmation. It also explains the two-phase uploadSlots → PUT → blobKeys choreography and that a batch reports per-file results and 'does not fail as a whole when one file does'. Nothing here contradicts the 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 purpose is front-loaded and the three sources are cleanly bulleted, so the structure serves the reader well. It is nonetheless long, and the trailing block on confirmation prompts is dense enough that the actionable rule ('first call performs NO write and returns a preview plus confirmToken') has to be dug out of a single run-on sentence.

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 (fileIds, per-file ordered results) and what to do with them. Combined with the size limits, share-class semantics, partial-failure behavior, and the confirmation fallback, an agent has everything needed to invoke an 8-parameter, three-mode tool 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 would be 3, but the description adds semantics the schema cannot express: the 'Pass EXACTLY ONE source' rule, which the schema does not enforce (there is no oneOf among path/inline/uploadSlots), plus limits (10 files, 25 MiB, bare non-dot filename) and the meaning of confirmToken as valid only on a repeat call after explicit user approval. It also clarifies that fileIds are the hand-off key to myFileIDs on the message tools.

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

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

The description opens with a specific verb and destination resource: 'Upload a file to OurFamilyWizard's "My Files" so it can be attached to a message.' It distinguishes this from the downstream siblings by naming ofw_send_message and ofw_save_draft and explaining that this tool only stages files that those tools then attach. An agent can identify the tool's role without opening the schema, though the near-neighbour ofw_upload_expense_pdf is never explicitly excluded.

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

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

It gives an explicit decision tree over the three modes: uploadSlots for hosted deployments and 'the way to send photos and other real files', inline for small files that 'work anywhere', and path for local installs only, with an explicit statement that path 'cannot work' on a hosted deployment. It also states when to bypass this tool entirely by using the other tools' inlineAttachments / blobKeys instead, which is exactly the alternative-routing guidance the dimension asks for.

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.