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

The description discloses costs ('one OFW request per folder plus one per messageId'), explains return fields (live state, revision hash comparison), clarifies that drafts edited in web app don't change timestamps, and warns about allowMarkRead marking messages read irreversibly. Annotations show readOnlyHint=false, which is consistent with the potential write effect of allowMarkRead=true. No contradiction.

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 dense paragraph but efficiently front-loads purpose and cost. Every sentence adds value, no redundancy. It reads naturally while packing in behavioral details. Ideal length for this complexity.

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 output schema and three parameters with edge cases, the description fully covers what the tool does, when to use it, costs, side effects, output fields, and distinguishes from similar tools. Leaves no obvious gaps.

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 description adds significant meaning: for folders it explains default behavior when messageIds omitted; for messageIds it details which cached states can be probed without marking read; for allowMarkRead it explains the irreversible consequence and server ceiling. This goes well beyond the schema's enum 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's purpose: 'Cheaply confirm whether the local cache still matches OurFamilyWizard, WITHOUT running a full sync.' It specifies a use case ('draft X is still sitting unsent') and distinguishes from siblings like ofw_status and full sync.

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 guidance: 'Use this before asserting anything about current state' and 'For draftKeys, or a full live draft inventory, use ofw_status.' Also explains when not to use (if mark read side effect is undesirable) and provides alternative sibling 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 minimal annotation (destructiveHint: false), the description discloses key behavior: events are immediately visible to the co-parent unless privateEvent is set, and there is no draft stage. This adds valuable context for an agent.

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 two sentences, no waste, and the most critical behavioral detail (visibility and draft stage) is front-loaded. Every word earns its place.

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

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

Despite 14 parameters and no output schema, the description only covers visibility and draft behavior. It lacks explanation of return values, error cases, or interactions among parameters like children, eventParentId, or reminders. The complexity of the tool demands more.

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 64% schema description coverage, the baseline is 3. The description does not add new meaning to parameters beyond what the schema already provides, but it does not detract either. No parameter-specific elaboration is given.

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 'Create a calendar event in OurFamilyWizard' with a specific verb and resource. It distinguishes from siblings by highlighting the immediate visibility to co-parent and absence of a draft stage, which sets it apart from update/delete 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 provides guidance on when to use privateEvent (to control visibility), and implies this is for new events given the sibling tools for update and delete. However, it does not explicitly state when not to use it 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 provide destructiveHint=false, indicating non-destructive action. Description does not add behavioral details such as whether it creates a new record, what it returns, or any side effects. The agent may need more context about the operation.

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

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

Single sentence, front-loaded with verb and object. Every word earns its place; no unnecessary fluff.

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?

Simple tool with two required params and no output schema. Description is minimal but covers the core action. However, it lacks details on return value or post-creation behavior, which could be useful for a new expense action.

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

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

Schema coverage is 100% with descriptions for both parameters. Description does not add additional meaning beyond the schema, so baseline score 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?

Description states verb 'Log' and resource 'expense' clearly. However, it does not differentiate from sibling tools like ofw_list_expenses or ofw_get_expense_totals, missing a chance to clarify its unique action.

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 updating or deleting expenses. No prerequisites or context provided, leaving the agent to infer usage.

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

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

Annotations only provide destructiveHint=false. Description adds no additional behavioral info such as permissions, side effects, or what happens on success. Minimal 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?

Single concise sentence with no wasted words. Perfectly sized for the tool's simplicity.

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 create tool with no output schema and fully described parameters, the description is adequate but does not mention what the tool returns (e.g., created entry ID). Missing return value information.

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

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

Schema coverage is 100% with descriptions for both 'title' and 'body'. Description does not add extra meaning beyond what the schema already 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?

Description clearly states 'Create a new journal entry' with specific verb and resource. Distinct from sibling 'ofw_list_journal_entries' which is a read operation.

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 vs alternatives. There are no similar create tools among siblings, but no explicit usage context is provided.

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 give destructiveHint: true. Description details the safety mechanism (re-read and refuse on change), local cache removal, and behavior of force parameter. No contradictions.

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: first states the core action, second elaborates behavior. No fluff, front-loaded, each word contributes 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, no output schema, the description covers concurrency, safety, force option, and cache side effect. Comprehensive and sufficient 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 covers all 3 parameters with descriptions (100% coverage). The description reinforces the meaning of expectedRevision and force, explaining their interplay, adding workflow context beyond bare 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?

