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

The annotation declares readOnlyHint: true, implying no side effects. However, the description explicitly states that setting allowMarkRead: true 'marks it READ on OurFamilyWizard and stamps a co-parent-visible "First Viewed" time — irreversible.' This is a write operation that directly contradicts the readOnlyHint. The contradiction is serious and undermines trust in the tool's safety classification.

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 densely packed with necessary context: costs, use cases, state semantics, side effects, and alternatives. It's front-loaded with the core purpose and avoids fluff. It could be trimmed slightly, but every detail serves the agent's decision-making.

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?

Given there is no output schema, the description fully describes what is returned: live server counts per folder, and for each id: state, folder, sentAt, existsOnServer, and content comparison. It also explains the meaning of state and why existsOnServer is insufficient. Costs, side effects, and exclusions are covered. No missing information is evident for an agent to call this 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 each parameter has a baseline description. The tool description goes well beyond this: it explains the default behavior of folders when messageIds is absent, the max of 25 ids, why certain ids are probed freely, and the full implications of allowMarkRead including the irreversible mark-read side effect. It also clarifies that content comparison uses revision hash because timestamps don't change on edit. This is substantial added meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Cheaply confirm whether the local cache still matches OurFamilyWizard, WITHOUT running a full sync.' It clearly distinguishes the tool from a full sync and from ofw_status, which it names as the alternative for draft inventories. The purpose is unambiguous and 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?

The description gives explicit when-to-use guidance: 'Use this before asserting anything about current state — especially "draft X is still sitting unsent".' It also states when not to use it: 'For draftKeys, or a full live draft inventory, use ofw_status.' This is a clear routing decision with no ambiguity.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses the no-draft publication behavior, the confirmation requirement, the two-step fallback with confirmToken, and the 'may already exist' uncertainty. This significantly extends what the annotations alone 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?

The description is dense but every clause carries operational value: confirmation, visibility, failure ambiguity, and retry prohibition. It is somewhat long and could be split into shorter sentences, but none of the content 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?

For a 15-parameter write tool with no output schema, the description covers the non-obvious execution model thoroughly: preview-first behavior, confirmToken reuse rule, and the EVENT_UNCONFIRMED edge case. Required/optional fields are left to the schema, which is appropriate.

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

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

With 67% schema coverage, the schema already handles most parameters. The description adds behavioral meaning for privateEvent (visibility to co-parent) and confirmToken (fallback-only, never first call), which are the parameters most likely to be misinterpreted by an agent.

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 action and resource: 'Create a calendar event in OurFamilyWizard.' It immediately distinguishes itself from update/delete/list siblings by its create semantics and further clarifies the sharing model with co-parent visibility.

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 gives strong situational guidance: shared events need confirmation, private events do not, and on an EVENT_UNCONFIRMED failure the agent must check ofw_list_events before retrying. It does not, however, explicitly contrast this tool with ofw_update_event or state when update should be preferred.

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 goes well beyond annotations by disclosing that the expense appears immediately to the co-parent, that the server cannot delete it, that an ambiguous failure means EXPENSE_UNCONFIRMED, and that the first call may perform NO write in fallback mode. These are critical behavioral traits not inferable from readOnlyHint, openWorldHint, or destructiveHint alone.

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 dense sentences cover purpose, side effects, failure handling, confirmation behavior, and retry guidance without redundancy. The most important operational warning, the no-retry rule, is front-loaded near the beginning.

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?

Despite having no output schema, the description covers the full call lifecycle: preview mode, confirmToken, repeat call, ambiguous failure, and verification via ofw_list_expenses. For a mutation tool with confirmation semantics and destructive implications, this is complete enough for an agent 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 description coverage is 100%, so the baseline is 3. The description adds value by clarifying that a repeat call must use the same arguments and that the confirmToken must only be passed after explicit user approval, which reinforces and extends the confirmToken schema semantics. It does not need to restate amount or description since those are fully documented 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?

