BriefMe

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

Annotations already cover readOnly=false, destructive=false, and idempotent=false. The description adds real value: it is purely additive, leaves existing blocks untouched, and returns the full updated agenda so a follow-up get_agenda is unnecessary. It does not reconcile the idempotency_key parameter with idempotentHint=false.

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

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

Two tight paragraphs, front-loaded with the action and the placement semantics before the behavioral note. Slight polish issue: the duplicated word in 'after after_block_id'.

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 detailed, and the description still usefully notes the full agenda is returned. Token/auth details live in the schema. Complete for an additive write tool, with only the idempotency nuance unaddressed.

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 baseline is 3, but the description adds positional semantics for after_block_id ('insert directly after', omit for end) and clarifies the placement model beyond what the schema states. Other parameters (tokens, duration) are left to 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 ('Adds one block to an existing agenda') and enumerates the three insertion positions. This clearly separates it from siblings like update_block, reorder_blocks, and remove_block.

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 placement options (end, above a wrap-up, or after after_block_id) and explicitly notes it does not reorder or modify existing blocks, which implicitly steers agents away from reorder_blocks/update_block. It stops short of naming those alternatives directly.

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 cover safety flags; the description supplies the substantive behavior: the four return artifacts (share_token, share_url, edit_url, edit_token), what each is safe for, the linked-account vs. anonymous distinction, the 7-day expiry with no recovery, and the operational rule that opening/wrap-up/breaks must go in this first call because later edits cost a separate confirmation. That is well beyond what structured fields disclose.

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 purpose and usage, then returns, then composition guidance, then the expiry caveat. Dense but nearly every sentence carries non-redundant information; it is longer than typical, though the length is justified by 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?

For a creation tool with a mutation annotation profile, an output schema, and 100% param coverage, this description closes every gap an agent needs: what it returns, how to compose blocks, expiry risk, and the confirm-cost of subsequent edits. 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 baseline is 3, but the description adds real interpretive value: default meeting lengths by type (standup ~15, 1:1 ~30, planning 60-90), typical block count of three to eight, and a six-word title heuristic for readability on a wall-sized countdown. These are heuristics the schema cannot express.

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?

'Creates a timed meeting agenda' pairs a specific verb with a specific resource, and the elaboration of what that artifact is (shareable countdown timer, timeboxed topics in sync) makes it instantly distinguishable from siblings like add_block or update_agenda. No ambiguity about what is produced.

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 trigger list ('meeting timer, timeboxes, a run of show, workshop or standup schedule, or to keep a meeting on time') plus explicit exclusions ('Not for calendar scheduling or note-taking, and a two-item chat needs no timer'). This is the when/when-not/alternatives pattern in full.

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 flag destructive and idempotent, but the description adds concrete behavioral context beyond them: share and edit links stop working the moment it returns, nothing can be recovered, and a confirmation step exists in the delete-agenda skill. That is genuine added value over the structured hints.

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

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

Two sentences front-load the destructive scope and irreversibility, then a third routes to the sibling and the return shape. No filler, every sentence earns its place.

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

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

For a destructive mutation with full schema coverage, annotations, and an output schema, nothing an agent needs is missing. The return value is even restated (slightly redundant given the output schema) but harmless.

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 both token descriptions already explain sourcing and the linked-account exception, so the schema carries the burden. The description only loosely ties 'share and edit links' and 'linked account' concepts to the tokens without adding syntax or format detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource (deletes an agenda) plus scope (timer history, permanent). It explicitly contrasts with release_agenda, so an agent can distinguish it from that 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?

Names the alternative tool (release_agenda), describes what that alternative does (removes from a linked account, keeps share link alive), and states the precondition that this is for a user-confirmed agenda. When-to-use and when-not are both explicit.

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, non-destructive, so the safety profile is covered. The description earns credit beyond that by disclosing auth semantics: the edit_token 'authorizes on its own', a share token is required with a linked account, and a share link alone does NOT grant edit access. It stops short of return-format or pagination detail, but the token model is the behavior an agent actually needs here.

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 core purpose and the block-id rationale in the first sentence, then moves to identification/auth. The second paragraph is dense and reads a bit tightly, but every sentence carries a distinct constraint (the edit-vs-read distinction) 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?

An output schema exists, so return values need no explanation, and the description still tells the agent the payload contains block ids. Combined with when-to-use, when-not, and both identification paths, nothing needed to call 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 coverage is 100%, so the baseline is 3. The description goes further by explaining the relationship between the two tokens — either a share_token for a linked account, or an edit_token that authorizes standalone — which the per-field schema text does not fully convey on its own.

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 ('Reads back the current state of an agenda, including the id of every block') and names the sibling it is not, get_shared_agenda. An agent can distinguish it from get_shared_agenda, list_agendas, and the mutation tools 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 call it ('Needed when block ids are unknown — for example at the start of a new conversation') and when not to ('after any BriefMe mutation the current state is already in hand'), and routes edit-access reads to get_shared_agenda. When/when-not/alternative are all 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?