Description clearly states 'Delete a draft message from OurFamilyWizard. Also removes the draft from the local cache.' It identifies the specific verb and resource, distinguishing it from siblings like ofw_save_draft and ofw_list_drafts.

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 guidance on when to use: deletion of drafts. Explains the re-read-and-refuse logic, expectedRevision, and force:true. Does not explicitly name alternatives like ofw_save_draft for modifications, but the usage context is 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?

The annotation already indicates destructiveHint=true, so the description's 'Delete' is consistent but adds no new behavioral context (e.g., permanence, cascading effects on recurring events). It meets the minimum bar but does not exceed it.

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 sentence with no wasted words. It is appropriately front-loaded and easy to parse quickly.

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 delete tool with no output schema, the description is mostly complete. However, it could briefly note that the action is irreversible or that includeFuture affects recurring events, which 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?

Both parameters are fully described in the input schema (100% coverage). The description adds no additional meaning beyond the schema, so the score is 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 clearly states the verb 'Delete' and the resource 'OurFamilyWizard calendar event'. It is distinct from sibling tools like ofw_create_event and ofw_update_event, making it easy for an agent to select this tool when deletion is needed.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as ofw_update_event for modifications. It does not mention prerequisites or conditions under which deletion should not be performed.

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 all behavioral traits beyond the annotations: it explains the inline delivery ladder, disk saving behavior, no-op on re-download, mime type normalization, and forced inline on hosted deployments. Annotations only indicate readOnlyHint=false, so the description fully covers the mutation and side effects.

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 main purpose and each sentence adds value. However, it is lengthy and could be slightly more concise; still, the complexity of the tool justifies the detail.

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

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

For a tool with 7 parameters and no output schema, the description fully covers all aspects: behavior, response structure (meta block, extracted content), parameter defaults, edge cases, and context from sibling tools. It is complete and leaves no gaps.

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 7 parameters are described in the schema (100% coverage), but the description adds significant meaning: e.g., the ladder for inline delivery, default extract behavior, relationship between inline and env var, and edge cases like force being ignored when inline:true. This greatly enriches understanding 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 clearly states the tool downloads an OFW message attachment by fileId and returns readable content. It specifies the inline delivery ladder for different file types, distinguishing it from sibling tools like ofw_get_message which provides the fileId but not the download.

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 guidance on when to use inline vs disk mode, the OFW_INLINE_ATTACHMENTS env var, and the source of fileId (from ofw_get_message). Also explains when to set extract, force, and saveTo, and notes edge cases like hosted deployments where disk mode is unavailable.

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?

The description goes far beyond the readOnlyHint:false annotation by disclosing the irreversible, co-parent-visible mark-read side effect, the First Viewed timestamp, and the exact conditions under which it happens. It also explains cache versus fetch behavior and draft-specific response differences, giving the agent a precise mental model of side effects.

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 action is front-loaded, and each subsequent sentence adds a distinct behavioral fact rather than repeating flourishes. The length is justified by the tool's side-effect complexity and the absence of an output schema.

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

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

For a single-message getter with a subtle write-behavior trap, the description is complete: it covers cache reads, irreversible marking, the opt-out flag, draft routing, and folder values for each message category. There is no output schema, but the behavioral and routing details an agent needs are all 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?

Schema coverage is 100%, giving the baseline of 3, but the description adds meaningful semantics for messageId: supplying a draft ID yields folder=drafts and draft-cache values, including no fromUser and modifiedAt-mirrored timestamps. allowMarkRead semantics are also reinforced, though largely restating 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-plus-resource statement: Get a single OurFamilyWizard message OR draft by ID. This clearly differentiates the tool from sibling list and draft utilities and states the exact unit of work.

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 strong situational context: when a cache read is possible no stamping occurs, and when a fetch of an unread inbox message would mark it read, with allowMarkRead:false as an opt-out. However, it never explicitly names when to prefer this over a sibling such as ofw_list_messages or ofw_list_drafts, so the routing is implied rather than stated.

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

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

Explicitly discloses side effect of updating last-seen status, which annotations (readOnlyHint=false) only hint at. This adds critical behavioral 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?

Two sentences, front-loaded with purpose, behavioral note in second sentence. 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?

For a zero-parameter tool with no output schema, the description adequately states return content and side effect, making it fully actionable.

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, so no parameter information is needed. The description properly omits any parameter discussion.

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?

