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

With no annotations, the description carries the burden and does well: it discloses that the operation is destructive, that it defaults to a non-destructive preview, and that the final call must follow user approval. It stops short of stating whether deletion is permanent or undoable and whether non-'done' ideas in a project scope are affected.

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, each carrying distinct information: what is deleted, the default dry-run behavior, and the required confirm flow. The safety-critical gate is front-loaded ahead of any caveats.

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 2-parameter destructive tool with no output schema, the description covers the action, scope, and safety protocol adequately. The remaining gap is what the preview actually returns (count of ideas, list of names), which matters for the show-to-user step.

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?

Scope's accepted values repeat the schema text, but the description adds real meaning for the undocumented 'confirm' parameter — it defines the preview/commit gate and the approval condition, which the schema's bare boolean 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?

States a specific verb and resource — 'Delete many ideas' — with the bulk nature ('many') explicitly distinguishing it from the sibling delete_idea. The scope values are enumerated inline, so an agent knows exactly what population the tool acts on.

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 operating procedure: call without confirm to preview, show that preview to the user, then re-call with confirm=true only after approval. This is when-to-use, when-not-to-use, and the required human-in-the-loop ordering, all in the description.

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 full burden of behavioral disclosure. It implies a mutation but says nothing about whether completion is reversible, idempotent, whether it drops associated data, or what the response contains — all material for a state-changing 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?

One short sentence, front-loaded with the verb and no padding or repetition of the name. Its brevity is efficient even if the content is thin.

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 mutation tool with no annotations, no output schema, and an undocumented parameter, the description should at least cover return behavior and reversibility. None of that is present, so an agent lacks what it needs to call this confidently.

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 single required parameter has 0% schema description coverage, so the description would need to clarify that "id" is the idea identifier and what format it takes. It says nothing about the parameter at all, leaving the only input entirely undocumented.

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

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

The description names a specific action on a specific resource ("mark an idea done"), which is a real state transition rather than a tautology. However, it does not distinguish this from close siblings such as park_idea, snooze_idea, start_idea, or update_idea, so an agent cannot tell from the text whether completion is a distinct status or just an update_idea call.

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

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

There is no guidance on when to call this versus alternatives, no preconditions (must the idea be started first?), and no exclusions. In a cluster of six status/CRUD siblings, the absence of any routing language leaves the choice 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?

With no annotations, the description carries the full burden and does disclose the key trait: deletion is permanent and irreversible, so confirmation is required. It leaves gaps on edge cases — whether a missing id errors, and whether deletion cascades to related records — but the destructive nature and safety protocol are clearly stated.

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 sentences: the action and its danger first, then the safety protocol, then the id-resolution workaround. 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 single-parameter destructive tool with no annotations and no output schema, the important agent-facing concerns (irreversibility, confirmation, id sourcing) are covered. Only error behavior and possible side effects on related data are 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 coverage is 0% and the id property has no description, so the description must compensate. It clarifies that the id must be exact and is not a title, which is genuinely useful, but it never states the id's format (UUID, slug, numeric) so an agent still cannot construct or validate one.

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 (delete), resource (idea), scope (ONE, by exact id), and consequence (permanently). The emphasis on 'ONE' implicitly distinguishes it from the bulk sibling clear_ideas without needing to name it.

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

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

Gives explicit preconditions ('Confirm with the user first'), an explicit anti-pattern ('Never guess an id from a vague title'), and routes the agent to the concrete alternative ('list ideas to find it'), which maps to the list_ideas sibling.

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 adds some behavioral context by saying the result includes full context, notes, and history, and 'Get' implies a read operation. However, it does not explicitly confirm read-only behavior, permissions, not-found handling, or 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?

A single short sentence front-loads the action and resource with no redundant or filler text.

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

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

