Familia

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

Annotations already convey that this is a non-read-only, destructive operation, so the agent has the core safety signal. The description does not add detail about the replaceExistingPhoto side effect, though the schema documents it; this is a minor gap rather than a 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?

Two sentences with no filler: the use case and file formats come first, then the encoding rule and the negative boundary. Every sentence contributes to correct invocation.

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 tool, the input schema covers each parameter and an output schema exists, so the description need only provide intent mapping and behavioral boundaries, which it does. The only omitted nuance is the destructive replacement behavior, but this is signaled by destructiveHint and documented on replaceExistingPhoto.

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 the key relationship that either dataUrl OR base64Data-plus-mimeType should be provided, which is not explicit from the JSON schema alone; this pushes it to 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 uses a specific verb ('attach') and a concrete resource ('image to an existing Familia task or plan'), and restricts acceptable formats to JPEG/PNG/WebP. The closing 'Do not use for non-image files' differentiates it from generic attachment tools, even though no sibling name is cited.

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 explicitly tells the agent when to invoke: when the user asks to attach a JPEG/PNG/WebP image to a task or plan. It also provides a clear negative rule ('Do not use for non-image files'), but it does not name an alternative tool for those cases, so it stops just short of the highest bar.

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=true annotation, the description discloses important internal behavior: the batch runs bounded individual write operations one by one and does not create a backend transaction. This is critical for agents to understand non-atomicity and partial-failure potential. This is exactly the kind of behavioral context annotations alone do not 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 compact and front-loaded: the first sentence states the trigger conditions, followed by two disambiguation rules and one internal-behavior caveat. Every sentence earns its place, and there is no redundant restatement of the title or 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 complex batched-write tool, the description covers the key decision points: when to use it, when to use alternatives, and how the batch behaves internally. The output schema exists, so return-value details are not the description's burden, and the annotations already signal the destructive nature. This is complete for safe and correct invocation.

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

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

The schema already documents most parameters at roughly 75% coverage, so the baseline is 3. The description adds meaningful selection-level semantics by telling agents when to use repeatRule/rrule versus duplicate operations, and when to prefer create_plan with relatedTasks over separate operations. This goes beyond the schema's individual field descriptions and helps structure the operations array correctly.

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: batch-creating or modifying multiple Familia tasks, list tasks, plans, and task attachments in one request. It distinguishes this from single-operation sibling tools by anchoring on 'multiple in one request' and by naming create_plan as the preferred alternative for main-event-plus-related-actions cases.

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 conditions: explicit user request for multiple items, or one prompt with multiple standalone dated actions. It also provides clear when-not-to-use guidance: repeated tasks/plans should use repeatRule/rrule on one operation, and related dated actions should go into a single create_plan with relatedTasks. This directly routes agents away from misuse.

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 destructiveHint=true and readOnlyHint=false, which the description is consistent with. The description adds useful nuance by clarifying that the operation cancels/archives/hides rather than permanently deletes the record, which is important behavioral context beyond the annotation flags.

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 with no filler. The core usage condition is front-loaded, the exclusion is clear, and the alternative tool is named. 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?

Given the small parameter set, existing output schema, and annotations, the description fully covers usage conditions, exclusions, and non-permanent destructive behavior. Nothing an agent needs to call this tool correctly is missing.

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

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

Schema coverage is 100%: both timezone and agreementId have clear descriptions, including the legacy naming note for agreementId. The description itself adds no parameter-level meaning, so 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 clear verb and resource: cancel, archive, or hide an existing Familia task. It also differentiates the tool from familia_update_task by explicitly excluding the 'mark done' use case, so an agent can distinguish it from siblings without inspecting 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 description gives an explicit condition for use ('only when the user explicitly asks to cancel, archive, or hide'), a clear exclusion ('Do not use to mark a task done'), and names the alternative tool (familia_update_task). This leaves no ambiguity about when to select this tool.

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

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

