BriefMe

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

With no annotations, the description carries the behavioral burden. It discloses that the operation appends or inserts, does not mutate existing blocks, and returns the full updated agenda. It does not cover failure behavior or invalid after_block_id, but the core side-effect profile is clear.

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

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

The description is compact and front-loaded with the primary action. Every sentence adds useful information: placement behavior, the no-reorder guarantee, and the return value. No filler or redundant restatement of the tool name.

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

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

For a 6-parameter mutation tool with no annotations and no output schema, the description covers the essential operational context: what is added, where it goes, what is not changed, and what is returned. It could mention error cases like an invalid after_block_id, but the parameter schema already documents the inputs thoroughly.

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 reinforces after_block_id behavior but does not add meaning beyond what the schema already provides for title, block_type, edit_token, description, or duration_seconds.

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 ('Adds one block') and resource ('an existing agenda'), then clarifies the two placement modes: append to the end or insert after after_block_id. It also distinguishes this tool from reorder/update siblings by stating it does not reorder or change existing blocks.

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 clear when-to-use context: adding a new block, with explicit append vs insertion behavior. It also states a when-not boundary ('does not reorder or change any existing block') and tells the agent not to call get_agenda afterwards. However, it does not explicitly name the alternative sibling tools for reordering or updating.

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 are empty, so the description carries the full burden, and it delivers substantially: security-critical behavior (edit_url is the only control page and must never be posted shared), output semantics (share_url is read-only and safe for invites), lifecycle behavior (agendas expire after 7 days and cannot be recovered), and disclosure rules (block_type must never be mentioned to the user). This covers side effects, safety, and persistence far beyond what an annotation could 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?

The description is long and dense, but nearly every sentence earns its place given the tool's complexity: security-sensitive outputs, nested block construction rules, and expiry behavior all need coverage. It is front-loaded with the core purpose and critical link-handling instructions before the construction rules. The break-threshold rules are heavy with numbers and could be slightly better organized, but nothing is 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?

With no output schema and no annotations, the description must explain return values and behavioral safety itself — and it does: edit_url, share_url, and edit_token semantics are each clarified, security constraints are stated, expiry is disclosed, and the full block-construction rules are given. An agent has everything needed to call this tool correctly and handle its outputs appropriately. The only minor omission is behavior when an agenda already exists, which is not critical for a create tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning well beyond the schema: titles must be six words or fewer and scannable on a countdown screen, block durations must sum to the requested meeting length (with inference rules for standups, 1:1s, sprint planning), and the structure rules specify when to use opening/closing/break block types and their duration proportions. These are operational semantics the schema does not convey.

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 opening sentence 'Creates a timed meeting agenda and returns the links that run it' states a specific verb, resource, and distinctive outcome (the runnable links). This clearly separates it from siblings like add_block, update_block, and get_agenda, which operate on an existing agenda rather than creating a new one.

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

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

The description provides extensive context on how the tool should be used — duration aggregation rules, break thresholds, opening/closing block structure, and title constraints — which is effectively guidance for constructing the blocks parameter. The creation semantics are clear enough that an agent can infer this is the 'first creation' tool versus sibling mutators, but it never explicitly names alternatives or states when not to use it.

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 readOnlyHint annotation, the description discloses a key authentication constraint: 'Requires edit_token — a share link or share URL cannot be used here.' It also describes the return content ('including the id of every block') and explains the state semantics around mutations. This goes well beyond the annotation and gives the agent actionable behavioral context.

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

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

The description is compact, front-loaded with the core purpose, and organized into three clear paragraphs: function, usage, and constraints. Every sentence earns its place; there is no filler or repetition.

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

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

For a single-parameter read tool with readOnlyHint and no output schema, this description covers all necessary ground: what it does, when to use it, when to avoid it, token requirements, and the alternative when requirements are not met. An agent has enough information to invoke it correctly and handle user edge cases.

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

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

The input schema already fully documents edit_token as 'The edit_token returned by create_agenda.' The description adds significant semantic detail by clarifying that share links are not acceptable and specifying the appropriate user response. While baseline for 100% schema coverage is 3, the extra token-type distinction justifies a 4.

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

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

The description opens with a specific verb and resource: 'Reads back the current state of an agenda.' It further clarifies that the tool returns 'the id of every block,' distinguishing it from the mutation siblings (add_block, remove_block, etc.). This makes the tool's function unmistakable.

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

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

The description explicitly states when to use the tool ('Use this when you need block ids you do not already have') and when not to ('After any BriefMe mutation you already hold current state, so you do not need to call this again'). It also provides an alternative path for the share-link case: 'offer to create a new one instead.' This is exemplary usage 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?

