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

Annotations only declare the mutation profile (readOnly=false, idempotent=false, destructive=false); the description adds real operational context beyond that: the approval workflow ('Waiting for approval in Sara' and no change until Allow), the off-state response, and the availability gate. It also discloses the return string format and that the #id works with read_note/update_note/delete_note.

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 in the first sentence, then alternatives, then return value, then gating — a logical progression with nothing clearly redundant. The final sentences are long and multi-clause, but each clause carries distinct behavioral information about approval modes.

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?

Covers everything an agent needs for a non-idempotent creation tool with no output schema: side effects, return strings, ID reuse across sibling tools, availability precondition, and the three approval outcomes. Little is left to inference.

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 title, body, and project are already fully documented, including the 20,000/200/80 character limits and the create-if-missing project behavior. The description only restates 'title and free text, Markdown welcome' and that project is optional, adding no format or semantic 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?

States a specific verb and resource ('Save a new note ... in the owner's planner in Sara, optionally in a project') and immediately distinguishes itself from update_note and remember_fact. An agent can pick this over its siblings without inspecting 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 routes the agent: use update_note to change an existing note and remember_fact for a single fact. It also states the availability precondition ('Only listed when the owner turns on "Let other apps change things"') and the approval-mode behavior, which tells the agent exactly what to expect in each mode.

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 give a safety profile (readOnlyHint=false, destructiveHint=false); the description adds substantial behavioral detail beyond that: the exact return string and its embedded #id, the approval flow ('Waiting for approval in Sara'), the off-state response, and the 9:00 default for hourless due times. This is exactly the context annotations cannot carry.

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?

Purpose and the primary alternative are front-loaded, and each sentence carries real information (ID usage, due-time default, approval modes). It is dense but slightly long with several semicolon-packed clauses, keeping it just below maximally crisp.

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 mutating tool gated by owner approval with no output schema, the description covers everything an agent needs: what it returns, how the ID is used downstream, the approval-gated outcomes, and the due-time interpretation. Nothing material 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 the schema already documents all four parameters and their formats. The description still adds value by clarifying that a due time without an hour means 9:00 in the owner's time zone, which the schema does not state. It stops short of explaining every parameter, hence 4 rather than 5.

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 new to-do to the owner's planner in Sara') plus the optional fields it supports. It explicitly distinguishes itself from update_task, so an agent can tell the create path from the edit path without opening 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?

Names the alternative ('Use update_task to change an existing one') and the condition that selects it. It also spells out the availability gate ('Only listed when the owner turns on...') and the approval-mode behavior, giving the agent concrete when-to-use context.

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 declare non-read-only, non-idempotent, non-destructive, but the description adds what annotations cannot: the conversation is persisted and owner-readable ('which the owner can read in Sara'), the reply is plain text, an AI notice appears on new sessions, an approval-pending note is returned, and calls can take minutes with up to two concurrent replies per key. The only gap is that 'her own tools are allowed for other apps' sits slightly against openWorldHint=false, though it describes a returned note rather than direct external interaction, so it is not a hard 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?

Purpose is front-loaded in the first clause, followed by routing, then behavioral caveats. It is dense but nearly every clause carries decision-relevant information; the approval-flow sentence is slightly convoluted but still 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 no output schema, the description still explains the return value (plain text reply, AI notice, approval-pending note) and sets latency/concurrency expectations. For a one-parameter conversational tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter already carries a description, examples, and length bounds, so the baseline is 3. The description only adds 'in plain words', which does not meaningfully extend 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?

States a specific verb and resource ('Send Sara a message and get her reply, as in a chat') and immediately differentiates from siblings by naming remember_fact and the to-do/note tools. An agent can tell it is the free-form conversational entry point 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?

Explicit routing: use for 'questions, opinions or anything conversational', use remember_fact to deliberately store a fact, use the to-do/note tools to change the planner. This gives both when-to-use and named alternatives, 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=false, idempotentHint=true and destructiveHint=false. The description adds genuine context beyond them: the exact success string, that re-completing a done item is a no-op, and the three-state approval flow with its return strings (allowed / "Waiting for approval in Sara" / off). The only shortfall is that the idempotent no-op restates the annotation rather than extending it.

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

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