The description states a specific verb and resource: 'Log a new expense in OurFamilyWizard,' and clarifies that it is a money claim appearing in the shared ledger. This clearly distinguishes it from sibling tools like ofw_list_expenses and ofw_get_expense_totals.

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 gives explicit when-to-use and when-not-to-use guidance: it instructs not to retry after an ambiguous failure until ofw_list_expenses confirms the expense did not land, and it explains the confirmation flow with a two-step fallback. This is concrete operational guidance beyond a generic description.

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 essentially restates the tool name and adds only the product context, so it discloses no behavioral traits beyond what the annotations already provide. The destructiveHint:false annotation covers non-destructiveness, but the description does not add anything about persistence, visibility, authentication, or expected effects of creating the entry.

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 one short, front-loaded sentence with no filler or redundant clauses. It names the operation and the resource efficiently, which is appropriate for a simple two-parameter creation 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 simple creation tool with two self-explanatory parameters, the description is largely usable, but it omits any indication of what response the agent should expect after creation. Since there is no output schema, a brief note about the result or a pointer to ofw_list_journal_entries for verification would improve completeness.

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%, with 'title' and 'body' already described as 'Entry title' and 'Entry text content'. The description adds no additional parameter nuance, but because the schema fully documents the parameters, the baseline of 3 is appropriate.

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

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

The description states a specific action ('Create') and a specific resource ('journal entry') within a named product ('OurFamilyWizard'). This clearly distinguishes it from sibling create tools like ofw_create_expense and ofw_create_event, so an agent knows which operation this is without inspecting 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?

Usage context is only implied by the resource name and description; nothing explicitly says when to choose this over ofw_list_journal_entries, ofw_create_expense, or other journal-related tools. It is adequate for a simple create operation but provides no explicit alternatives or exclusions.

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

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

Annotations only flag destructiveHint:true, but the description goes far beyond: it details the re-read before delete, the refusal on change, the local cache removal, and the behavior of force and expectedRevision. It fully discloses the destructive nature and safety mechanisms, exceeding the annotation's minimal coverage.

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 moderately long but each sentence contributes: it front-loads the primary action, then explains the cache side-effect, the safety re-read, and the two ways to handle revisions. No fluff, though it could be tightened slightly without losing meaning.

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 tool with 3 parameters and no output schema, the description covers all critical aspects: the action, side-effects, conflict resolution, and what is returned on refusal or force. It gives an agent everything needed to invoke it correctly and understand outcomes.

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 valuable nuance: it explains that expectedRevision asserts a specific version and that force bypasses the check, with the discarded server body echoed back. This clarifies the parameters' roles beyond the schema's own descriptions.

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 action ('Delete a draft message from OurFamilyWizard') and the specific resource (draft message). It distinguishes itself from siblings like ofw_save_draft by focusing on deletion and mentions cache removal, making its purpose unambiguous.

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

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

The description explains the version-checking mechanism and how to handle conflicts via expectedRevision or force:true, giving clear usage context. It doesn't explicitly state when not to use it or mention alternatives, but the draft-specific scope and safety checks imply appropriate use. Could be improved by contrasting with ofw_save_draft for editing.

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 far beyond: it discloses the read-first behavior, co-parent visibility confirmation, preview of the exact event, refusal if the event changed, and the two-step confirmToken fallback. This is exceptional transparency 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?