For a simple read tool with no output schema or annotations, the description gives a useful high-level summary of returned content. It still leaves out key call details such as identifier semantics, not-found behavior, and return structure.

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 0%, and the single required parameter 'id' is not described beyond type string. The description does not clarify what the ID identifies, its expected format, or where to obtain it.

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 ('Get one idea') and adds scope with 'full context, notes and history.' It implicitly distinguishes singular retrieval from list/search siblings, but does not explicitly name alternatives or explain how it differs from update/delete 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?

There is no explicit guidance on when to use this tool versus list_ideas, search_ideas, or update_idea. It also omits prerequisites such as whether the caller must already know the idea ID.

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 full behavioral burden. It usefully discloses the return format (markdown table) and an important display constraint (do not reformat or drop dates and ids), but it omits default filtering behavior, pagination/limit behavior, and whether the operation is read-only.

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 two tight sentences with zero fluff. The core purpose is front-loaded, and the presentation instruction follows naturally.

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 five-parameter tool with no annotations, no output schema, and no schema descriptions, the description is too thin. It addresses output presentation but leaves critical context such as parameter meanings, default status behavior, and usage alternatives unexplained.

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 schema has five parameters with 0% description coverage, so the description must compensate. It does not explain to, from, limit, status, or project; 'parked ideas' only faintly hints at a status default, and 'dates and ids' refers to output, not input 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 and resource: list ideas as a markdown table. However, it says 'parked ideas' while the schema exposes a status enum covering parked, due, snoozed, done, and all, so the stated scope is narrower and potentially misleading. It also does not distinguish this tool from sibling search_ideas or get_idea.

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 no guidance on when to use list_ideas versus search_ideas, get_idea, or other siblings. It only instructs how to present the returned table, leaving tool selection and filtering conditions 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?

No annotations are provided, so the description carries the full behavioral burden. It says "park ... for later" which hints at persistence, but it never discloses what the tool returns, whether a duplicate title is rejected, or what nagEveryMinutes does (a recurring reminder is a significant side effect left entirely unexplained).

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

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

A single front-loaded sentence with no filler, leading with the core action. It is efficient but arguably too short for a six-parameter mutating tool with a nested object.

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?

Six parameters including a nested context object, no output schema, no annotations, and only 17% schema coverage demand a richer description. Key behaviors (nagging cadence, whether details/context are optional, what gets stored and returned) are undocumented, leaving an agent to guess.

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 only 17%, so the description needs to compensate but doesn't. It mentions only due, project and context in passing, and omits details (5000-char body), nagEveryMinutes, and the structure of the context object (repo, files, branch, source, summary). The one useful clarification, "natural language ok" for due, repeats what the schema already says.

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

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

The description gives a specific verb and resource ("park an idea for later") and names the differentiating elements (due date, project, context). It implicitly contrasts with siblings like get_idea/complete_idea by describing a capture-and-defer action, though it never names an alternative.

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

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

Usage is only implied: "for later" suggests capturing ideas not currently being worked on, and the sibling set (start_idea, complete_idea) makes the intent inferable. There is no explicit statement of when to choose this tool over start_idea or update_idea, and no prerequisites are mentioned.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that results are returned as a markdown table and should be shown as returned, but it omits match semantics, ranking, case sensitivity, pagination behavior, and whether the operation is read-only.

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 definition is two tight sentences with no wasted language. The core search behavior is front-loaded and the output-handling instruction follows immediately.

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 tool with no annotations, no output schema, and no schema parameter descriptions, the description is not complete enough. It covers the basic purpose and output format, but leaves status and limit unexplained and does not describe matching behavior or result constraints.

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 0%, so the description must compensate for three undocumented parameters. It adds useful meaning for the required query parameter by naming the fields searched, but gives no explanation of the limit parameter or the status enum.

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: search ideas by text across title, details, project, and notes. It distinguishes this from list_ideas in practice through the search framing, though it does not explicitly name the sibling.

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 implies using this tool for text search, but provides no explicit guidance on when to use it instead of list_ideas or get_idea. There are no exclusions, prerequisites, or alternative-routing instructions.

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?