Front-loaded with the core action, then alternatives, then return value, then permission gating — a sensible ordering. The approval-gating sentence is long and packs three branches into one line, which costs a little readability but each clause carries distinct information.

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 supplies the exact return string, plus the approval and disabled-state responses an agent must be able to recognize. Idempotency, error behavior, and permission prerequisites are all covered, so 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 the single id parameter already documents its provenance and the unknown-id error, so the baseline of 3 applies. The description reinforces the id source but adds no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ("Mark one of the owner's to-dos in Sara as done, by its id") and implicitly scopes it against delete_task and update_task by naming update_task as the reopen path. An agent can distinguish it from every sibling 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 says where ids come from (list_tasks or get_today) and names the alternative for the inverse operation (update_task with status "open"). It also states the precondition that the tool is only listed when the owner enables "Let other apps change things", which is real when-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?

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds substantial context beyond them: irreversibility, the exact success string returned, the approval handshake ('Waiting for approval in Sara') and the fact that nothing changes until the owner presses Allow, plus the disabled-tool response. That is precisely the kind of workflow/auth behavior annotations cannot express.

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 action and irreversibility, and every sentence carries information an agent needs. The final sentence is a long run-on that chains the approval flow and the disabled-tool case together, which slightly hurts readability.

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

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

For a single-parameter destructive tool with no output schema, the description covers availability gating, irreversibility, return strings and the approval lifecycle. Nothing an agent needs to invoke it safely 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 the id property already documents the '#12' format and the refusal behavior for unknown ids. The description's 'by its id (from list_notes)' restates that pointer without adding format or validation 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 and resource ('Delete one of the owner's notes from Sara's planner') and scopes it by id, pointing at list_notes as the source of that id. An agent can distinguish it from update_note/add_note/read_note purely from the description.

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?

Explains the gating condition under which the tool is even visible (owner must enable 'Let other apps change things') and the approval requirement, which tells the agent when a call will actually take effect. It does not, however, name alternatives such as update_note for non-destructive edits, so it stops short of explicit when-not guidance.

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

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

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses irreversibility, the exact success string, the mandatory owner-approval gate and its 'Waiting for approval in Sara' response, and the 'turned off' outcome. This is precisely the operational context an agent needs before attempting a destructive call.

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 action and a one-line sibling contrast; every sentence carries usable information. It is dense — the availability and approval clauses are stacked in long sentences — but nothing is truly wasted.

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 destructive tool with no output schema, it covers return values, irreversibility, approval gating, error path (via schema), and availability conditions. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the schema already explains that id is 'the number after # in list_tasks or get_today's results', so the description's mention of the id source is largely redundant. Nothing is added about the integer constraint or the refusal-on-unknown-id behavior beyond what the schema states.

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 ('Delete one of the owner's to-dos from Sara's planner ... by its id') and immediately distinguishes itself from the nearest sibling by contrasting deletion with complete_task's ticking-off. An agent can tell exactly what this does without inspecting the schema.

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

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

Explicitly names the alternative ('to tick a to-do off instead, use complete_task') and the id source ('from list_tasks or get_today'). It also states the availability precondition (the owner must enable 'Let other apps change things'), which is real when-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?

Annotations already declare readOnlyHint/idempotentHint, so the safety profile is covered; the description still adds real behavioral value by disclosing the aggregation window (next 24 hours for reminders, 'coming up' for dates), the conditional inclusion of calendar events ('when a calendar is connected'), and the fact that it takes no input. That is substantive context beyond 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?

Front-loaded with what the tool does, then usage routing, then return shape — a sensible order with no filler. The return-format sentence is dense (section names plus a sample bullet template) but it earns its place given there is no output schema; slightly verbose for a no-parameter tool.

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

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

There is no output schema, and the description compensates by describing the plain-text return: the date line, the exact section headers, and the '- #id title (due …)' bullet format. Combined with the usage routing and read-only disclosure, an agent has everything needed to call it and parse the result.

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

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