Beyond the destructiveHint annotation, the description discloses several behavioral traits: remaining blocks keep ids and order, removal fails on the last block, the meeting shortens without time redistribution, and the updated agenda is returned. This is rich, non-obvious context that helps the agent anticipate side effects.

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

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

The description is compact and front-loaded with the primary action, then adds constraints, side effects, and return value in short sentences. Every sentence contributes meaningful information; 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?

For a destructive mutation with two documented parameters and no output schema, the description answers the essential questions: what it does, when it fails, what changes, and what is returned. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema already fully documents both block_id and edit_token with clear descriptions, so the description adds no parameter-level detail. With 100% schema description coverage, the baseline of 3 applies.

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

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

States a specific operation ('Removes one block from an agenda') with a clear resource and scope, distinguishing it from siblings like add_block, reorder_blocks, and update_block. Additional effects (ids/order preserved, failure on final block) further clarify what the tool does.

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 makes the removal context obvious and gives a clear constraint (cannot remove the last block), but it does not explicitly say when to prefer this tool over alternatives or mention any exclusions. Usage guidance is implied rather than stated as a routing rule.

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

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

With empty annotations, the description carries the full behavioral burden. It clearly states the strict block_ids constraint (every current id exactly once, none missing/extra/repeated), the non-mutating nature of the operation, and the return value ("Returns the full updated agenda"). This gives the agent a complete picture of side effects and requirements.

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

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

The description is tightly structured: a one-sentence core purpose, a focused paragraph on block_ids constraints and non-mutation, and a final note about get_agenda plus the return value. Every sentence earns its place and the most important information is front-loaded.

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

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

For a moderate-complexity tool with no output schema, the description covers all necessary context: what the tool does, exact input requirements, how to obtain current ids, what it cannot do, and what it returns. The edit_token requirement is already documented in the schema, so nothing critical 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 adds meaningful value beyond the schema by expanding block_ids semantics into explicit constraints: "none missing, none extra, none repeated," reinforcing the schema's "exactly once" wording. It also clarifies that no editing is possible, which supplements the parameter meaning.

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

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

The description opens with a specific verb and resource: "Puts the agenda's blocks into the order you give." It explicitly differentiates this from sibling tools by stating what it cannot do — "cannot add, remove or edit a block" — making reorder_blocks distinct from add_block, remove_block, and update_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?

The description gives clear usage context: reorder existing agenda blocks by providing a complete ordered id list. It also provides a precondition — "If you are unsure of the current ids, call get_agenda first" — and implicitly routes add/remove/edit operations to sibling tools through the "only reorders" limitation.

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 no annotations, the description carries the burden. It discloses a key behavioral trait (does not affect blocks) and the return value (full updated agenda). It omits auth or failure details, but for a simple rename these are minor.

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

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

Two sentences with no filler. The main action is front-loaded, and the side-effect clarification and return behavior are each given one concise sentence.

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 rename tool with no output schema, the description covers purpose, scope, side effects, return value, and how it differs from block tools. 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 schema already documents both parameters. The description adds no new parameter-level meaning beyond the schema, landing at the baseline.

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

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

The description uses a specific verb and resource ('Changes the agenda's title') and explicitly distances itself from block operations, distinguishing it from the sibling block tools. The return-value note also clarifies what the tool accomplishes.

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

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

It explicitly says 'Does not touch any block — use the block tools for those,' giving clear exclusions and routing to alternative sibling tools. This tells an agent when not to use this tool, which is strong 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?

With empty annotations, the description carries the full burden and does well: it discloses partial-update behavior ('anything you leave out keeps its current value exactly'), scope limitation, and return behavior ('Returns the full updated agenda'). It does not address failure modes or token staleness, which keeps it just below a perfect score.

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 behavior and organized into useful short paragraphs: semantics, exclusions, prerequisite, and return value. Some redundancy exists ('Changes one block only' restates the opening, and 'Do not re-send fields' repeats the supply-only-changed-fields idea), but it remains economical.

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 six-parameter mutation tool with no annotations and no output schema, the description provides the essential context: partial updates, single-block scope, prerequisite id retrieval, and the return value. It omits error/validation behavior and does not describe the shape of the returned agenda, but enough is present for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the input schema already documents every parameter. The description reinforces the 'omit to leave unchanged' convention that appears in the schema but adds little new parametric meaning beyond the conceptual partial-update model already implied by the property descriptions.

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

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

The description states a specific verb and resource ('Changes one block, identified by block_id') and explicitly narrows scope to a single block. It also differentiates from sibling tools by stating what it does not do: 'does not reorder, add or remove anything.'

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 clear when-to-use guidance: change a single block by supplying only changed fields. It gives explicit when-not-to-use guidance ('do not re-send fields you are not changing', 'do not rewrite the whole agenda') and a concrete prerequisite: 'If you do not have current block ids, call get_agenda first.'

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