Description clearly states the tool retrieves a dashboard summary with specific items (unread count, events, expenses), distinguishing it from sibling tools that target individual data types.

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?

Implies usage for a general overview but does not explicitly differentiate from siblings or provide when/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?

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?

Discloses key behaviors: reads from local cache, returns a 'complete' flag, and refusal with UNVERIFIED_EMPTY when cache is not fresh. Explains autoRefresh side effect, aligning with readOnlyHint=false 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?

Four-sentence paragraph is front-loaded with purpose, every sentence adds value, 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?

Even without an output schema, the description explains the 'complete' return field and special refusal result. All necessary details for using the tool are 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?

Schema coverage is 100%, and the description adds significant context for autoRefresh, including default behavior and cost implications, exceeding raw 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?

Clearly states the tool lists sent messages that are unread by recipients, with specific verb and resource. Distinguishes from sibling tools like ofw_list_messages by specifying unread sent messages and local cache usage.

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 guidance on using autoRefresh to avoid refusal, explaining when it's needed. Does not explicitly contrast with alternatives, but the tool name and context imply its specific use case.

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 idempotentHint, and the description adds meaningful behavioral detail: it never returns the credential itself, makes exactly one authenticated request, reports the credential source, round-trip time, and distinguishes failure categories. This goes beyond the safety hints already encoded in 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 tightly written in three sentences: mechanism, outputs, and usage trigger. Every sentence adds distinct value, and the most decision-relevant information appears early.

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 present, the description compensates by enumerating exactly what the tool reports: credential source, acceptance by ourfamilywizard.com, round-trip time, and a plain-English failure hint. It also explains the diagnostic purpose and the safety guarantee about not returning the credential, making it complete for an agent selecting and invoking the 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?

The tool has zero parameters, so there is nothing for the description to clarify beyond the schema. The baseline for no-parameter tools is 4, and the description does not need to elaborate on inputs.

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 names a specific diagnostic action: resolve credentials exactly as real tools do, make one authenticated request to ourfamilywizard.com, and report the outcome. It clearly distinguishes this health-check tool from the data-oriented sibling tools by focusing on broken-hop diagnosis rather than domain operations.

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 an explicit trigger: 'Call this when a real tool fails and you want to know which hop broke.' It implies the alternative is failing sibling tools, but it does not explicitly name a sibling or list when-not-to-use scenarios. Still, the usage context is clear enough for an agent.

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 fully discloses that this appears to be a list operation but may trigger a drafts sync, make OFW requests, and refuse empty results from a stale cache. It explains the semantic meaning of `complete`, `draftKey`, and UNVERIFIED_EMPTY, going well beyond the annotation readOnlyHint:false. There is no contradiction and no hidden side effect is glossed over.

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 front-loaded, leading with the main purpose and then layering essential caveats. Some content repeats the schema's verify and autoRefresh explanations, but the behavioral warnings about `complete` and UNVERIFIED_EMPTY are crucial enough to justify the length. A bulleted structure would improve scannability but the current form is 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?

Given there is no output schema, the description compensates well by explaining the crucial return semantics: the `complete` boolean, the `draftKey` stability, and the UNVERIFIED_EMPTY refusal path. It also covers pagination and response-shape parameters through the input schema. Nothing essential for invoking 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 description coverage is 100%, so the input schema already explains verify, autoRefresh, view, page, and size. The main description adds no new parameter-level meaning beyond reinforcing the verify/autoRefresh workflow, which the schema already covers. This meets the baseline for fully documented parameters without adding extra value.

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 draft messages'. It distinguishes this from sibling messaging tools by focusing on drafts and adds a distinctive guarantee: results are 'verified against OurFamilyWizard in ONE call'. This makes the tool's purpose immediately identifiable even 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?

The description gives concrete guidance on when to use each mode: verify:true for server-confirmed answers, verify:false for cache-only answers, and autoRefresh:true to resolve UNVERIFIED_EMPTY. It does not explicitly name sibling tools as alternatives for non-draft listing, but the context of draft messages and the explicit flag guidance make the usage conditions 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?

Annotations already declare readOnlyHint=true. Description adds that it lists events in a date range but no further behavioral traits (e.g., no pagination info, rate limits, or data freshness). Minimal added value beyond 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?

Single front-loaded sentence that efficiently conveys the tool's purpose. No 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?