The description is front-loaded with the core action and each subsequent sentence adds essential safety information. It is slightly long but every sentence earns its place; it could be tightened but remains effective.

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 destructive tool with no output schema, the description covers the full confirmation flow, preview, and refusal conditions. The only minor gap is that it never explicitly states what a successful deletion returns, but the overall flow is well-covered.

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 adds context about confirmToken usage in the confirmation flow, but does not introduce new parameter semantics beyond what the schema already documents. Thus a 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Delete an OurFamilyWizard calendar event.' This unambiguously identifies the operation and differentiates it from sibling tools like ofw_update_event or ofw_create_event by the action verb.

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 clear operational context—reads first, requires confirmation, handles repeating events with includeFuture—but it does not explicitly name alternatives or state when not to use this tool. That's a clear context with no exclusions, matching a 4.

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 only say readOnlyHint=false and destructiveHint=false, which are minimal. The description carries the full behavioral burden and does so excellently: it discloses the delivery ladder (images vs extracted content vs raw bytes), the fallback to forced inline on hosted deployments, the disk-write behavior with path and overwrite rules, mime-type normalization, and the no-op re-download behavior. Nothing contradicts the annotations, and the description adds far more context than the 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 description is long but densely packed with essential details. It front-loads the core purpose and then systematically explains the delivery ladder, modes, defaults, and constraints. The numbered list and logical flow make it scannable. Every sentence contributes to understanding, with no filler. It is not overly verbose given the tool's complexity, so a 4 is appropriate.

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 seven parameters, one required, and no output schema, the description is remarkably complete. It covers all delivery modes, return formats (ImageContent, extracted content, EmbeddedResource blob, saved path), the meta block fields (deliveredVia, deliveryAttempts), environment variable overrides, filesystem constraints, overwrite rules, and extraction limits. It even tells the agent how to obtain fileId from a sibling tool. No critical operational detail 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 input schema has 100% parameter coverage with descriptive text for all seven parameters, so the baseline is 3. The description adds meaningful value beyond the schema: it explains the interaction between extract and inline/disk mode, the default values (e.g., extract default varies by mode), the saveTo path constraints and relative resolution, and the effect of maxChars on clipping. This elevates it to a 4.

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 clear verb-resource pair ('Download an OFW message attachment by fileId') and immediately states the output's value ('return content you can actually read'). It then enumerates three distinct delivery modes, which clearly differentiates it from siblings like ofw_upload_attachment (which does the opposite) and ofw_get_message (which provides the fileId). The purpose is unambiguous and distinct.

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 gives strong contextual guidance: it tells the agent that fileId comes from ofw_get_message's attachments[].fileId, explains when inline vs disk mode applies, and documents the default behavior and env-var override. It stops short of explicitly stating when not to use the tool or naming alternative tools beyond the fileId source, so it earns a 4 rather than 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 already declare readOnlyHint=true. The description adds context about output type (owed/paid totals) but does not disclose additional traits like time period scope.

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?

Single sentence with no wasted words. Front-loaded with verb and resource.

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?

Given no parameters and no output schema, description sufficiently conveys purpose. Could specify time period scope but not critical for basic functionality.

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?

No parameters exist; schema coverage is 100%. Description adds value by clarifying output content. Baseline 4 is appropriate.

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

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

The description clearly states the verb 'Get' and resource 'expense summary totals (owed/paid)', distinguishing it from sibling tool 'ofw_list_expenses' which likely lists individual expenses.

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 guidance on when to use this tool versus alternatives like 'ofw_list_expenses'. No explicit context for usage or exclusions.

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

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

Beyond the destructiveHint annotation, the description discloses the precise side effect: fetching an unread inbox message marks it read, stamps a co-parent-visible 'First Viewed' time, and this cannot be undone. It also explains which reads are side-effect-free and how the allowMarkRead parameter interacts with the server-wide setting.

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 every sentence carries distinct operational information: cache behavior, side-effect warning, opt-out path, draft routing, and folder semantics. It is front-loaded with the core purpose and side-effect warning before the detailed draft behavior, and it is appropriately sized for a tool with this much nuance.

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 it mostly delivers: it specifies folder values, draft-specific fields, mirroring of timestamps, and the compact/full distinction is covered in the schema. Minor gaps include no explicit failure/not-found behavior, but overall the agent has enough context to call this tool and interpret its main 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 the baseline is already met. The description adds real meaning beyond the schema, especially for allowMarkRead (irreversible co-parent-visible stamp, refusal behavior, unaffected cases) and for draft IDs (folder="drafts", no fromUser, sentAt/fetchedBodyAt mirroring modifiedAt). The view parameter is only covered by the schema, but the added parameter semantics still push this above the baseline.

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

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