Annotations already convey that the operation is not read-only and not destructive, so the description does not need to restate those facts. It adds useful behavioral context by clarifying that this creates a new attachment on an existing task or plan rather than modifying an existing one. Additional details such as idempotency or exact mutation behavior are not necessary given the annotation 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 only two sentences and every part contributes: the first sentence gives the trigger and scope, the second gives a clear exclusion. No fluff, repetition, or unnecessary background material is present.

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 100% schema coverage, the output schema, and the non-read-only/non-destructive annotations, the description provides enough decision context for correct tool selection and invocation. It could be slightly richer by naming the editing alternative explicitly, but the existing wording is sufficient to avoid the main confusion with update_list_attachment.

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 parameters are already documented in the schema itself. The description adds general context about attaching lists to existing tasks or plans, but it does not need to restate parameter meanings. This aligns with the baseline of 3 when the schema carries the detailed parameter documentation.

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 has a clear verb ('add') and resource ('list attachment to an existing Familia task or plan'), and it enumerates concrete use cases: checklist, shopping list, packing list, or structured subtasks. It also explicitly rules out editing an existing attachment, which distinguishes it from update_list_attachment without needing to open 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 clearly states when to use the tool ('when the user asks to add a new checklist, shopping list, packing list, or structured subtasks to an existing Familia task or plan') and provides a direct exclusion ('Do not use for editing an existing attachment'). It stops short of naming sibling alternatives like update_list_attachment or create_list_task explicitly, but the 'existing' and 'do not use for editing' cues are strong enough for routing.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description adds meaningful behavior: it is a creation operation and explains that repeated lists should become a single recurring task, not multiple one-time tasks. This is useful behavioral context not carried by the annotations 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?

The description is appropriately concise: two sentences with a clear front-loaded trigger condition, a recurrence rule, and an explicit anti-use case. No filler or repetition of schema fields.

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 rich input schema, output schema, and annotations, the description covers the key decision points: when to create a list task and how to handle recurring lists. It could have explicitly named the sibling for plain task creation (familia_create_task) or standalone list attachments, but the existing exclusions make it sufficiently complete.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters thoroughly. The description adds a high-level note about repeatRule, but it does not add new parameter meaning beyond what the schema already provides; a 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 clearly identifies the verb (create) and resource (list task), and lists concrete trigger examples: shopping list, packing list, checklist, or any Familia task with list items. It also distinguishes the tool from editing an existing list attachment, which is a sibling 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?

It explicitly states when to use the tool ('Use this when...'), gives a conditional rule for recurring lists via repeatRule, and includes a clear exclusion ('Do not use when editing an existing list attachment'). This gives an agent actionable routing guidance beyond the schema.

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 state readOnlyHint=false, so the description carries the burden of disclosing creation behavior. It adds useful behavioral context: recurring plans should be created as one schedule, separate dated actions belong in relatedTasks rather than notes, and standalone task reminders belong elsewhere. This goes beyond the mere fact that the tool creates a plan, though it doesn't detail side effects or permission requirements.

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

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

The description is a single dense paragraph, but every sentence earns its place: primary usage, recurrence handling, relatedTasks handling, and exclusion with alternatives. It is front-loaded with the core purpose and avoids redundant restatement of schema fields.

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

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

For a 16-parameter create tool with a rich schema and an existing output schema, the description covers the key selection and invocation decisions: what counts as a plan, how to model recurring schedules, how to model associated actions, and which sibling tools to use instead. Nothing critical for correct high-level use 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 94%, so most parameters are already well documented in the structured schema. The description adds cross-parameter semantics that the schema alone doesn't: how to choose between rrule, relatedTasks, notes, and when to route to create_task or batch_write. This meaningfully supplements the schema without repeating it.

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 an explicit, specific verb and resource: 'create a Familia plan item' for a broad list of plan categories, and it immediately names the sibling tools it is not (familia_create_task, familia_batch_write). This makes the tool's identity unambiguous even before 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?