For a simple list tool with full schema coverage and readOnlyHint annotation, the description is complete enough. No output schema required.

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 has 100% coverage with descriptions for all 3 parameters. Description doesn't add additional meaning beyond the schema, so 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?

Description clearly states it lists calendar events from OurFamilyWizard within a date range. The verb 'List' and resource 'calendar events' are specific, and it distinguishes from create/update/delete 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?

No guidance on when to use this tool versus alternatives. It doesn't mention when not to use it or suggest other tools like ofw_create_event for adding events.

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=true annotation, the description discloses a non-obvious response trait: paging state (hasMore, nextStart) precedes the records, so truncated reads still convey whether more remain. This plus the total/absence guardrail adds real behavioral context that an agent could not infer from annotations or the schema.

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

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

Four sentences, all earning their place: purpose, paging mechanism, response ordering with its implication, and an anti-hallucination guardrail. It is front-loaded with the core purpose and contains zero filler.

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

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

For a tool with two optional, fully documented parameters and no output schema, the description covers purpose, pagination mechanics, response shape, and interpretation rules. The only small gap is not naming ofw_get_expense_totals as the explicit alternative for totals, relying instead on an implied prohibition.

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 both max and start fully documented including defaults, ranges, and the nextStart continuation contract. The description adds the offset-paging framing but does not materially extend what the schema already provides, 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?

The description opens with 'List OurFamilyWizard expenses' — a specific verb and resource that precisely identifies the operation. It cleanly distinguishes itself from sibling tools like ofw_get_expense_totals (totals) and ofw_create_expense (creation), reinforced by the closing guardrail 'Never state an expense total'.

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 establishes clear use context: listing expenses with offset paging via start/max, and continuing via nextStart. The directive 'Never state an expense total or an absence from one page' functions as an implicit exclusion for the totals sibling, but it does not name the alternative explicitly, which would have earned 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?

The description goes well beyond the readOnlyHint annotation by detailing the paging contract: offset paging with 1-based start/max, response shape with hasMore and nextStart before records, the null meaning of nextStart, and the warning never to state an entry count or absence from a single page. This is substantial non-obvious behavioral 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?

The description is three tightly packed sentences with no filler. It front-loads the core purpose, then communicates the paging behavior and the critical agent-facing caveat, so every sentence earns its place.

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

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

For a simple read-only list tool with two optional parameters, the description is complete: it identifies the resource, the paging mechanism, the response paging fields, and the key interpretation pitfall. The schema covers parameter defaults and continuation, and the annotation covers safety, so an agent can invoke and interpret the 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 description coverage is 100%, so the baseline is 3. The description mentions 'start/max' and '1-based' but the input schema already documents defaults, ranges, and how to continue with nextStart. The additional paging-state information is response behavior rather than 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 a specific verb and resource: 'List OurFamilyWizard journal entries.' This clearly distinguishes it from sibling tools that list events, messages, expenses, or drafts, and it is not a tautology.

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 resource-scoped purpose makes the selection context clear, and sibling tools target different resources, so an agent can choose this tool without much ambiguity. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls 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 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 only include readOnlyHint=false, so the description carries the behavioral burden, and it delivers richly: result ordering, inclusive vs exclusive date semantics, the `complete` boolean's meaning, the UNVERIFIED_EMPTY refusal behavior, and the autoRefresh fallback are all disclosed. No annotation contradiction.

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 front-loads the core resource, then packs decision-relevant behavior (pagination semantics, sort behavior, complete flag, unverified-empty behavior) in a tight block. No filler or repetition of schema entries.

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 9-parameter, no-output-schema tool, the description covers the operational guardrails needed to call it correctly: freshness, empty-refusal, autoRefresh cost, and result completeness. The one gap is that it does not describe the record fields or response envelope, but with no output schema, a bit more detail about the result payload would round it out; still, the coverage is strong.

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 has 100% coverage, so the baseline is 3, and the description adds meaningful semantics beyond schema: the `sort` field's effect on which end of a truncated page is kept, the cache-size motivation for filters vs page-walking, and the precise meaning of `complete` relative to freshness.asOf. It does not restate every schema field, but the added strategic context is substantial.

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 messages from the local OurFamilyWizard cache,' then immediately names filtering dimensions (folder, date range, substring on subject+body). This clearly distinguishes it from sibling tools like ofw_get_message (single message) and ofw_sync_messages (sync operation).

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

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