With zero parameters the baseline is 4, and the description supports it by stating explicitly that the tool 'takes no input', removing any ambiguity about whether a date or filter could be passed. There is nothing further to document.

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 ('Get the owner's agenda for today in one view') and enumerates exactly what is aggregated: to-dos due/overdue, high-priority undated, reminders in 24h, calendar events, upcoming dates. It also explicitly distinguishes itself from list_tasks, so an agent can separate the two without opening 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 an explicit selection rule: 'Use it for "what's on today"; use list_tasks for the whole to-do list with filters.' It also names the downstream tools that consume the returned #ids (complete_task, update_task, delete_task), which tells the agent how this tool fits into a workflow rather than standing alone.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses the privacy boundary (facts from other people's chats and private conversations are excluded), the sort order, and the exact return shape including the empty-state string. No output schema exists, so describing the line format is real added value rather than repetition.

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 doing distinct work: what it returns, when to use it vs alternatives, then the output contract and privacy note. Front-loaded with scope and no filler.

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

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

For a one-parameter read tool, everything an agent needs is present: scope, ordering, alternatives, exclusions, and return format. No output schema is required because the description specifies the line format and empty case.

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?

Single optional limit parameter with 100% schema description coverage including default, min and max, so the schema carries the burden. The description adds nothing about the limit or sensible values, which is the baseline 3 case.

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?

Names a specific verb and resource plus the exact content domain (name, people, likes, habits, work) and ordering (newest first), which lets an agent distinguish it from list_notes and search_memory without opening the schema.

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

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

Explicitly routes usage: use this for a general picture, search_memory for something specific, remember_fact to add. Both the use case and the alternatives are named with the condition that selects them.

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?

Despite readOnlyHint already being present, it adds real behavioral context: exact return shape ('- #id title [project] (updated YYYY-MM-DD)' or 'No notes.'), a 100-line cap, and ordering (newest first). That is the kind of output-shape disclosure an agent needs before calling.

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 purpose, then workflow, then return format — efficient and well-ordered. The trailing 'Read-only.' slightly duplicates the readOnlyHint annotation, a minor 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?

Single optional parameter, no output schema, and the description covers purpose, workflow, return format, and limits. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the query parameter already documents 'only notes containing these words (title or text)' with examples. The description's 'or the ones matching some words' restates the schema rather than adding syntax, limits, or matching rules, 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 and resource ('List the notes in the owner's planner'), plus scope details (titles only, newest first, optional word matching) that separate it from read_note and search 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?