It gives direct when-to-use guidance for plans versus standalone tasks, tells the agent to collapse recurring requests into a single rrule-based plan, and instructs how to handle multi-action events with relatedTasks. It also explicitly says 'Do not use for standalone responsibility-style task reminders' and names the alternatives, leaving no ambiguity about routing.

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

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

Annotations only indicate that the tool is not read-only, not destructive, and not open-world, leaving the description to carry behavioral meaning. The description adds a meaningful behavioral nuance: recurring tasks should be consolidated into one recurring item via repeatRule rather than created as many one-time tasks. It does not describe return values or side effects, but the presence of an output schema and non-destructive annotations mitigate that gap.

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

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

The description is three sentences with no wasted words. It front-loads the primary use case, immediately gives usage guidance, and then states exclusions with sibling alternatives. 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?

Given the tool's 13 parameters, the description sufficiently covers intent mapping, recurring-task behavior, and sibling differentiation. Combined with a fully documented schema and output schema, an agent can correctly select and invoke the tool. Minor details like todoList attachment or owner/assignee handling are left to the schema, but they are fully described there, so no critical gap exists.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does mention the repeatRule parameter and its purpose, but the schema's own repeatRule description already explains the same recurring-schedule guidance, so the main description adds little parameter-level meaning beyond the structured 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 creates a responsibility-style Familia task, agreement, reminder, or chore, which is a specific verb+resource combination. It also explicitly distinguishes itself from familia_create_plan (calendar events) and familia_create_list_task (lists), so an agent can tell it apart from siblings without inspecting other 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?

It provides an explicit when-to-use trigger ('when the user asks to create a responsibility-style Familia task...'), explicit exclusions ('Do not use for calendar-style events... use familia_create_plan instead'), and a clear routing rule for lists ('use familia_create_list_task'). It also gives a concrete rule for recurring tasks: provide repeatRule and create one recurring task rather than multiple.

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 convey destructiveHint=true and readOnlyHint=false, lowering the burden on the description. The description adds useful context about what is deleted and that it must be an existing attachment, but it does not disclose permanence, cascading effects, or any post-deletion behavior. It meets the baseline but does not go beyond it significantly.

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 tight sentences that front-load the core usage condition and immediately follow with an exclusion. Every sentence earns its place; 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 simple destructive operation with one required parameter, an output schema, and annotations covering the destructive nature, the description plus schema and annotations is fully sufficient. It tells the agent exactly when to invoke the tool and what it acts on.

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 already documents both parameters well: attachmentId is described as the Familia attachment id to delete, and timezone as the IANA timezone. The description adds no additional parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb ('delete or remove'), a specific resource ('existing Familia photo, checklist, or list attachment'), and clearly distinguishes this from related operations. The scope is clear enough that an agent can differentiate it from sibling tools like familia_delete_plan or familia_update_list_attachment.

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

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

Explicitly says when to use the tool ('only when the user explicitly asks to delete or remove') and when not to use it ('Do not use for hiding or summarizing attachments'). This gives clear positive and negative triggers with no reliance 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 aligns with annotations: destructiveHint=true and readOnlyHint=false confirm this is a mutating, destructive operation. The description adds the nuance that the target must be an existing plan item and that deletion should only happen on explicit user request, but it does not disclose additional behavioral details such as irreversibility or side effects. Since annotations already cover the destructive nature, a 3 is appropriate.

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 concise sentences with no filler. The critical usage condition is front-loaded, and the differentiation from the sibling tool is packed into a short second sentence. 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?

For a simple two-parameter mutation tool with 100% schema coverage, a destructive Hint annotation, an output schema, and explicit sibling routing, the description is complete. An agent has enough information to select the tool, populate the required planItemId, and understand the destructive nature of the operation.

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

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