No annotations are provided, so the description carries the full behavioral burden. 'Move ... later' implies mutation, but there is no disclosure of what happens when both `until` and `minutes` are supplied, whether the change is reversible, what permissions are needed, or what the call returns.

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

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

Two short sentences with the core action front-loaded and no filler. Slightly too terse given the unresolved ambiguity around the two time parameters.

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

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

A mutation tool with zero annotations, no output schema, 0% parameter documentation, and confusable siblings. The description does not supply enough to call it correctly in edge cases (both time params given, missing due date) or to pick it over park_idea.

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 0%, so the description must compensate; it does partially by naming `until` (date text) and `minutes` and implying a choice via 'or'. However, it leaves the `id` parameter and the accepted date-text format unspecified, and never resolves precedence or mutual exclusivity between the two timing params.

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: moving an idea's due date later. Clear on its own, but it never distinguishes itself from sibling park_idea (plausibly a similar deferral action) or update_idea, which could also alter a due date.

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 second sentence is parameter usage, not tool-selection guidance. There is no statement of when to snooze versus park_idea or update_idea, nor any precondition such as the idea needing an existing due date.

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 full disclosure burden, and it leaves the most important trait unresolved: whether calling start_idea merely reads data or also transitions the idea into an 'in progress' state (the name and the park/complete/snooze siblings strongly suggest a mutation). It also says nothing about permissions, side effects, or what happens if the idea is already started; only the shape of the returned brief is hinted at.

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

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

A single front-loaded sentence with no filler; the action comes first and the purpose follows. It is efficient, though the terseness is arguably part of the definition's incompleteness rather than a virtue in itself.

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?

Given zero annotations, no output schema, and an undocumented parameter, the description does not supply enough for confident invocation: the read-vs-mutate question, the get_idea overlap, and the id's provenance all go unanswered. It describes the payload but not the consequences of the call.

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?

There is a single required parameter whose schema has 0% description coverage, so the definition must compensate and does not. The description implies the id identifies the idea, but gives no format, source (where to get an id), or error behavior for invalid ids, leaving the agent to infer everything about the one parameter it must supply.

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

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

The verb 'Load' and the resource ('an idea's details, context and notes as a brief') are specific, and 'so you can start work on it' names the end goal. However, it never distinguishes itself from sibling get_idea, which plausibly loads the same idea details, leaving the agent to guess which one to call.

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 trailing clause 'so you can start work on it' implies a usage context (beginning work on an idea), which is better than nothing. But there is no explicit when-to-use/when-not and no reference to the obvious alternative get_idea or to the lifecycle siblings (park_idea, complete_idea, snooze_idea) that would clarify the intended moment to call this.

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 full burden, and it does disclose the two most important traits: it is a partial update ('Only the fields given change') and note is appended rather than replacing. It says nothing about permissions, behavior on an unknown id, reversibility, or side effects, leaving meaningful gaps for a mutation tool.

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

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

A single front-loaded sentence plus one short clarifying clause. Nothing is redundant, and the most load-bearing fact (only given fields change) is placed last for emphasis without padding.

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

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

For a 6-parameter mutation tool with no annotations and no output schema, the definition covers the core semantics but omits error behavior, permission requirements, and whether the updated idea is returned. Adequate to call correctly for the common case, incomplete for 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?

Schema description coverage is 33%: only due and note are documented, and the schema already covers both. The description maps human terms ('due date') to parameters and adds the partial-update rule, but gives no formats or limits for title, details, or project, so it only partially compensates for the coverage gap.

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 (Edit) and resource (idea) and enumerates the mutable fields, so an agent can tell it apart from status-oriented siblings like park_idea, complete_idea, and snooze_idea. It stops short of naming those siblings explicitly, so the differentiation is inferential rather than stated.

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

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

Usage is only implied: by listing title/details/project/due/note, it implies status transitions belong to other tools. There is no explicit 'use this when X, use delete_idea when Y' routing, and no prerequisites such as needing an existing id.

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