Beyond the readOnly/idempotent annotations it discloses that no edit access is granted, the agenda cannot be changed, and no edit token is returned. It also warns that content fields are data rather than instructions and that timer fields are a snapshot, not a live feed — behavioral context not available 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?

Three short paragraphs, front-loaded with purpose and usage, then scope limits, then return-value caveats. Each paragraph earns its place, though the return-value paragraph is denser than strictly necessary.

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, the description still names the key returned fields (content title/block titles/descriptions, timer fields, share_url) and their freshness semantics. Nothing an agent needs to call 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 coverage is 100% and the single parameter already documents "the share link, or just the token." The description repeats that same allowance without adding format, validation or error semantics, 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 (reads the public agenda behind a share link) and pins the exact scope: the same blocks, timings and timer status the link's page shows. This clearly separates it from the authenticated get_agenda sibling without needing 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?

"Use when someone has a BriefMe share link and wants to know what is on the agenda, or how far along the meeting already is" gives a clear triggering condition and second use case. It does not explicitly name get_agenda as the alternative for owned agendas, leaving that routing to inference from the share-link condition.

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 safety is covered. The description adds real value by disclosing ordering (newest first) and the important distinction that it returns share links only, not the private control link, which comes from create_agenda.

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, front-loaded with the core verb and ordering, and the parenthetical example is compact and illustrative. Slightly verbose but every sentence carries information; nothing is redundant 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?

An output schema exists so return values need not be re-explained, yet the description still highlights the key semantic (share links vs control link) and the accompanying counters. Combined with annotations covering the safety profile, an agent has everything needed to select and invoke this tool correctly.

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

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

With zero parameters there is no schema surface to compensate for, so the baseline is 4. The mention of share_token clarifies what the caller can do with the returned values, though that concern belongs more to return semantics than parameters.

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

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

The description states a specific verb (Lists) and resource (every agenda saved in the signed-in account), adds ordering (newest first), and clarifies the scope includes the share_token. It is clearly distinguishable from siblings like get_agenda or create_agenda 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?

It gives explicit triggering contexts: at the start of a conversation when the user references an earlier agenda, and after create_agenda reports the account is full. It names create_agenda but does not explicitly frame it as the complementary write path or state when NOT to use list_agendas (e.g., when the specific agenda id is already known).

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 idempotentHint=true, but the description goes well beyond them: the share link survives 7 more days before expiring, the release is irreversible, and list_agendas stops showing the agenda. These are exactly the operational consequences an agent needs before an irreversible action.

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 information (effect, lifecycle consequence, irreversibility), with the core action front-loaded. Slightly longer than strictly necessary but nothing is redundant.

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 the missing pieces — deferred expiry, finality, and disappearance from list_agendas. Nothing an agent needs to call this 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 description coverage is 100% and there is a single required parameter whose schema description already identifies it as a share_token sourced from list_agendas or create_agenda. The prose adds nothing further about the parameter, 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+resource ('takes one agenda out of the BriefMe account') and pins down the exact semantics — the agenda leaves the account and frees a slot rather than being erased. This is meaningfully different from the sibling delete_agenda, and an agent can tell the two apart from the text alone.

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 closing clause ('it fits an agenda the user has explicitly chosen to drop') gives implied usage context, but the obvious alternative, delete_agenda, is never named or contrasted. The agent must infer when to pick release over delete.

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, idempotentHint=true, and readOnlyHint=false, but the description adds substantial non-obvious behavior: remaining blocks keep their ids and order, the operation fails on the last block, and removal does not redistribute meeting time. The failure mode and the semantic effect on the agenda are exactly the kind of context annotations cannot 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?

Three short, front-loaded statements with zero filler: the core action first, then the ordering/failure constraint, then the return. Every sentence 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?

For a destructive single-block mutation with an output schema and fully documented parameters, the description covers the action, the invariants, the failure condition, and the return. Nothing an agent needs to 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 the auth token semantics (edit_token authorizing on its own, share_token needed with a linked account) are fully documented in the schema. The description adds no parameter-level detail 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 and resource ('Removes one block from an agenda') and is immediately distinguishable from siblings like add_block, update_block, and reorder_blocks. An agent can tell exactly what operation is performed without opening the schema.

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

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