Explicitly tells the agent when to prefer filters over pagination ('if you know what you want (a date range, a topic), prefer the filters over walking pages'), and there is an explicit 'instead of paging to it' alternative. Although sibling alternatives are not named by name, the guidance about cache size and filter-vs-page tradeoff is actionable.

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 far beyond the readOnlyHint=false annotation, disclosing mutation consequences (replacement deletes the old draft, id changes on every edit), recipient non-persistence, replyToId normalization, conflict refusal behavior, and force semantics. The agent is fully warned about irreversible and surprising behaviors.

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?

Long but exceptionally dense and organized with clear section labels (RECIPIENTS, IDENTITY, THREADING, SAFETY). Every sentence carries non-obvious operational information; no filler is present, and the core action is stated first.

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 high-complexity mutation tool with no output schema, this description is remarkably complete. It covers returned identity fields (draftKey, id, revision), conflict response (serverBody), threading verdict fields, and failure recovery, so an agent can call and interpret it correctly without additional documentation.

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 the schema already has 100% descriptive coverage, the description adds crucial semantics: recipientIds are not persisted, messageId leads to a new id and deletion, expectedRevision asserts a specific version, replyToId may be rewritten, and myFileIDs should come from ofw_upload_attachment. It substantially enhances 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+resource ('Save a message as a draft in OurFamilyWizard') and clarifies scope by distinguishing create from replace ('Pass messageId to replace an existing draft'). It is clearly distinct from sibling tools such as ofw_send_message, ofw_list_drafts, and ofw_delete_draft.

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 routing cues: supply recipientIds at send time instead, pass messageId to replace, attach files via myFileIDs from ofw_upload_attachment, and retry with expectedRevision after a conflict. It also explains why the OFW update-in-place endpoint is never used. This is concrete when-to-use and alternative 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?

Beyond the destructiveHint annotation, the description reveals critical runtime behaviors: the tool re-reads the server version, refuses on revision mismatch or already-sent draft, deletes the source draft only after confirmation, always retains it on failure, and may rewrite replyToId from cache. This is exactly the kind of consequence disclosure an agent needs before invoking an irreversible operation.

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

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

The text is long but tightly organized with SCREAMING-header segments for draft sending, recipients, post-send behavior, fresh compose, and attachments. The irreversibility warning is front-loaded, and every sentence conveys a behavioral rule or condition rather than padding.

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, zero-required-parameter mutation tool with only destructiveHint and no output schema, this definition is exceptionally complete. It describes the response fields (sentMessageId, draftKey, threaded, draftDeleted, draftRetained), success/failure handling, attachment behavior, and the draft deletion guarantee, so an agent has enough context to call 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?

Even though schema coverage is 100%, the description adds cross-parameter meaning that the schema alone does not carry: draftId and messageId are synonyms, subject/body override only when provided, myFileIDs overrides draft attachments when sending by draftId, and expectedRevision asserts the exact version being sent. It clarifies the interaction between parameters and the guard mechanics, not just individual field types.

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 and object — 'Send a message via OurFamilyWizard' — and immediately distinguishes this from drafting/saving by framing it as the irreversible, guarded operation. It then lays out two concrete modes (send existing draft vs compose from scratch), so an agent can tell exactly what the tool accomplishes.

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 branches: use draftId/messageId to send an existing draft, no draftId to compose fresh, and states when recipientIds is still required because OFW does not persist recipients. It also explains when to keep the draft via deleteDraftOnSuccess:false and when the send is refused, giving clear conditions for invocation without relying on 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?

The description thoroughly discloses behavioral traits: it is a live call that may mutate state (marking messages as read via allowMarkRead, irreversible and co-parent-visible). It explains the verification logic and the meaning of the `complete` flag. This exceeds the annotation's false readOnlyHint by providing concrete details.

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

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

The description is comprehensive and front-loaded with purpose, but it is relatively long. However, every sentence adds valuable information without redundancy, so its length is justified. Could be slightly more concise, but it remains 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?

Given no output schema, the description adequately explains return fields: state, sentAt, viewedAt, sentMessageId, and the top-level `complete` flag with its condition. It also clarifies edge cases (e.g., draftKeys resolving after sent). This covers all necessary behavioral context for an AI agent.

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

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