The description opens with a specific verb and resource: "Get a single OurFamilyWizard message OR draft by ID." It clearly distinguishes this single-record retrieval tool from the list-oriented siblings and immediately communicates the draft/message dual behavior.

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 makes the core usage context clear: reads cache when available, otherwise fetches, and tells the agent exactly when to pass allowMarkRead:false. It does not explicitly name list-oriented alternatives, but the single-by-ID semantics are unambiguous enough that an agent can select this tool correctly.

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 a critical side effect: 'updates your last-seen status.' This is valuable behavioral context beyond the readOnlyHint annotation, which might otherwise lead an agent to assume no state changes. The annotation says readOnlyHint=true, but the description correctly warns of a state mutation, so there is no contradiction—the description adds important nuance.

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 a single, compact sentence that front-loads the tool's purpose and then adds the critical side-effect warning. Every word earns its place; no filler or repetition.

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 tool with no output schema, the description adequately covers what the tool does and its side effect. It could be slightly more complete by noting whether the returned summary includes counts only or also details, but the core information an agent needs is present.

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, so the description doesn't need to explain parameter meaning. The baseline for 0 params is 4, and the description appropriately focuses on what the tool returns rather than parameters.

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 retrieves a dashboard summary with specific content types (unread message count, upcoming events, outstanding expenses). It distinguishes itself from siblings like ofw_list_messages or ofw_list_events by being a summary rather than a detailed list, though it doesn't explicitly name a sibling alternative.

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 this is the tool to use when you need an overview of multiple data types at once, rather than detailed lists. However, it doesn't explicitly state when to use this over alternatives like ofw_list_messages or ofw_list_events, nor does it mention any exclusions.

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

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

The description correctly indicates a read operation, consistent with the readOnlyHint annotation. It adds no extra behavioral details beyond what the annotation already provides.

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 a single, concise sentence that directly conveys the tool's purpose without unnecessary 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?

Given the simple nature of the tool (no parameters, readOnlyHint annotation), the description is complete. No output schema is needed for such a straightforward retrieval.

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?

There are no parameters, so the baseline is 4 as per guidelines. The description does not need to elaborate on parameters.

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 action (get) and the resource (current user and co-parent profile information). It implicitly distinguishes from sibling tools that handle notifications, messages, events, expenses, and journal entries.

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 the tool should be used when profile information is needed but provides no explicit guidance on when not to use it or alternatives. With zero parameters and no sibling profile tools, this is adequate but minimal.

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 readOnlyHint annotation, the description exposes important behavior: it reads from local cache, includes a `complete` flag, and can refuse with UNVERIFIED_EMPTY if the cache is not fresh. The autoRefresh remedy is also disclosed, adding substantial value beyond annotations. No contradiction found.

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 compact and well-structured. It leads with the main action, then covers cache behaviorкну, return indicator, and the key edge case in a few efficient sentences with no filler.

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

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

For a read-only list tool with fully documented optional parameters, the description is largely complete: it explains purpose, cache behavior, a key refusal case, and the remedy. The only notable omission is the shape of the returned message list itself, which is more noticeable because no output schema exists.

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

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

All three parameters are fully documented in the schema with descriptions, including autoRefresh's behavior and defaults. The description reinforces autoRefresh's effect but adds no new page/size semantics, so the baseline 3 for high schema coverage is appropriate.

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

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

The description states a specific verb ('List'), a clear resource ('sent messages'), and a precise filter ('not been read by one or more recipients'). This semantically distinguishes it from sibling tools like ofw_list_messages without requiring the reader to open schemas.

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 context for using the tool is clear: it lists unread sent messages and can refresh on empty results. However, it does not explicitly name sibling alternatives or state when not to use this tool, leaving usage guidance somewhat implicit.

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?

It discloses behavior far beyond the annotations: default sync behavior, what 'complete' means semantically, the stable draftKey across draft edit churn, and the UNVERIFIED_EMPTY refusal plus remedy. This is especially valuable because there is no output schema and readOnlyHint=false is otherwise under-explanatory. No contradiction with annotations exists.

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 every sentence carries a unique, decision-relevant fact: one-call verification, cache-only mode, complete semantics, draftKey stability, empty-refusal and autoRefresh remedy. It is front-loaded with the core one-call promise and is as tight as the complexity allows.

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 full burden of explaining return semantics, and it does: complete boolean, result UNVERIFIED_EMPTY, draftKey, cacheStatus, view shapes, and failure remedies. An agent has enough to call it correctly, interpret the response, and handle edge cases without further investigation.

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 every parameter. The description adds meaningful semantics for verify, autoRefresh, and view beyond their schema text, including defaults, cost implications, and result-set consequences. However, page and size receive no additional meaning beyond the schema.

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

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