Schema description coverage is 100%, so the schema already documents both timezone and planItemId. The description reinforces that planItemId refers to an existing plan item, but this is a minor addition; the parameter semantics are carried by the schema. 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 uses specific verbs ('delete, remove, or cancel') tied to a clear resource ('existing Familia plan item'), making the tool's purpose unmistakable. It also differentiates from the sibling familia_update_plan by explicitly stating what this tool is not for.

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 first sentence states exactly when to use the tool: only when the user explicitly asks to delete, remove, or cancel an existing Familia plan item. The second sentence names the alternative (familia_update_plan) and the conditions that should route to it, providing excellent when-to-use and when-not-to-use 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 beyond the destructiveHint annotation by specifying exactly what gets removed: the task record plus related schedules, occurrences, reminders, and attachments. This gives the agent a clear picture of the destructive scope, though it could have explicitly noted irreversibility.

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 concise sentences with no filler. The usage condition is front-loaded, and the second sentence adds necessary behavioral detail about cascaded deletion.

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 single-target tool, the description covers what it does, when to use it, and what will be affected. An output schema exists for return values, so the description's omission of response details is acceptable.

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

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

Schema description coverage is 100%, so the parameters are already documented. The description adds the context that this targets an existing task and performs permanent deletion, but it does not add meaningful semantic detail beyond the schema's 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 clearly identifies the action as a permanent/hard delete of an existing Familia task, using a specific verb and resource. It also distinguishes itself from softer operations like cancellation by explicitly emphasizing 'permanently delete' and 'hard delete'.

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

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

The description states a clear condition for use: only when the user explicitly asks for permanent deletion. It lacks an explicit mention of the alternative 'cancel' tool for non-permanent cases, but the 'only when' phrasing provides a strong exclusion criterion.

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 destructiveHint=false, so the safety profile is covered. The description adds 'without hard Familia availability blockers' which hints at the blocking semantics, but it does not explain behavior like busy-hour windows or policy effects beyond what the schema already documents.

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 tight sentences, with the primary usage scenario front-loaded and a useful exclusion added. 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?

The tool has 9 fully documented parameters, an output schema, and read-only annotations. The description focuses appropriately on when to use the tool, which is what an agent needs most for selection. Minor gaps like naming sibling tools or describing result shape are largely covered by other structured fields.

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 every parameter already has a meaningful description. The tool description adds no additional parameter-level insight, which is acceptable given the schema carries the full burden.

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 identifies the tool's purpose: finding free days, open dates, vacation windows, long weekends, and consecutive days without availability blockers. It also distinguishes itself by explicitly saying not to use it for listing tasks on one known date, though it does not name a specific sibling tool.

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

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

The description gives explicit trigger phrases ('find free days', 'open dates', 'vacation windows', 'long weekends') and a clear negative case ('do not use for listing tasks on one known date'). It lacks a named alternative tool, but the when/when-not guidance is strong.

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, openWorldHint=false, and destructiveHint=false, so safety and side effects are covered. The description adds that the tool includes tasks, plans, and connected calendar events, giving insight into its result content. No contradictions with annotations exist.

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 concise, consisting of two sentences that avoid redundancy. It front-loads the primary purpose and includes only essential clarifications about when not to use the tool, making it easy to parse.

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 an output schema and the description clarifies the scope of returned items (tasks, plans, events), an agent has enough context to invoke it correctly. The description also covers edge cases like 'omitted for today' and 'time window' by referencing the schema parameters, making it complete for this tool's complexity.

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% description coverage for all six parameters, including formats and defaults. The tool description itself does not elaborate on parameters, but since the schema is already comprehensive, this meets the baseline without needing additional explanation.

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 function: retrieving Familia items (tasks, plans, calendar events) for a specific date or time window. It also distinguishes it from other tools by explicitly excluding broad text search and multi-week availability, which are covered by sibling tools like search_items and weekly_overview.

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 usage guidance: 'Use this when the user asks for Familia items on a specific date or in a specific time window' and warns 'Do not use for broad text search or multi-week availability.' This effectively tells the agent when to invoke this tool and when to consider 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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds intent categories but does not disclose behavior like ordering, aggregation semantics, or how the inbox relates to other views; this is acceptable but not rich.

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 front-loaded sentence with no wasted words. It immediately states when to use the tool and lists concrete user phrasings, making it efficient and easy to parse.

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 presence of an output schema and fully documented parameters reduces the burden on the description. Still, the description overlaps with familia_list_past_due by including 'overdue tasks' and does not clarify the boundary between the inbox and other sibling tools, so contextual routing is not fully complete.

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 already fully described in the schema with defaults and semantics, so schema coverage is 100%. The description adds no parameter-level meaning beyond the general 'what is waiting on them' context, matching the baseline for fully documented params.

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 identifies the resource as 'inbox / items needing attention' and provides a specific verb (get) plus a broad list of user intents. However, it does not explicitly differentiate this from overlapping siblings like familia_list_past_due or familia_get_next_up, so the distinction relies on inference.

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 by enumerating trigger phrases such as 'inbox', 'items needing attention', and 'overdue tasks'. It does not mention when not to use it or name alternatives, so exclusion criteria 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?