Explicitly routes the agent: use it to find a note's id, then read_note, update_note, or delete_note. The primary workflow and the downstream alternatives are named rather than inferred.

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 the description adds value beyond them: the exact plain-text return format per line, the empty-state string 'No conversations yet.', and hard scope exclusions (no other people's chats, private, archived, or imported conversations). That is exactly the context an agent needs to interpret results correctly.

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, then return shape, then scope caveats — a sensible order with no filler sentences. Slightly verbose: 'Read-only' repeats the annotation and the exclusion list is long, but both carry real signal.

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 specifying the exact line format and empty case. With one optional parameter and full annotation coverage, nothing an agent needs to call or interpret this tool 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 the single 'limit' parameter is fully documented with default, range, and examples in the schema. The description adds no additional semantics about limit, 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 and resource ('List the owner's most recent conversations with Sara'), plus ordering ('newest first') and per-item fields (title, last active, summary). It is clearly distinguishable from search_memory, which it names 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?

Gives an explicit use case ('see what the owner has been talking about lately') and an explicit alternative with its own condition ('use search_memory to look for a topic across all of her memory'). The routing decision is fully determined.

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 safety (readOnly, idempotent, non-destructive), yet the description adds substance they don't: plain-text return, a 100-line cap, ordering rules (open first, by priority then due date), the exact line format including the [x]/[ ] marker, the empty-result string "Nothing open." This is a tool with no output schema, and the description compensates for it.

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

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

Purpose and the sibling comparison are front-loaded, and the quoted line format is dense but useful. The format/order sentence is long and packs several facts into one clause chain, which costs a little readability but every element 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 only 2 optional params, no output schema, and a simple read, the description covers everything an agent needs: what it returns, how it's ordered, the size limit, the empty case, and how the output id feeds the mutation siblings. 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?

Schema description coverage is 100%, so the enum values and project filter are already documented, and the baseline is 3. The description paraphrases the filters as "optionally only open or done ones, or one project" but omits the third enum value "all", adding no real semantics beyond the schema.

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

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

Specific verb + resource ("List the to-dos in the owner's planner in Sara") with scope qualifiers (open/done, one project). It explicitly distinguishes itself from the sibling get_today, so an agent can separate the two without opening either 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?

States two concrete use cases (see the whole list, find a to-do's id) and names the alternative tool plus the condition that selects it ("use get_today for just what's due today"). It also tells the agent the id is the key consumed by complete_task/update_task/delete_task, which links it into a workflow.

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

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

Goes beyond the annotations by specifying the exact return shape ('# Title', blank line, then text) and the unknown-id error behavior, and confirms read-only. The 'Read-only' sentence and the unknown-id error both duplicate what the annotations and schema already declare, so it adds less new context than a fully independent disclosure would.

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 short sentences, front-loaded with the purpose and followed by the workflow hint, return shape, and error case. Minor waste: 'Read-only' and the unknown-id error restate annotation/schema content.

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 takes on the burden of explaining the return value and does so concretely (Markdown with title heading). A one-parameter read tool needs nothing further for an agent 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% and the single id parameter is fully documented there, including how to derive it from list_notes output and the minimum of 1. The description's 'by its id' adds no meaning beyond the schema, 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 and resource ('Read one note ... in full, by its id') and scopes the data source ('the owner's planner in Sara'), which distinguishes it from sibling readers like list_notes and search_library. An agent can tell exactly what it retrieves without opening the schema.

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

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

Gives an explicit prerequisite workflow: 'Use list_notes first to find the id,' naming the sibling that produces the required input. It also names the failure condition (unknown id returns an error), so the agent knows when the call will not succeed.

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?

With annotations only saying readOnlyHint=false and non-destructive, the description supplies the behavior that matters: it is a two-phase operation that always asks first, returns 'Waiting for approval in Sara' and stores nothing until Allow, and returns 'Remembered (#id): fact' once permitted. That approval gate and attribution behavior cannot be derived from the annotations or schema.

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

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

Front-loaded with the core action, then alternatives, then return values and preconditions in a logical order with zero filler. It is dense—long compound sentences and quoted literals—but every clause carries information an agent needs to call it correctly.

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?

No output schema exists, and the description compensates by documenting both return strings (approval-pending and success with id). Combined with the availability precondition and the fact that failure to approve means nothing is stored, an agent has everything needed to invoke it and interpret the result.

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

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

Schema coverage is 100% and the 'fact' parameter already documents the 1-400 character sentence constraint with examples. The description only restates 'one fact about the owner' and does not add format or granularity guidance beyond the schema, 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 (remember/store) and resource (one fact about the owner in Sara's long-term memory), plus the 'marked as told by this app' attribution. It explicitly names what it is not (ask_sara is for conversation, add_note is for longer text), so an agent can pick it out of a 17-tool sibling set immediately.

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 positive guidance ('use it to store something on purpose'), names two alternatives with the exact conditions that select them (ask_sara for conversation, add_note for longer text), and states the availability precondition (owner must enable 'Let other apps change things'). 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 the read-only, idempotent, closed-world profile, and the description adds behavior beyond that: the result cap (6 passages), per-passage length (1,400 chars), the '[document title, place]' header format, the explicit 'nothing found' line, and the chat-only-document exclusion. These are exactly the facts an agent needs to interpret results correctly.

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 dense sentences with no filler, front-loaded with what the tool searches before routing to the alternative. The parenthetical file-type list and nested parentheticals in the last two sentences add bulk, though each still carries useful routing or result-shape information.

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 one-parameter retrieval tool with no output schema, the description fully covers what would otherwise be missing: result count, result size, result formatting, the empty-result signal, and coverage exclusions. Nothing an agent needs in order to call it and read its output correctly is absent.

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

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

Schema coverage is 100% with a single, well-exampled 'query' parameter, so the schema does most of the work. The description adds one useful semantic point beyond the schema — matching happens on both words and meaning — which tells the agent that natural-language questions (not just keywords) are valid queries.

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 (search) and resource (the owner's documents in Sara's library), enumerates the document types covered, and notes it works 'by words and meaning' (hybrid keyword + semantic). It is immediately distinguishable from search_memory, which covers conversational memory rather than documents.

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 names the selection rule: use this for questions answered by the owner's documents, use search_memory for what Sara remembers from conversations. It also states a scoping exclusion (documents shared in a single chat only are left out), which prevents false-negative interpretations.

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 cover safety (readOnlyHint, idempotent, non-destructive), but the description adds substantial behavior: exact return format ('- [kind, YYYY-MM-DD] text'), ordering (best match first), the empty-result sentinel line, and content exclusions (other people's chats, private conversations, explicit content while Adult mode is off). These are things the annotations cannot express.

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

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

Four sentences, all load-bearing, with the core purpose front-loaded and alternatives and return format following in logical order. No filler or restatement of the name/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?

With no output schema, the description still specifies the return format, ordering and empty-result case, and it discloses privacy boundaries. An agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra credit by clarifying the query is matched 'by words and meaning' (keyword plus semantic), which the schema's examples alone do not convey. It does not discuss the limit parameter, but the schema documents that fully.

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 (search) plus resource scope ('Sara's long-term memory about the owner') and enumerates the content kinds (facts, summaries, decisions, promises, dates). It also names the sibling tools it is not (list_facts, search_library, list_recent_conversations), so an agent can distinguish it 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 says when to use it ('for context about the owner's life, preferences and projects') and routes the caller to the right alternative for each other need (browse all facts → list_facts, documents → search_library, recent chatter → list_recent_conversations). Both positive and exclusionary guidance are present.

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

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

Goes well beyond the annotations: it discloses whole-text replacement of body, the exact success string 'Changed note #id: title', conditional exposure gated on an owner setting, and an approval mode that returns 'Waiting for approval in Sara' with no change applied. The annotations already flag destructive/idempotent, and the description adds the operational gates and side-effect timing an agent needs before mutating.

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 mutation target and scope, followed by return value and then the availability/approval caveats in decreasing priority. Every sentence carries information, though the three-mode approval sentence is dense and could be tightened without losing signal.

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, gated mutation with no output schema, the description supplies the return string, the no-op approval path, the off-state behavior, and the partial-update semantics. Nothing an agent needs to call it safely and interpret the result 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 length limits, id validation, and the empty-string project removal are already documented in the schema. The description only restates that body is replaced as a whole and enumerates the three optional fields; it adds no format or edge-case detail beyond the structured fields. Baseline 3 applies when the schema does the heavy lifting.

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 ('Change one of the owner's notes in Sara by its id') plus the mutable scope (title, text, project), which cleanly separates it from read_note, add_note, and delete_note. The id provenance from list_notes is named, so an agent can identify both the tool and its key input without opening the schema.

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

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

Explicitly routes to a sibling ('Read the note with read_note first if you mean to edit part of the text') and names list_notes as the source of ids. It also states the partial-update contract ('Only the fields you give change'), which is the decisive usage fact for an agent deciding between this and full-replacement behavior.

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?

Adds context that annotations cannot convey: partial-update semantics ('Only the fields you give change'), the approval gate with its exact 'Waiting for approval in Sara' response and the guarantee that nothing changes until Allow, and the disabled-tool response. This is far richer than the readOnly/idempotent/destructive hints and is consistent with them.

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 action and field list, then the alternative, return values, and gating. It is dense with sentences chained by semicolons and parentheses, but nearly every clause carries information an agent needs for a gated mutation tool.

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

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

With no output schema, the description carries the return contract — 'Changed to-do #id: title' with the new due time, the approval-waiting string, and the turned-off string. Combined with the schema's error note for unknown ids, an agent knows the full call and response picture.

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 still contributes the cross-cutting partial-update contract that applies to all seven parameters and cannot be inferred from any single field. It does not restate formats already in the schema, which 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?

Names a specific verb and resource ('Change one of the owner's to-dos in Sara by its id') and enumerates the mutable fields. It also identifies its source of ids (list_tasks or get_today), which makes it instantly distinguishable from add_task, delete_task and complete_task.

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 routes the simple case away ('Use complete_task to simply tick one off'), and states the availability prerequisite (the owner must enable 'Let other apps change things'). It does not contrast with delete_task or update_note, but the primary overlap is handled.

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