The description opens with a specific verb and object: 'List draft messages', then sharpens it with 'verified against OurFamilyWizard in ONE call'. It clearly distinguishes this from draft-mutating siblings like ofw_save_draft and ofw_delete_draft, and from ofw_list_messages, by focusing on drafts and their freshness/verification semantics.

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 gives explicit conditions for parameter choices: 'Pass verify:false to answer purely from the cache' and 'pass autoRefresh:true to sync and answer instead' when UNVERIFIED_EMPTY occurs. It does not, however, explicitly contrast this tool with sibling list tools (e.g., when to use list_drafts vs list_messages), so it stops short of full alternatives guidance.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds no further behavioral information such as default summary vs detailed output or ordering, but it does not contradict the annotations. With annotations carrying the safety profile, the description's limited addition earns a baseline 3.

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 a single, well-structured sentence that front-loads the verb and resource, then states the date-range filter. It contains no filler or 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?

This simple list tool has only three parameters and an annotation for read-only safety, so the description covers the core purpose. However, with no output schema, the description does not explain the shape or fields of the returned events, and the detailed parameter's effect is only documented in the schema. This leaves a modest gap in what the agent can expect as a 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?

The schema already provides full descriptions for all three parameters at 100% coverage, including formats for startDate/endDate and the effect of the detailed flag. The description does not add semantic detail beyond the schema, so it remains at the baseline 3.

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

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

The description uses the verb 'List' with a specific resource ('OurFamilyWizard calendar events') and a clear scope ('in a date range'), which distinguishes it from mutation siblings like ofw_create_event and ofw_delete_event. No ambiguity exists about the tool's high-level function.

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 clearly implies the tool is for retrieving events within a date range, aligned with the required startDate and endDate parameters. It does not explicitly name alternatives or exclusions, but the sibling tool names make the read-only usage context obvious, providing clear context without explicit when-not 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?

Discloses a non-obvious response behavior – paging state (`hasMore`, `nextStart`) appears BEFORE the records, and `nextStart` is null when exhausted – which annotations (only readOnlyHint) do not cover. The warning about not stating totals or absence adds safety-critical context beyond the structured metadata.

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 mechanism, response behavior, and a caution. The verb and resource are front-loaded, with zero filler or 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 simple list tool with full schema coverage and a readOnly annotation, the description covers purpose, pagination, and a key limitation. It does not enumerate the fields inside each expense record, which an agent might need if it must process the data, but the tool's name and warning reduce the risk of misuse. Minor gap only.

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%: both parameters have descriptive text in the input schema (`max` with default 20, `start` with offset semantics and nextStart guidance). The description's mention of 'Offset-paged via start/max' and the nextStart instruction essentially echoes schema content, adding no new parameter-level meaning.

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 'List OurFamilyWizard expenses' – a specific verb and resource that unambiguously identifies the tool's function. It distinguishes this from siblings like ofw_get_expense_totals and ofw_list_messages by naming the exact resource type.

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?

Provides clear pagination usage ('Offset-paged via start/max', 'pass the nextStart from the previous response') and a critical caution ('Never state an expense total or an absence from one page') that implies when not to rely on this tool. However, it does not explicitly name alternative sibling tools (e.g., ofw_get_expense_totals) for those cases, leaving some routing 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?

Even with readOnlyHint=true already present, the description adds substantive behavioral detail: the response leads with paging state, nextStart is null when exhausted, and a truncated/partial response still indicates whether more records remain. It also warns against overclaiming counts or absence from a single page, which is valuable beyond the annotation.

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

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

The description is appropriately sized and front-loaded with the tool's purpose. The pagination and caution sentences earn their place, though they are slightly dense; the explicit 'BEFORE' emphasis and 'Never state...' instruction could be tightened without losing meaning.

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

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

With no output schema, the description compensates by explaining the paging state placement and exhaustion semantics, which are the main risks when invoking a paged read tool. It does not enumerate journal entry fields or sorting, but those are not required for correct invocation and selection.

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 schema already documents both parameters, including defaults and the nextStart continuation behavior, so the description does not need to compensate. The description adds the 'offset-paged' framing and 1-based emphasis, but this largely repeats what the schema provides; baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List OurFamilyWizard journal entries.' This cleanly distinguishes it from sibling list tools like ofw_list_messages, ofw_list_events, and ofw_list_expenses. The added pagination details reinforce the intended operation without obscuring the core purpose.

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 gives clear invocation context, including the 1-based offset paging via start/max and how to continue from nextStart. It does not explicitly name alternative tools or exclusion conditions, but the purpose is specific enough that an agent knows when this listing tool is the right choice.

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 provide readOnlyHint=true, so the description does not need to repeat that. It adds valuable behavioral context: 'Fetched LIVE from OFW, so the counts are current.' This goes beyond the annotation by explaining the data freshness.

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 three concise sentences, each adding value. The first sentence states the core purpose, the second adds behavioral detail, and the third clarifies what is not returned. 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?