Annotations already establish that this is a safe read-only operation, and the description adds meaningful behavioral context: the default scope is personal assigned items, household scope is only for family-wide wording, and owner-only tasks must not be misattributed to the current user. This goes beyond the annotations and gives an agent useful operational 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?

Three focused sentences with no filler. The usage trigger is front-loaded, followed by scope guidance and a critical correctness guardrail. 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?

With full schema coverage, read-only annotations, and an output schema present, the description covers the essential selection and invocation context. The only notable gap is that it does not define how 'next' is ordered or what exactly constitutes an 'upcoming family item', but this is not critical given the output schema.

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

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

Schema description coverage is 100%, so the schema already documents limit, scope, timezone, and householdId. The description adds extra semantic context around scope and output attribution, particularly the warning about owner-only tasks. It does not add much about the other parameters, but the schema already carries that burden.

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 identifies when the tool applies: questions about 'what is next', 'what should I do now', 'next task', or 'next upcoming family item'. It does not use an explicit verb like 'retrieves' or 'returns', and it does not explicitly distinguish itself from siblings such as get_today_schedule or get_weekly_overview, but the intended purpose is still clear.

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 trigger phrases and explicitly says when to use personal vs household scope. It also adds the important guardrail about not describing owner-only tasks as assigned to the current user. It does not explicitly state when NOT to use the tool or name an alternative, so it falls just short of the highest bar.

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 provide readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the output scope ('Includes tasks, plans, Google/calendar events, and an overdue summary') but no additional behavioral traits like timezone handling or household aggregation 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?

Two compact sentences: the first is an actionable trigger, the second is the output scope. There is no fluff, no repetition of schema content, and important information is 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?

Given the read-only annotations, fully documented optional parameters, and existence of an output schema, the description covers what an agent needs to select and invoke the tool. The only notable omission is explicit routing to sibling schedule tools for non-today queries.

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: timezone has an IANA example and default, and householdId explains its optionality and omission behavior. The description adds no parameter-level meaning, 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 clearly identifies the resource ('today's agenda, today's tasks') and provides concrete user phrasings. It states the content scope (tasks, plans, Google/calendar events, overdue summary), but does not explicitly distinguish itself from siblings like familia_get_tomorrow_schedule.

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?