Schema description coverage is 100%, and the description adds significant meaning beyond schema: it explains the stable identity of draftKeys, why they are needed (OFW creates new IDs on edit), and how they resolve to states. It also clarifies the default behavior of includeDraftInventory and the implications of allowMarkRead.

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: 'ONE live call that answers "where does everything stand?"' and specifies it returns the full current draft inventory verified against OurFamilyWizard, distinguishing it from session memory or cached reads. It also explains the behavior with optional parameters like ids and draftKeys.

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 usage context: 'This is the call that should back any status summary about drafts or specific messages — never session memory, and never a cached read alone.' It also explains when to use draftKeys and the allowMarkRead parameter. However, it does not explicitly contrast with sibling tools like ofw_list_drafts or ofw_get_message, which would strengthen the guidelines.

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 critical behavioral traits beyond the readOnlyHint annotation: every call re-checks the newest page first, budget-based pausing and resumption, local vs. hosted unbounded behavior, and the irreversible mark-as-read effect of fetchUnreadBodies. This fully informs the agent of side effects and operational constraints.

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 comprehensive but somewhat verbose for the complexity of the tool. Every sentence is meaningful and well-organized, but some lines could be tightened without losing clarity. Overall, it balances detail with 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?

The description covers all essential aspects: return values (counts, unread list), budget/resume mechanism, deep parameter for backfilling, mark-as-read implications, and local vs. hosted differences. Missing only minor details like error handling, but the complexity is well-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?

Although the schema descriptions cover 100% of parameters, the tool description adds significant context: it explains the budget mechanism for maxRequests, the backfill logic for deep, the mark-as-read implication for fetchUnreadBodies, and the default behavior for folders. This enhances understanding beyond the schema 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 clearly states the tool syncs messages from OurFamilyWizard into a local cache and returns counts per folder and a list of unread inbox messages without fetched bodies. It is distinct from sibling tools like ofw_get_message (fetches a specific message) and ofw_list_messages (lists messages), 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 provides explicit guidance on when to use this tool versus alternatives (e.g., call ofw_get_message on unread messages not fetched). It explains the bounded and resumable sync behavior, how to handle done:false responses, and the effect of the deep parameter for backfilling. It also warns that done:false does not mean recent messages are missing.

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

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

The description adds behavioral context beyond the destructiveHint annotation: it reveals the merge strategy (fetch, apply changes, write back). It does not contradict annotations. It lacks explicit disclosure of required permissions or irreversibility details, but the annotation covers general destructiveness.

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 two sentences: first states the purpose, second explains the merge behavior. No redundancy, efficient, and front-loaded.

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?

The description explains the crucial merge strategy, which is key for correct usage. However, it does not explicitly state that omitted fields retain their current values, nor does it describe the return value (no output schema). For a tool with 15 parameters, this is a minor gap.

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

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

With 67% schema description coverage, the schema already documents most parameters. The description adds overall context about the merge operation but does not elaborate on individual parameters beyond what's in the schema. 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 clearly states 'Update an existing OurFamilyWizard calendar event.' It also explains the merge strategy, distinguishing it from create (ofw_create_event) and delete (ofw_delete_event) siblings.

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

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

The description explains the fetch-merge-write approach and notes that OFW has no partial update, implying how to use parameters. However, it does not explicitly state when to use this tool versus create or delete, though the context with sibling tools makes it 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?

The description discloses default privacy (PRIVATE), the ability to share via shareClass, and the return value (fileId). Annotations only include destructiveHint: false, so the description adds useful behavioral context, though it omits details like file size limits or synchronous 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?

The description is two sentences, front-loaded with the core action and return value. Every sentence adds essential information without redundancy or 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 has 4 parameters, no output schema, and minimal annotations, the description adequately explains the upload purpose, return value usage, and key parameter behavior. It connects to sibling tools for downstream attachment use. Missing details like error handling or prerequisites are acceptable for this scope.

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

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

Schema coverage is 100% with clear parameter descriptions, so baseline is 3. The description adds value by noting tilde expansion for path and reinforcing the default shareClass, providing extra semantic guidance.

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 uploads a local file to OurFamilyWizard's 'My Files' for message attachment, specifies the returned fileId, and distinguishes from sibling tools like ofw_send_message and ofw_save_draft by explaining how the fileId is used.

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

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

The description tells when to use the tool (before sending or drafting a message) and explains optional parameters like shareClass for sharing with co-parents. It does not list explicit when-not-to-use scenarios, but the context is sufficient given the sibling tools.

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