Given the tool's simplicity (no parameters, no output schema), the description is complete. It explains the action, the output (folder IDs and counts), the distinction from message content, and the live nature of the data.

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 input schema has zero parameters, so the baseline is 4. The description does not need to add parameter details, and it correctly focuses on the tool's purpose and output.

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 verb 'List', the resource 'OurFamilyWizard message folders', and specifies that it returns folder IDs and unread counts. It distinguishes itself from sibling tools like ofw_list_messages by explicitly noting that it does not return message content.

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 a clear usage hint: 'Returns folder IDs needed to call ofw_list_messages', implying the tool is a prerequisite. It also warns that it does not return message content, preventing misuse. However, it does not explicitly list when not to use or mention alternatives.

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

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

Annotations already declare readOnlyHint:true, and the description adds substantial behavioral context: cache-based results, the complete boolean describing result-set completeness, the UNVERIFIED_EMPTY refusal for unverified caches, autoRefresh sync behavior, sort semantics affecting which end of a range a page keeps, and view field shaping. No contradiction with annotations; this exceeds the baseline.

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 every sentence adds value. It is front-loaded with the core purpose, then flows into filtering, pagination/sort, result-set semantics, and edge cases. There is no fluff or redundancy; the structure is logical and efficient.

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

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

For a 9-parameter list tool with no output schema and only readOnlyHint annotation, the description covers all critical aspects: caching, freshness, pagination, sort behavior, response shape via view, and the complete boolean. It also explains the UNVERIFIED_EMPTY refusal and autoRefresh remedy. 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 all 9 parameters are documented, but the description adds significant meaning beyond the schema: it explains sort's effect on paging (start at old end vs paging to it), the compact vs full view trade-offs (dropping duplicate fields, promoting sender to from), and autoRefresh's cost and default behavior. These enrich the parameter semantics well beyond the baseline.

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

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

The description clearly states 'List messages from the local OurFamilyWizard cache' with a specific verb and resource. It enumerates filtering options (folder, date range, substring) and pagination, distinguishing itself from sibling tools like ofw_get_message (single message) and ofw_list_drafts. The scope is precise and unambiguous.

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

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

Provides explicit guidance: prefer filters over walking pages when a specific date range or topic is known, and pass autoRefresh:true when the cache might be stale. It implies when to use this list tool vs alternatives, though it does not name specific sibling tools or explicit exclusions. The context is clear enough for an agent to decide when to call it.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, but the description goes far beyond: it warns that replacing a draft DESTROYS the old one, explains that the id changes on every edit while draftKey is stable, describes the conflict-check refusal, and details the re-fetch behavior returning authoritative revision. It also covers threading normalization and the fact that recipientIds are not persisted. All of this is behavioral context not derivable from annotations.

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

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

The description is long but every sentence earns its place. It is structured into labeled sections (RECIPIENTS, IDENTITY, THREADING, SAFETY) that are easy to scan. The core purpose is front-loaded, and each paragraph covers a distinct behavior with concrete examples. There is no filler or 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 tool with 8 parameters, destructive side effects, identity quirks, and conflict safety, this description is exhaustive. It covers the return values (revision, serverBody, draftKey, response.id), edge cases (thread re-targeting, silent cache lag), and the exact workflow for safe replacement. No output schema exists, so the description must carry that burden, and it does completely.

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 described. However, the description adds substantial semantic depth: it explains that recipientIds are accepted but not persisted, that messageId triggers a delete-and-replace rather than an in-place update, that expectedRevision asserts a specific version and the fallback to local cache, and that force overrides the conflict check with the server body echoed. This goes well beyond the schema's basic type/description.

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

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