'Use this when the user asks about today's agenda...' gives explicit when-to-use conditions with natural language examples. However, it does not mention when not to use it or point to alternative tools, so it lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by disclosing exactly what the result aggregates: tasks, plans, Google/calendar events, and an overdue summary.

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 short and front-loaded with the trigger phrase. Minor redundancy exists in repeating 'tomorrow's' across several list items, but it remains readable and efficient overall.

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 the trigger, scope, and content of the response, and an output schema is present to detail the return structure. With a complete input schema and read-only annotations, nothing essential is missing for an agent to invoke 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 description coverage is 100%, so both parameters (timezone and householdId) are already fully documented in the input schema. The description adds no additional parameter-level meaning, which is acceptable given the schema's completeness.

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 resource (tomorrow's schedule) and the user intents that should trigger it: agenda, tasks, plans, and preparation. The clear temporal scope ('tomorrow's') distinguishes it from sibling tools like familia_get_today_schedule and familia_get_day_overview without needing to name them.

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 condition: use when the user asks about tomorrow's agenda, tasks, plans, or preparation. It does not explicitly state when not to use it or name alternative tools, but the 'when to use' guidance is clear and 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is fully covered and the description does not contradict it. The description adds only the multi-day scoping behavior beyond what annotations provide; it does not disclose how households are aggregated, what the overview contains, or any limits on results. With the safety burden carried by annotations, a 3 is appropriate.

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 front-loaded sentence that directly states the invocation conditions. It is efficient but slightly redundant—'this week', 'the next week', and 'family schedule for the week' overlap, and 'upcoming days' plus 'multi-day planning overview' cover similar ground.

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 low-complexity, read-only tool with a rich output schema and fully documented optional parameters, the description covers the key selection criteria an agent needs. It is complete enough to route the agent correctly among 24 siblings; the only minor gap is that it does not clarify what an 'overview' contains or how it differs from familia_get_next_up or familia_find_free_days.

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 all four parameters individually documented in the input schema, so the baseline of 3 applies. The description adds nothing about parameters beyond what the schema already states—it does not explain defaults, formats, or the householdId omission behavior.

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 conveys that this tool provides a multi-day family schedule overview, and the temporal scope ('this week, the next week, upcoming days, multi-day') distinguishes it from day-level siblings like familia_get_today_schedule and familia_get_day_overview. However, it is phrased as a usage trigger ('Use this when...') rather than a direct verb+resource statement, and it never names the sibling alternatives it contrasts with.

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 entire description is an explicit when-to-use statement, listing concrete user intents ('this week', 'next week', 'upcoming days', 'multi-day planning overview'). This gives clear routing context relative to the day-specific siblings. It stops short of a 5 because it does not explicitly state when NOT to use it or name specific alternative tools by name.

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 destructiveHint=false, so the safe-read profile is covered structurally. The description adds modest value by clarifying that the tool serves as an ID-discovery step before edits, implying attachment IDs are returned, but it adds no deeper behavioral detail such as pagination or filtering 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?

Two sentences, both earning their place: the first states the main use case, the second states a secondary workflow trigger. The most important scoping information is front-loaded and there is 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?

With an output schema present and 100% parameter schema coverage, the description does not need to explain return values or parameter formats. For a low-complexity read-only list tool, the description plus structured fields cover what an agent needs; it omits only minor context like whether results are ordered or limited.

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 targetType, targetId, and timezone each documented in the schema itself. Per the rubric, high schema coverage sets a baseline of 3, and the description adds no parameter-level meaning beyond what the schema already provides.

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 verb and resource — 'list attachments' on an existing Familia task or plan — and further scopes it to 'photos, checklists, or list attachments' so an agent knows exactly what is returned. This scope clearly differentiates it from siblings like familia_search_items or familia_get_inbox.

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

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

The description gives an explicit trigger condition ('when the user asks what photos, checklists, or list attachments are attached') and a workflow rule ('Use before editing an existing list attachment when the attachment id is unknown'). It doesn't explicitly name when-not-to-use it or contrasting alternatives, but the guidance is concrete enough to route correct invocation.

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 destructiveHint=false, so the safety profile is covered. The description adds the useful context that the tool is for resolving unknown user ids, but it does not detail behavior such as what is returned or ordering. The output schema exists, which lowers the burden.

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 with no filler, and the condition is front-loaded. It loses a point because it relies on the title to convey the actual action (listing members), making the standalone description slightly indirect.

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 lookup with an output schema, the description and annotations provide enough context for an agent to invoke it correctly. The required householdId is documented in the schema, and the description tells the agent exactly the scenario in which the tool is needed. It is complete but not unusually rich.

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 have descriptions in the schema, so schema description coverage is 100%. The tool description itself adds no parameter-level meaning beyond what the schema provides, matching the baseline score for full schema coverage.

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

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