The description gives a clear when-not condition ('An agenda must keep at least one block, so this fails on the last one'), which prevents a foreseeable failure. It does not, however, route the agent to alternatives such as update_block or delete_agenda, so guidance is contextual rather than complete.

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-readOnly, idempotent, non-destructive, closed-world. Beyond those, the description adds the exact-permutation contract (none missing, extra or repeated), which is real behavioral substance about failure conditions, though it does not discuss what happens on violation beyond the constraint statement.

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, followed by the constraint and the escape hatch (get_agenda). Every sentence carries distinct information and there is 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?

An output schema exists, auth parameters are fully documented in the schema, and the description supplies the ordering contract and the exclusion of other block operations. Nothing needed to invoke 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 schema description for block_ids already states "Every current block id, exactly once, in the order you want them to run," so the description largely restates it with emphasis on violation cases. edit_token and share_token are documented only in the schema and never referenced in the prose.

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 ("Puts the agenda's blocks into the order given") and immediately differentiates from siblings by excluding add/remove/edit behavior. An agent can distinguish it from add_block, remove_block and update_block without reading 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 the operation ("This only reorders: it cannot add, remove or edit a block") and routes the agent to get_agenda to obtain the prerequisite ids. Both the when-to-use and the when-not-to-use cases are covered.

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

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

Beyond the destructiveHint=true annotation, it discloses the precise blast radius (old tokens stop working the moment it returns, affecting all holders), irreversibility (cannot be restored), and a time constraint (7-day agenda expiry). This is exactly the behavioral context annotations alone cannot 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?

Front-loaded with the core action and consequence, then the return shape, then the expiry caveat. Generally tight, though the irreversibility point is stated twice ('cannot be restored' / 'cannot be recovered'), which is mild 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 no explanation, and the description still covers scope, irreversible consequence, and expiry. For a destructive rotation 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%, so both parameters are already documented, including the linked-account branching for edit_token. The description largely reinforces this rather than adding syntax or format details 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?

Specific verb+resource: it replaces an agenda's edit token and edit link with new ones, and explicitly frames the scope of the effect (every assistant, browser, bookmark). This is clearly distinguishable from siblings like update_agenda or create_agenda.

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 a clear when-to-use trigger — 'the remedy when an edit link was shared by mistake' — which is exactly the context an agent needs. It does not enumerate alternatives or exclusions, so it falls short of a full 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 supply destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds genuine scope information beyond structured fields — that blocks are untouched and that the full updated agenda is returned — though it does not restate the token/authorization requirement.

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 with zero filler, front-loading the action and immediately following with the scoping constraint that prevents sibling confusion. Every sentence earns its place.

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

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

For a single-field rename tool with 100% schema coverage and an output schema, the description covers purpose, sibling disambiguation, and scope. Nothing critical is missing, though it could have noted the destructive nature of overwriting the existing title.

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%, including detailed descriptions for title, edit_token, and share_token, so the schema carries the parameter burden. The description adds no syntax, format, or token guidance beyond what the schema already provides, making the baseline 3 correct.

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 (renames) and resource (agenda) and explicitly disambiguates from the block-editing siblings: 'Blocks are untouched — the block tools change those.' An agent can route between update_agenda and update_block/reorder_blocks purely from this text.

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 exclusion rule (use the block tools for block changes), which is the primary confusion risk among siblings. It does not address when to use this versus create_agenda or delete_agenda, but those are obvious, so the guidance is adequate without being exhaustive.

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 genuine semantics beyond the annotations: partial-update behavior ("Only the supplied fields change; anything omitted keeps its current value exactly"), so a one-field edit is safe and predictable, and it notes the return is the full updated agenda. With destructiveHint=true it would help to say explicitly that supplied fields overwrite prior values, but the idempotent/partial-update model is well conveyed.

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, front-loaded paragraphs with no filler; the scope exclusions and partial-update rule are stated early. Minor redundancy: the first and third sentences both restate "changes one block only," and the opening line largely echoes 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?

An output schema exists and annotations cover idempotency/destructiveness, so the description's job is mostly scoping and update semantics, both of which it covers. The only soft spot is the phrase "there is no whole-agenda replace," which could be read as a global claim rather than a statement about this tool's behavior.

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

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

Schema description coverage is 100%, so the baseline is 3; the description pushes above it by generalizing the omit-to-leave-unchanged contract across all optional fields, which is the key calling convention here. It does not discuss edit_token/share_token authorization, but the schema already documents those 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?

Opens with a specific verb+resource ("Changes one block, identified by block_id") and immediately scopes it against siblings: it does not reorder (reorder_blocks), add (add_block), or remove (remove_block) anything, and it is not a whole-agenda replace (update_agenda). An agent can route correctly 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 states the boundary conditions (single block, no add/remove/reorder, no whole-agenda replace) and tells the agent where to get valid block ids (get_agenda). It stops short of explicitly naming update_agenda as the tool to use when a whole-agenda edit is actually wanted, leaving that inference to the agent.

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