The description opens with a precise verb+resource statement: 'Save a message as a draft in OurFamilyWizard.' It immediately clarifies the core action and contrasts with siblings like ofw_send_message and ofw_delete_draft. The subsequent paragraphs detail the identity and safety nuances, leaving no ambiguity about what this tool does versus others.

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 explicitly states when to use this tool and when not to: 'supply recipientIds at send time instead' for recipients, 'Pass messageId to replace an existing draft' with an explanation of how to replace, and it even notes that OFW's update-in-place endpoint is never used. It provides clear guidance on expectedRevision and force parameters, including the condition 'Only use after showing the user the conflict.'

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 indicate a destructive write (readOnlyHint=false, destructiveHint=true), but the description discloses a wealth of behavioral detail: the irreversible deletion of the source draft, guard/refusal on revision mismatch, SEND_UNCONFIRMED uncertainty, automatic deletion only after confirmation, cache rewriting of replyToId, and the two-step confirmation fallback. It even explains what happens on timeout or failure, leaving little to the agent's imagination.

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 an extensive multi-paragraph monologue, likely over a thousand words, and repeats information already present in the input schema (e.g., deleteDraftOnSuccess, expectedRevision, force). While the key warning is front-loaded, the density of parentheticals and redundant explanations makes it hard to scan, and much could be condensed into a structured summary.

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?

Given the tool's complexity—11 parameters, no output schema, destructive side effects, confirmation flow—the description is exceptionally complete. It covers the response shape (sentMessageId, draftKey, threaded, draftDeleted), the SEND_UNCONFIRMED edge case, attachment inheritance, and the confirmation fallback, so an agent has all necessary context to invoke the tool 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%, but the description adds crucial semantic interconnections: draftId/messageId refer to the server's version, subject/body act as explicit overrides, expectedRevision asserts a specific version, recipientIds are still required because OFW does not persist draft recipients, myFileIDs override server attachments, and confirmToken has a strictly defined lifecycle. These nuances go far beyond the per-parameter schema descriptions.

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 sends a message via OurFamilyWizard and explicitly labels it 'the ONE irreversible operation here', distinguishing it from siblings like ofw_save_draft and ofw_delete_draft. It further breaks down two distinct use modes (sending an existing draft vs composing from scratch), leaving no ambiguity about the tool's purpose.

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?

Provides explicit when-to-use guidance: the safe default of sending a draft via draftId, when to compose fresh, when force may be used after user confirmation, and a concrete directive to avoid retry on SEND_UNCONFIRMED until a sync verifies the message did not send. It also references ofw_save_draft's guarding mechanism and warns that recipientIds are usually still required, making alternative selection clear.

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 readOnlyHint, it discloses the freshness contract ('complete is true ONLY when every part... verified live'), the create-then-delete id churn behind draftKeys, and the irreversible co-parent-visible mark-read side effect gated behind allowMarkRead. This is exactly the kind of behavioral context annotations do not 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?

The description is long but information-dense; the main purpose is front-loaded and every subsequent sentence covers a needed behavioral or parameter nuance. Nothing 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, it still tells the agent what comes back: full inventory, lifecycle states, sentAt/viewedAt, and the meaning of top-level complete. It also covers defaults and safety caps, so an agent has enough to call it correctly in any mode.

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 100%, the description adds meaning the schema lacks: max 25 probes, draftKey stability semantics across edits and sends, the default of includeDraftInventory based on other args, and the OFW_ALLOW_MARK_READ cap. These clarify how to invoke the tool rather than just what each field is.

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 concrete job ('ONE live call that answers where does everything stand?') and specifies exactly what it returns: full verified draft inventory and per-message lifecycle state. It distinguishes itself from cached reads and session memory, so an agent can tell it apart from list/get 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?

States the intended use explicitly ('should back any status summary about drafts or specific messages') and gives negative guidance ('never session memory, and never a cached read alone'). It also defines when each parameter mode applies: bare call for a full snapshot, 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?

The description goes far beyond the annotations. It discloses that the sync is bounded and resumable, that every call re-checks the newest page first, that done:false means older history is still backfilling (not that recent messages are missing), and that fetchUnreadBodies marks messages read with a co-parent-visible timestamp. It also explains the budget mechanism and local vs. hosted behavior. This is rich behavioral disclosure.

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

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