The description is condition-driven rather than a direct statement, but it clearly implies the tool lists household members to reveal their Familia user ids. It focuses on the use case (assignment/ownership/sharing), which distinguishes it from the sibling list_households tool. A more explicit 'List members of a household' phrasing would make it a 5.

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

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

The description explicitly states when to use the tool: when a task/plan must be assigned, owned by, or shared with a named household member whose user id is unknown. It does not name an alternative or state when not to use it, but the condition is precise and 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?

Annotations already indicate read-only, non-destructive, closed-world behavior. The description adds useful behavioral context by revealing that the result includes member names and user ids, which helps an agent know what to expect and how the data can be used for assigning tasks or plans.

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 front-loaded: the first sentence states the exact use case, the second adds content expectations, and the third gives a clear negative boundary. Every sentence earns its place with 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 parameterless read-only list tool with rich annotations and an output schema, the description covers everything an agent needs: when to call it, what it returns, and what it should not be used for. Nothing important 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, so the description does not need to explain any parameter behavior. The schema coverage is complete and there is nothing for the description to compensate for; the baseline of 4 for parameterless tools 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 states a specific action ('list') and a clear resource ('Familia households, families, or shared boards'), and clarifies what the response includes. It also sets boundaries by explicitly saying it is not for tasks, plans, or calendar events, which distinguishes it from the many task- and plan-related sibling 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 an explicit trigger condition ('Use this when the user asks which Familia households... are available') and an explicit exclusion ('Do not use for listing tasks, plans, or calendar events'). This gives an agent clear routing guidance without having to infer when the tool applies.

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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context ('Calendar events are excluded') beyond the annotations, but it doesn't disclose return shape, sorting, or edge cases; the output schema likely covers return structure.

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

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

A single, front-loaded sentence covers the core use case, gives a useful synonym list, and states an exclusion. Every part earns its place; there is no filler or redundant repetition of the tool name.

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 read-only annotations, fully documented optional parameters, and presence of an output schema, the description is complete for invocation purposes. It clearly defines scope and exclusions; a minor gap is not naming sibling tools for alternative routing, but that is not essential for this tool's usage.

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 all three parameters (limit, timezone, householdId) are already documented in the input schema. The description does not add any parameter-specific semantics beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description uses a specific trigger pattern ('overdue items, past leftovers, missed tasks, unfinished items from previous days') tied to a clear resource, and notes that calendar events are excluded. It distinguishes the tool's scope from schedule-oriented siblings, though it does not name any sibling explicitly.

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 explicitly states when to use the tool with concrete user-phrase examples and adds an exclusion for calendar events. It doesn't mention specific alternative tools or when-not-to-use scenarios, but the trigger list is clear enough for an agent to route 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, so no safety contradiction exists. The description adds little behavioral detail beyond searching, but nothing contradicts annotations; baseline is appropriate.

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 concise sentences with no redundant wording. Key purpose and exclusion are front-loaded, making it easy for an agent 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?

