Dadiosity

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

Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses substantial behavior: safety checks run first, crisis input gets a crisis answer, health questions get a not-medical-advice refusal, diagnostic questions get a can't-diagnose answer, no-fit cases return nearest lessons, and the tool never writes a new lesson. It also states the age band never changes matching and warns when the band is outside the toddler range, which is valuable context an agent could not infer from 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 front-loaded with the core purpose and then covers fallback and safety behavior in a logical order. It is somewhat long and repeats the point that age band does not change matching, but nearly every sentence carries useful information for 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 two-parameter lookup tool with no output schema, the description is complete: it explains what is returned, what happens when nothing matches, how safety cases are handled, and how the optional age band behaves. An agent has enough information to call the tool correctly and interpret the results.

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 parameters, including the situation example and the age-band enum. The description reinforces that situation is a few of the parent's own words with no names or personal details and that age band is context only, but it adds little beyond the structured schema, 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 specific verb and resource: it returns the one written lesson that matches the parent's described hard part, quoted word for word, and it lists the lesson components. This is clear enough for an agent to understand what the tool does, but it does not explicitly distinguish itself from the sibling search_lessons or tonight_plan 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 explains the matching behavior, the no-fit fallback, and the safety-first routing, which gives useful context for when the tool applies. However, it never names the sibling tools or states when an agent should choose get_lesson over search_lessons, tonight_plan, or the other activity tools, so selection guidance is only implied.

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 safe, idempotent, closed-world read, and the description still adds substantial behavior: the pick rotates daily and is stable within a day for identical inputs, different inputs open different parts of the bench, and an impossible minutes constraint yields an honest 'shortest fit' fallback rather than fabrication. It also says what is returned verbatim (activity text, duration, what to grab), with no annotation contradiction.

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

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

Front-loaded with the core purpose, then the tier mapping, then rotation and fallback behavior — a sensible ordering. The single long colon-chained opening sentence is dense, but each clause (tier semantics, determinism, fallback) carries distinct information that 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?

There is no output schema, and the description compensates by naming the return fields (verbatim activity, duration, what to grab). For a two-optional-parameter read tool it also covers the non-obvious cases: same-input determinism, daily rotation, and the no-short-enough fallback, 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%, so baseline would be 3, but the description adds real meaning: it maps 'low'/'some'/'full' to empty-tank, small, and big tiers and explains that minutes acts as a hard cap on run length. It stops short of clarifying edge behavior for a fractional or boundary minutes value, which the schema's 1-120 range already covers.

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: it returns exactly one evening activity from a 27-item bench, constrained by energy and minutes. That is clearly distinguishable from get_lesson and search_lessons, though the near-sibling weekend_pick (an obvious alternative for a different day) is never named, so differentiation is implied by 'evening' rather than explicit.

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 rather than stated: the parent supplies the energy they have left and the minutes available, and 'Omit if any energy/length is fine' appears only in the schema. There is no explicit when-not guidance and no named alternative, so an agent must infer that weekend_pick or tonight_plan cover other planning horizons.

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 readOnly, idempotent, non-destructive, closed-world, so the bar is lower, but the description still adds substance: it names the returned fields (lesson number, title, the one line to keep, an honest count), discloses the empty-result fallback, and warns that safety routing runs first. That safety pre-emption is a behavioral trait not encoded anywhere in the structured fields.

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

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

Four sentences, front-loaded with the verb and the returned fields, then the fallback and the get_lesson contrast. The parenthetical list of topic examples plus "and the rest of the bank's own topic words" runs a little long, but every sentence 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?

There is no output schema, so the description correctly spends words on return contents and the empty-result shape, and it flags the safety override. For a one-parameter read tool with full annotation coverage, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and describes the single topic parameter, so the baseline is 3. The description adds that valid topics are drawn from "the bank's own topic words" rather than free text, which meaningfully constrains how an agent should pick a value beyond the schema's loose "a topic in a word or two."

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?

"Lists the written Dadiosity lessons filed under a topic" gives a specific verb (lists) and resource (lessons), and the examples (tantrums, listening, mornings, hitting, bedtime) pin down the topic bank. It also explicitly separates itself from get_lesson with "It lists only; get_lesson reads one in full."

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 covers the primary case, the empty case ("When nothing is filed under the topic, it says so and lists topics that do exist"), and the alternative tool for full content (get_lesson). It also routes medical or diagnostic topics to the safety answer instead of a list, which is a real usage carve-out an agent could not infer.

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, so the safety burden is light. The description still adds real behavioral context beyond them: output is deterministic per date ('the same date always gives the same plan'), there is no per-family memory, and the site's 'Another one' swap is not an input — which preempts an agent from hunting for a variation/seed parameter.

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 content is front-loaded, leading with what the plan is and following with the components, then the determinism and no-memory caveats. The enumerative first sentence is long and dense, but each clause (activity duration, what to grab, lesson quoted in full with puzzle line) carries genuine information rather than filler.

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

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

There is no output schema, so the description must carry the return-value burden, and it does — listing every section of the plan and noting the lesson is quoted in full with its puzzle line. Combined with the stated determinism and absence of per-family state, an agent has everything needed to call this correctly and to interpret the response.

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

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

Schema description coverage is 100% and the single date parameter is fully documented in the schema, including the local-vs-UTC nuance, so the description need not repeat it. The line 'the plan is fixed by the date' reinforces the parameter's role but adds no format or syntax detail 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?

The description names a concrete resource (the full evening plan for a given date) and enumerates its parts — dinner, phone line, activity block, bath, close, parent's hour — so an agent knows exactly what comes back. It does not explicitly name the sibling tools (get_lesson, pick_activity) or state that this is the whole-evening counterpart to their fragments, leaving that distinction implicit.

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 rather than stated: because the tool returns the entire evening and the lesson 'rides inside the block', an agent can infer this is the pick when the whole plan is wanted and get_lesson/pick_activity are for single pieces. There is no explicit when-to-use, when-not-to-use, or named alternative anywhere in the text.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds real behavior beyond that: filters walk the bench in rotation order to the first match, and the response plainly flags when a pick is not the week's rotation pick. It also states the returned fields verbatim. It does not mention caching or what happens if no pick satisfies a filter combination, which keeps it below 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?

The core purpose is front-loaded in the opening clause and every clause carries information (rotation, returned fields, filter behavior, fallback disclosure). The sentences are long and heavily parenthetical, which makes them slightly dense to parse, but no sentence is filler.

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

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

With no output schema, the description does the necessary work of enumerating the returned pick's fields (what, duration, cost, weather, what to grab). Combined with the fallback explanation, an agent has enough to call and interpret the result; the only gap is the absence of any signal about how filtering degrades if no bench item fits.

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

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

Schema coverage is 100% and each parameter already carries its own description, so the baseline is 3. The description adds one genuine semantic layer by explaining that the weather and length filters operate as a rotation-ordered fallback rather than a hard requirement, but it adds nothing for 'day' or 'date' that the schema does not already cover.

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 gives a specific verb and resource: one pick from Dadiosity's weekend bench of 20 outings/home projects for this week's Saturday or Sunday, resolved on the same weekly rotation as the website. That rotation detail separates it from 'pick_activity' and 'tonight_plan', but those siblings are never named, so the differentiation has to be inferred.

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 rather than stated: an agent can tell this is for a weekend plan and that weather/length filters narrow the bench, but there is no explicit 'use this when X, use pick_activity when Y' guidance. The note that omitting filters yields the rotation pick and filtering may yield a non-rotation pick is helpful, yet no conditions for choosing between the sibling planners are given.

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