Nestling

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

Annotations already declare readOnlyHint=false and idempotentHint=false; the description goes further by warning that each call appends a new entry and must not be retried after success, which is actionable context an agent could otherwise miss. It still says nothing about auth/permissions or limits.

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

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

Front-loads the purpose, then usage constraint, then retry warning, then timestamp-format rules. Four sentences, each carrying distinct operational information with no repetition of schema text.

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?

A write tool with full annotations and an output schema, so return values need no explanation. Purpose, when-to-use, retry behavior, and the tricky timestamp/timezone semantics are all covered, leaving nothing an agent needs in order to call it correctly.

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

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

Schema coverage is 100%, but the description adds real meaning beyond it: it enumerates the accepted timestamp formats (ISO 8601, relative, day+time, time only, date+time) and explains the timezone fallback for zone-less times, all of which the schema only labels as 'When it happened'.

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

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

States a specific verb and resource ('Add a diary entry ... to the baby's Nestling diary') and clarifies the entry type as a free-text note or milestone, which cleanly separates it from list_diary and the other create_* logging tools.

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

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

Gives an explicit when-to-use trigger ('only when the user asks to write, note or record something in the diary') plus an operational guard ('do not retry after success'). It never names a sibling alternative (e.g. list_diary for reads), so 4 rather than 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the mutation profile is known. The description adds the operational consequence of non-idempotency ('each call adds a new entry, so do not retry after success') and spells out the timestamp formats the tool will parse, which is genuinely extra 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?

Front-loaded with purpose, then usage gate, then timestamp formats. Three sentences with no filler, though the long parenthetical list of time formats makes the final sentence dense; it earns its place by preventing malformed timestamp calls.

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 non-idempotent create tool with an output schema, full parameter coverage and annotations, this is complete: the agent knows what it writes, when to call it, not to retry, and how timestamps are interpreted. Return values are covered by 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 coverage is 100%, so the baseline is 3, but the description goes beyond it by enumerating the accepted timestamp input formats (ISO 8601, relative, day-and-time, time-only, date-and-time) and noting that zoneless times fall back to the timezone argument — real added meaning for the least obvious required parameter.

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

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

States a specific verb and resource ('Add a feed to the baby's Nestling log') and enumerates the exact feed subtypes (breastfeeding, bottle, solids, expressing), which cleanly separates it from siblings like create_nappy and create_sleep without the agent opening a schema.

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

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

Gives a clear when-to-use gate ('Use this only when the user asks to log or record a feed') and an operational caution ('do not retry after success'). It stops short of naming an alternative sibling (e.g. open_quick_log, list_feeds) or a when-not-to-use beyond the user-intent condition, so it is clear context rather than full routing guidance.

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

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

Annotations already declare non-idempotency, and the description adds the actionable consequence ('Each call adds a new entry, so do not retry after success') plus the timezone fallback chain when the zone is omitted. It does not disclose permissions, rate limits, or failure modes, but for an append-only log tool with annotation coverage this is solid added context.

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

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

Three sentences, each carrying distinct load: what it creates, when to call it (with the retry warning), and how timestamps are parsed. The scoping sentence is front-loaded before the format 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?

An output schema exists so return values need not be explained, and the description covers the remaining gaps an agent needs: exact use condition, non-idempotent retry behavior, and timestamp/timezone interpretation for all five parameters.

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

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

Schema coverage is 100%, so the baseline is 3, but the description materially extends the thin schema text for timestamp ('When the nappy was changed') by enumerating accepted formats — ISO 8601, relative, day+time, time-only, date+time — and clarifying the timezone fallback rule.

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

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

States a specific verb and resource ('Add a nappy (diaper) change to the baby's Nestling log') and enumerates the domain values (Wet, Dirty, Both), which cleanly separates it from create_feed, create_sleep, and create_diary without opening any schema.

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

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

Explicitly scopes invocation: 'Use this only when the user asks to log or record a nappy change,' and adds a retry constraint ('do not retry after success'). It gives a clear condition for use but never names an alternative sibling (e.g. list_nappies or open_quick_log) for the read/edit 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?

Annotations already declare a non-idempotent write (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds the consequence: every call appends a new entry, so retrying after success duplicates data. It does not discuss auth or failure modes, so it stops short of a 5.

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

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

Front-loaded with purpose then the when-to-use constraint, followed by the format enumeration. Every sentence carries information; nothing is redundant 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?

Output schema exists so return values need no explanation. Between the description (formats, timezone fallback, append semantics, non-retry rule) and annotations (write, non-idempotent), an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description materially enriches the start/end semantics with accepted formats (ISO 8601, relative, day+time, time only) and the timezone fallback rule for zone-less times — meaning an agent cannot get from 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?

States a specific verb and resource ('Add a finished sleep session to the baby's Nestling log') and scopes it to completed sessions, which cleanly separates it from sibling creators like create_feed and create_nappy as well as from list_sleep.

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

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

Explicitly states the trigger ('only when the user asks to log or record a sleep that has ended') and adds an operational rule ('do not retry after success'). The only minor gap is that it does not name an alternative tool for in-progress sleeps, but no such sibling exists in the list.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds the returned field set, which is helpful, but since an output schema exists that is largely redundant, and nothing is said about error behavior for a missing/invalid babyId.

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

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

Two sentences, zero filler, with the purpose front-loaded ahead of the usage trigger. Every clause 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 single-parameter read tool with full annotations and an output schema, the description covers purpose and invocation adequately. It is not required to explain return values, though a note on behavior for an unknown babyId would have closed the last 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?

Schema description coverage is 100% and the single babyId parameter is already documented as 'The baby's ID from list_babies' with format and pattern constraints. The description adds no parameter-level detail, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get one baby's details') and enumerates the returned fields (name, birth date, added date). The word 'one' implicitly contrasts with the list_babies sibling, but no sibling is named explicitly, so it falls just short of full differentiation.

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

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

Gives a concrete trigger: 'Use this when the user asks about a baby's age or profile.' That is clear context for invocation, but it names no alternative (e.g., list_babies for discovery) and no exclusion conditions.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value by characterizing the payload categories ('read and log') and by constraining the trigger condition, though it says nothing about size or format (which the output schema covers).

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

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

Two short sentences, front-loaded with the action and scope, followed by the single gating condition. No filler and no restatement of the title.

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 introspection tool with rich annotations and an output schema describing the return, almost nothing is left for the description to carry. The only mild gap is that it doesn't hint at how the capabilities are grouped or whether the answer is static per connection, but the output schema handles that.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. Nothing in the description misleads about inputs, and schema coverage is 100%.

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

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

States a specific verb (List) and a clearly bounded resource (what this Nestling connection can read and log). This makes it immediately distinguishable from the create_* and list_* siblings, which operate on concrete entities rather than on the connection's capability surface.

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 scopes invocation: 'Use this only when the user asks what Nestling can do here.' That is an affirmative when-to-use plus an exclusion, so the agent knows not to reach for it during normal logging or retrieval flows.

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 readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds real context beyond them: overnight sleep crossing midnight is attributed to the day, and it returns data only rather than rendering. It does not mention pagination or response size, but for a bounded one-day summary that is minor.

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

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

Front-loaded with the core purpose, then the content list, then usage examples and the alternative. The enumeration is long but every item is a distinct output field, so it earns its space; slightly dense but no filler sentences.

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 annotations covering the safety profile, the description supplies everything else an agent needs: the aggregation rule for overnight sleep, example intents, and the routing to show_day. Nothing required to call it correctly is missing.

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

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

Schema coverage is 100%, so date, babyId, and timezone semantics (defaults, format, fallback behaviour) are fully documented in the schema. The description only implies date semantics via the midnight-crossing note, which does not extend beyond 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?

States a specific verb and resource (summarise one calendar day for a baby) and enumerates exactly what the summary contains: sleep totals, counts, bottle ml, breastfeeding minutes, nappies, and a timeline. This clearly distinguishes it from the list_* and create_* 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?

Provides concrete triggering questions ('how did she sleep today?', 'how many feeds yesterday?') and explicitly routes to the alternative for visual output: 'to show the day visually, call show_day.' Both when-to-use and the alternative are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is fully covered without the description. The description adds only the notion that the returned ID is 'stable', which is mild extra context and not a rich behavioral disclosure.

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

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

Two short sentences, output shape stated first and the usage trigger second. No filler, nothing repeated from the schema or annotations.

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 zero parameters, an output schema carrying the return structure, and annotations covering safety and idempotency, the description supplies everything an agent needs to call it correctly. Nothing essential 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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. The description correctly implies no input is required.

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 ('Return') and resource ('the connected Nestling account') and names the payload shape (account ID and email). It is clear on its own, but it does not distinguish itself from the sibling get_user, which an agent could easily confuse with the 'connected account' concept.

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

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

Gives an explicit trigger condition: 'Use this when the user asks which Nestling account is connected.' That is a clear when-to-use statement. It stops short of naming alternatives or when-not to use it (e.g., versus get_user), so it is not a full routing rule.

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, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered. The description adds the returned fields (email, ID), which is modest extra context, but says nothing about auth requirements or behavior beyond what the annotations and output schema convey.

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

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

A single short sentence with the resource, scope, and payload front-loaded. No filler, no redundancy; 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?

With an output schema present, return values need not be re-explained, and annotations carry the safety profile, so the description is nearly sufficient for a zero-parameter read. The one real gap is the absence of any signal separating this from the similarly named get_profile sibling.

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

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

The tool takes zero parameters, so parameter documentation is not needed and the baseline is 4. The description correctly implies no input is required by scoping the call to the signed-in user.

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

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

States a specific verb (Get) and resource (signed-in user's Nestling profile), plus the returned fields (email, ID). The scope word 'signed-in' distinguishes it from a generic profile fetch, but it does not differentiate itself from the sibling get_profile, which an agent could easily confuse it 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?

Usage is only implied: 'signed-in user's ... profile' suggests it is for retrieving the current account rather than another entity. There is no explicit when-to-use, no when-not-to-use, and no mention of the competing get_profile sibling, so the agent must infer the 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 already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral scope beyond that by clarifying that the result set spans owned plus shared babies, which an agent cannot infer from the annotations.

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

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

Two sentences with no wasted words; the purpose comes first and the usage directive follows immediately. Nothing is redundant with 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?

With zero parameters, an output schema present, and annotations covering the safety profile, the description only needs to convey scope and timing. It does both, so an agent has everything required to call it correctly.

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

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

The tool takes no parameters, so the baseline is 4. The description still introduces the babyId concept that this tool produces for other tools, giving the agent context for why the call exists.

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

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

States a specific verb (List) and resource (babies) scoped to the user's Nestling account, and adds the important qualifier that babies shared with the user are included. This distinguishes it cleanly from the singular sibling get_baby, which requires a known id.

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 reach for this tool first: when the user has not named a baby, or when a downstream tool needs a babyId. It stops short of naming the alternative (get_baby) or stating when not to use it, so it is strong but not fully 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 already declare this is a read-only, idempotent, non-destructive, closed-world operation, so the safety profile is covered. The description adds that results are scoped to a time range and contain notes/milestones, but says nothing about ordering, pagination, or empty-result 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, zero filler, with the what (list diary entries in a time range) front-loaded ahead of the when-to-use clause.

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?

An output schema exists, so return-value detail is unnecessary, and all four parameters are fully described in the schema. The definition covers what and when, though it omits ordering/volume expectations an agent might want for a listing tool.

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

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

Schema description coverage is 100%, with start/end formats, babyId provenance, and timezone fallback all documented in the schema itself. The description only restates that a time range is required, adding no meaning beyond structured fields. Baseline 3 applies.

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

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

States a specific verb (list) plus resource (a baby's diary entries) and characterizes the content as free-text notes and milestones within a time range. This clearly distinguishes it from siblings such as list_feeds, list_nappies, and list_sleep.

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

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

Gives explicit trigger conditions: when the user asks what they wrote, or about notes and milestones. It does not name competing alternatives (e.g., get_day_summary or show_day for a broader day view), so it stops short of full routing guidance.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false, so the safety profile is covered. The description adds the value of the fields returned and the granularity of data (individual feed times), which helps the agent reason about the response. It doesn't mention pagination or result limits, so it falls just short of a 5.

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

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

Two sentences, zero filler, with the tool's scope and returned fields front-loaded before the routing guidance to get_day_summary.

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

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

An output schema exists, so return values need not be described, and the schema fully documents all four parameters. For a read-only list tool, the description plus structured data covers everything an agent needs to call it correctly.

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

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

Schema description coverage is 100%, with start/end documenting all accepted formats and timezone explaining its fallback behavior. The description adds no parameter-level detail beyond what the schema 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?

States a specific verb (List) and resource (a baby's feeds) and enumerates the feed subtypes it covers (breastfeeding, bottle, solids, expressing), plus the returned fields (amount ml, duration seconds, side). It also names the sibling get_day_summary so the agent can distinguish scope without opening a schema.

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

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

Explicitly states when to use it (feeds across several days or exact feed times) and names the alternative plus its selecting condition (one day's totals → get_day_summary). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that each record is classified as Wet, Dirty or Both, but says nothing about pagination, ordering, or limits beyond the annotations.

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

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

Two tightly written sentences with the scoping rule front-loaded and the alternative routing second. No filler, though it is very short and could carry slightly more context at no cost.

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, return-value explanation is unnecessary, and annotations plus a fully documented schema cover parameters and safety. For a simple filtered-list tool the description is 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% – all four parameters, including the flexible time formats for start/end and the timezone fallback, are documented in the schema. The description adds no syntax or format guidance beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb (List) and resource (a baby's nappy changes) plus scope (within a time range) and the value domain (Wet, Dirty or Both). It clearly differentiates itself from the sibling get_day_summary, which covers single-day totals.

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

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

Explicitly says when to use it ('across several days') and names the alternative tool plus its selecting condition ('For one day's totals, prefer get_day_summary'). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description still adds a real behavioral nuance beyond the annotations: filtering is by session *start* time within the range, and each result carries start, end and length in minutes, which clarifies output shape.

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 short sentences, zero filler, with the core scope stated first and the routing caveat last. Every clause carries information an agent needs.

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?

Output schema exists, so return values need no prose. Combined with the stated range semantics, the alternative-tool routing and the safety annotations, an agent has everything required to select and call this 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 babyId, start, end and timezone are already fully documented with accepted formats and timezone fallback behavior. The description adds no parameter detail, which is the expected baseline when the schema carries the load.

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

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

States a specific verb and resource (list a baby's sleep sessions) plus the scoping rule (sessions that started within a time range) and the returned fields. It also explicitly names get_day_summary as the tool it is not, so an agent can distinguish it from siblings without reading 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?

Gives both sides of the routing decision: use this for multi-day ranges or exact sleep times, and prefer get_day_summary for a single day's totals. This is an explicit when-to-use plus a named alternative, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data and the description adds nothing on top. It does not explain what 'open' actually does for an agent (navigation vs. returning view content), nor whether the sidebar context matters. The only nuance is the mild tension between a navigation-sounding 'open' and readOnlyHint, which the description leaves unaddressed.

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 short sentence with no filler, front-loaded with the verb and target. Nothing is padded or repeated from the 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?

An output schema exists, so return values need no explanation, and the parameters are fully documented in the schema. What remains missing is the one thing only the description could supply: what opening a dashboard means relative to show_day and get_day_summary, and whether this is a UI navigation action. Adequate but with a clear gap for a tool sitting in a dense cluster of view-related siblings.

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 schema already explains date format and today-default, babyId sourcing from list_babies and the single-baby fallback, and timezone fallback behavior. The description adds no parameter meaning beyond that, so the baseline 3 for fully documented schema 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 verb-plus-resource is present ('Open the Nestling day view'), so the general purpose is legible, but the qualifier 'from the sidebar' describes a UI affordance rather than the tool's effect, and the description never distinguishes it from the close siblings show_day, get_day_summary, or open_quick_log. An agent cannot tell from this text which of those four view-related tools to pick.

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

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

There is no when-to-use guidance, no condition that selects this tool over show_day or get_day_summary, and no note on prerequisites. The single sentence gives the agent nothing to route on when several siblings plausibly open or summarize a day.

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, idempotent, non-destructive, non-open-world operation, so the bar is lower. The description adds genuinely useful non-annotation context: this is a UI action that opens a panel beside the conversation rather than returning data. It stops short of saying what the agent should do after the panel opens.

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 sentence, front-loaded with the verb and the resource, with the scope clause doing useful work. 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?

An output schema exists so return values need not be explained, and the tool takes zero required parameters, making it structurally simple. The description covers purpose and the UI-panel behavior adequately; only the post-open interaction model is unstated, which 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?

Schema description coverage is 100%, and the schema already documents date, babyId and timezone thoroughly (formats, defaults, fallback behavior). The description adds no parameter-level meaning beyond that, 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?

Specific verb ("Open") plus a concrete resource (a panel beside the conversation) and an explicit scope (logging feeds, sleep and nappies). An agent knows exactly what this does. It does not, however, distinguish itself from UI-oriented siblings like open_dashboard or show_day, which could plausibly be confused with it.

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

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

Usage is implied by the stated purpose — call it when the user wants to log feeds, sleep or nappies — but there is no explicit when-to-use, no mention of when to prefer the data-mutating siblings (create_feed, create_sleep, create_nappy) instead, and no prerequisites stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description adds genuinely new behavioral context: this renders a visual, interactive surface (a timeline the user can scroll and add to) rather than returning plain data, which is not derivable from the annotations. It stops short of mentioning permissions or what happens to the underlying data, keeping it at 4.

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

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

Two sentences, zero filler. The purpose and visual nature come first, then the usage trigger, then the alternative — well front-loaded and appropriately sized for the tool's 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?

The tool has an output schema, so return values need not be explained, and the description covers purpose, content, trigger and the alternative tool. Nothing an agent needs to select and invoke this 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% and all three parameters (date, babyId, timezone) are documented with defaults and formats in the schema itself. The description adds no parameter-level meaning beyond what the schema provides, 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 (show) and resource (one day for a baby), enumerates the content displayed (total sleep, feeds, nappies, scrollable timeline), and explicitly names the sibling it is not (get_day_summary). An agent can distinguish it from list_* and get_day_summary without opening any schema.

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

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

Gives an explicit trigger ('when the user asks to see, show or open their day or timeline') and an explicit exclusion with the alternative to use instead for non-visual answers ('For a plain answer without a visual, use get_day_summary'). Both when-to-use and when-not-to-use are covered.

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