Given the simple read-only search nature, the description is complete. Output schema is present, so return values do not need to be described. No critical operational context 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 covers all parameters at 100%, and the description adds meaningful semantic context by specifying the searchable fields (title, notes, description, location). This goes slightly beyond the raw 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 the action ('find') and the specific resource ('Familia tasks, plans, or connected calendar events'), along with the searchable fields. This makes its purpose distinct and immediately recognizable.

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 ('Use this when the user asks to find...') and a clear negative directive ('Do not use for public web search or unrelated document search'). However, it does not name alternative sibling tools to prefer in those negative cases.

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 transparently discloses the destructive, non-incremental nature of the operation: 'This replaces the existing list content.' This goes beyond the annotations, which already mark destructiveHint=true and readOnlyHint=false, and there is no contradiction with those 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 two sentences with no filler. It front-loads the use cases and then delivers the critical replacement caveat and unknown-ID fallback, making it highly scannable for an agent.

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 core selection criteria, destructive replacement semantics, and unknown-id workflow are covered. The only gap is that for add/reorder/edit operations, an agent may need to fetch the current items first to preserve existing content, and this isn't explicitly called out—though it is strongly implied by 'replaces the existing list content.'

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 parameters like attachmentId, items, title, and timezone are already explained by the input schema. The description adds useful operational context about replacement but does not provide additional parameter-level details beyond what the schema already gives.

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 a specific verb ('update') and enumerates the exact user intents it covers: edit, add, remove, reorder, or mark items. It clearly identifies the resource as an 'existing Familia checklist/list attachment,' which distinguishes it from create/delete/list sibling 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?

It explicitly states when to use the tool: when the user asks to modify items in an existing attachment. It also provides a conditional workflow: 'list attachments first if the attachment id is unknown.' However, it does not explicitly name when-not-to-use alternatives such as creating a new attachment.

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

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

The annotations already provide destructiveHint=true and readOnlyHint=false, so the mutating nature is known. The description adds the range of editable aspects but does not explicitly state that fields are replaced wholesale or that omitted fields remain unchanged; the schema's 'replacement' descriptions cover part of this, but the description itself adds limited behavioral depth.

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 with no wasted words. The trigger condition is front-loaded and the exclusion is concise and unambiguous.

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 gives the agent enough to select this tool correctly, while the schema documents all 12 parameters, the output schema covers return shape, and annotations cover the destructive nature. It could add a sentence about replacement semantics or null-clearing behavior, but those are already present in the schema descriptions.

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

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

Schema description coverage is 100%, so the schema already documents every parameter. The description's action words loosely map to parameters like title, startAt, endAt, location, and participantUserIds, but it adds no parameter-level detail beyond what the schema provides.

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 edits an existing Familia plan, with a concrete list of actions (rename, reschedule, move, update location, link tasks, change participants) that distinguishes it from creation or deletion. This is a specific verb+resource statement that an agent can act on.

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 tells the agent when to use the tool ('when the user asks to rename, reschedule, move...') and when not to use it ('Do not use to create a new plan'). This gives clear routing away from the sibling tool familia_create_plan.

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

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

The annotations already indicate this is destructive, and the description adds a valuable behavioral nuance: setting status to done completes the next actionable occurrence so recurring tasks continue. This goes beyond the structured annotations and helps the agent understand a non-obvious side effect. It does not detail other destructive side effects, but the annotation covers the general destructive nature.

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 focused sentences: positive use case, a key behavioral caveat, and an explicit exclusion. It front-loads the most important selection information and contains no filler or repetition of schema details.

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 update tool with 10 parameters, the description covers the core purpose, a key recurrence behavior, and the main exclusion. The output schema covers return values. The main missing piece is guidance around sibling tools such as familia_cancel_task, given that 'cancel' is listed in the description.

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 high, so the baseline is 3. The description adds meaning beyond the schema by mapping user intent (rename, reschedule, reassign, complete, cancel) to the update operation and by explaining the special behavior of status=done for recurring tasks. This is especially useful because the status parameter itself has no description 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 clearly identifies the resource (existing Familia task) and the verbs it covers: rename, reschedule, reassign, complete, cancel, or edit. It also explicitly says not to use it for creating a task. However, it does not distinguish this tool from sibling familia_cancel_task even though 'cancel' is listed as a use case, so sibling differentiation is incomplete.

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 strong positive guidance ('Use this when the user asks to rename, reschedule, reassign, complete, cancel, or otherwise edit an existing Familia task') and an explicit when-not ('Do not use to create a new task'). It does not mention when to prefer siblings like familia_cancel_task or familia_delete_task, so the alternative-routing guidance is incomplete.

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