The description is dense but well-organized, front-loading the core purpose and return shape before diving into behavioral details. Every sentence earns its place, though the length is substantial. The structure is logical: purpose, return shape, follow-up action, sync behavior, deep flag, budget/resume semantics, and local vs. hosted distinction.

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 sync tool with 4 parameters, no output schema, and no annotations covering safety, the description is remarkably complete. It explains the return value shape, the resume mechanism, the meaning of done:false, the deep flag's purpose, and the mark-as-read side effect. An agent has everything needed to call this tool correctly and interpret its 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 the schema already documents all four parameters. The description adds value by explaining the deep:true use case (backfill suspected gaps), the budget/resume semantics for maxRequests, and the mark-as-read consequence of fetchUnreadBodies. It doesn't add much beyond the schema for folders, but the added context for the other parameters justifies a score above baseline.

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

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

The description opens with a specific verb and resource ('Sync messages from OurFamilyWizard into the local cache') and immediately distinguishes itself from siblings by explaining the return shape (counts per folder, unread inbox messages without bodies) and the follow-up call (ofw_get_message). It clearly identifies what this tool does and how it differs from related message tools.

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

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

The description gives explicit when-to-use guidance: it explains when to pass deep:true (backfill suspected gaps), when to call again (when done:false), and what done:false means vs. does not mean. It also names the alternative for fetching bodies (ofw_get_message) and explains the mark-as-read tradeoff. This is comprehensive 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?

The description goes well beyond the destructiveHint annotation by explaining the read-modify-write behavior, the lack of partial updates in OFW, the confirmation workflow, optimistic concurrency protection, and the two-step fallback with confirmToken. This gives the agent an unusually complete picture of what happens when the tool is invoked.

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 dense but every sentence carries distinct, necessary information: purpose, merge behavior, confirmation and concurrency guarantees, and the fallback mechanism. It is front-loaded with the core action and avoids 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?

Given the tool's complexity, the destructiveHint annotation, and the absence of an output schema, the description covers all essential operational aspects: what it updates, how partial updates are handled, when confirmation is required, and what happens on concurrent modification. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 69%, and the description adds meaningful process-level semantics: 'applies the given changes' and 'writes the merged result back' clarify that callers can pass a subset of fields. It also explains how confirmToken fits into the two-step confirmation flow, which complements the schema's already detailed parameter descriptions.

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: 'Update an existing OurFamilyWizard calendar event.' It clearly distinguishes this from sibling tools like ofw_create_event and ofw_delete_event by emphasizing 'existing' and 'update.'

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 clearly frames the tool as the way to modify an existing event, and the 'existing' wording implies it is not for creation or deletion. It does not explicitly name sibling alternatives, but the use context is clear and no exclusions are needed beyond the obvious ones.

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 goes far beyond the annotations by disclosing that file contents leave the machine and are stored on OFW, that hidden files and files over 25 MiB are refused, that the default is PRIVATE, and that SHARED uploads require confirmation — including the two-step confirmToken fallback. This is rich behavioral disclosure with no contradiction against 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 front-loaded with the core purpose and integration, followed by restrictions, sharing behavior, and confirmation flow. It is long and has some redundancy in the confirmation wording, but nearly every clause carries operational value.

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

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

For a side-effectful upload tool with security and confirmation complexity, the description covers prerequisites, limits, defaults, return value, downstream usage, and failure/confirmation fallback behavior. No output schema exists, but the fileId return contract is explicitly stated, making the tool callable 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?

Although schema coverage is 100%, the description adds meaningful semantics beyond the schema: upload-directory constraints, hidden-file and size limits, defaults for label/description, SHARED visibility implications, and precise confirmToken behavior. This significantly reduces the chance of misuse.

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

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

The description states a specific verb and resource: upload a local file to OFW's 'My Files' for later attachment to a message. It also tells the agent how the returned fileId is consumed by ofw_send_message or ofw_save_draft, which clearly distinguishes this tool from download and message-listing 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?

It gives explicit when-to-use and when-not-to-use guidance: only upload files the user explicitly asked to share, never files named in message text, and only files inside the upload directory. It also explains the downstream integration (pass fileId to myFileIDs), which is the relevant alternative context for this operation.

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