Hamloy

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

Annotations already declare this is a non-read-only, non-destructive, non-idempotent write. The description adds useful behavioral context: the item stays open, should be claimed only when work starts now, and should be ticked only when the work itself is done, not for adding 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?

Two sentences, front-loaded with the core action and followed by a compact lifecycle rule. Every sentence earns its place with 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 12-parameter creation tool with nested fields and no output schema, the description covers purpose and lifecycle well, while the rich schema handles parameter detail. It could say more about what is returned, but the essential invocation context is present.

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 all 12 parameters are already documented in the schema. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource set: add a task, a request for the human, or a question for the human. It clearly distinguishes the three item kinds, though it does not explicitly name sibling tools like edit or import as alternatives.

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 lifecycle guidance about claiming and ticking, but that guidance is about post-add behavior rather than when to choose add over siblings such as edit or import. Usage is implied by the item kinds, with no explicit when-not or alternative routing.

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 this is a non-read-only, non-destructive, non-idempotent, closed-world mutation. The description adds the important behavioral constraint that the answer must come from the human, not be invented, but it does not explain overwrite/retry behavior or what exactly gets stored beyond the 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?

The description is two short sentences, front-loads the core action, and spends its remaining words on the most important misuse guardrails. 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 simple four-parameter recording tool with mutation annotations and 75% schema coverage, the description provides enough context to invoke it correctly. It could say more about the key parameter or overwrite semantics, but nothing critical is missing for normal use.

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 75%, so the schema carries most parameter meaning. The description only broadly clarifies that the recorded value is the human's answer and does not add field-level detail, especially for the undocumented key parameter.

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: record the answer the human gave you in chat. It also explicitly distinguishes this from the sibling tools assume and edit, so an agent can identify the correct tool 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?

It gives explicit when-to-use guidance (when the human gave an answer in chat) and explicit when-not-to-use cases with named alternatives: use assume when not given an answer, and use edit's needs when trying to unblock work.

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 real behavior beyond annotations: the question stays open and is marked assumed, held tasks block on it, and an overturn reopens those tasks. That task-lifecycle consequence is exactly the sort of context annotations cannot convey. It stops short of stating permissions or whether the assumption can be withdrawn by the agent itself, keeping it at 4 rather than 5.

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

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

Two tight sentences, front-loaded with the motivating condition, then the state consequence. The semicolon-clause structure is dense but every clause carries information about the question's lifecycle.

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, so the description must carry the result semantics – and it does: assumed state, open question, held tasks waiting, overturn reopens. For a four-parameter tool, that is sufficient for an agent to call it correctly and anticipate the aftermath.

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 75%, with descriptions for answer, option, and project, so the schema already does most of the work. The description only says 'pick an option', adding no format, indexing, or project-scoping detail beyond the schema; baseline 3 applies.

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

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

The description communicates the action – pick an option on a pending question and continue – and implies the question is marked assumed. However, it never names the resource being assumed from (a question/answer) until incidental phrasing, and it does not explicitly distinguish itself from the sibling tool 'answer', which is the critical contrast an agent must make.

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?

'Can't wait for the human?' gives an implied trigger (human unresponsive/unavailable), which is genuine guidance. But it never names 'answer' as the alternative, never says when assuming is inappropriate, and leaves the boundary between answering and assuming 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 destructive/idempotent/not-read-only, and the description adds real context beyond that: the 30-minute lease expiry, the refusal behavior for items assigned to others, and the release semantics with a required note. It does not explain simultaneous-claim races or whether the claim is strictly exclusive versus advisory beyond the 'other agents pick something else' implication.

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 and every sentence carries lifecycle information. The delivery is somewhat run-on, with semicolons and parentheticals stacking expiry, completion, release and refusal into two long sentences, which costs a bit of scannability.

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 4-parameter mutation tool with no output schema, the description covers the essentials: what claiming does, how long it lasts, how to end it cleanly, and how conflicting ownership is handled. Missing only edge behavior such as what happens when two agents claim at once or what the call returns.

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 75%, so the schema already explains force, project and release. The description nonetheless adds workflow meaning to release (drop the claim without finishing, after recording what you did and ruled out) and to the refusal case that force overrides, which is more than restating 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?

The description states a specific action and effect: announce you're working on an item so other agents choose something else, i.e. a cooperative advisory lock. It names related siblings in passing (tick drops the claim, edit's add_note for the note), which helps the agent place it in the workflow, though the primary verb 'claim' itself only appears in the name/title.

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 clear when-to-use ('say you're working on an item'), the expiry condition (quiet for 30 minutes), the shutdown path (tick when done, release:true plus a note via edit's add_note when not finishing), and a when-not case (items for someone else are refused). It stops short of explicitly stating when not to claim versus just working unclaimed.

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=false, and the description adds non-trivial context the annotation cannot: deletion is gated on human intent and is reversible via restore. It still doesn't say what happens to an item's subtasks/needs when an item is deleted, and the key-versioning staleness rule lives only in the 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?

Two sentences, front-loaded with the mutable surface, and the parenthetical on needs is genuinely informative rather than filler. The long comma enumeration partly restates schema parameter names, so it is dense but not wasteful.

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 16-parameter mutation tool with a nested fields object and no output schema, the description plus 88% schema coverage leaves the agent able to call it correctly, and the delete/restore story is covered. Minor gap: no statement of what a successful call returns or confirms, though no output schema exists to lean on.

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 88%, so the baseline is 3, but the description adds real gloss the schema doesn't: needs means the item is blocked until those are done, options applies to a question, and "its place in the list" maps to the before/after pair. That semantic framing raises it above 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?

A concrete verb plus an enumerated list of what can be changed (list, title, section, fields, needs, notes, options, position) and the delete/restore pair. Purpose is unambiguous, but no sibling tool is named, so the boundary with tick/claim/answer/section is only implied by the attribute list.

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?

"delete only when the human asks, or calls the work off, or for a duplicate you made; restore brings it back" gives explicit conditions for the risky operation and its inverse, which is the guidance an agent most needs here. It stops short of saying when to prefer tick/claim/answer instead, which the schema covers but the description does not.

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 annotations it discloses genuinely load-bearing behavior: all-or-nothing atomicity, duplicate merging, title-based skipping of items already in a list, a 20,000-character cap, and the metadata comment grammar including 'needs' dependency references. The dedup/skip rule is consistent with idempotentHint=true rather than contradicting 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 is front-loaded, but the body is a single run-on block of semicolon-chained clauses, including awkward phrasing like 'What only the human can do is a request and a decision of theirs a question, not also a task.' The format spec and metadata grammar would be far more usable as structured bullets; no sentence is superfluous, but the packaging costs 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?

Covers format, limits, dedup, atomicity, dependency references and project scope for a schema-complex, nested-parameter mutation tool with no output schema. The one gap is what happens on success or rejection beyond 'all in or nothing' — no mention of counts, error reporting, or what the caller gets back.

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 already 100%, so the baseline is 3; the description goes further by spelling out the Markdown grammar (## headings, checkbox syntax, indented notes, subtasks, question options with '(recommended)') and a full metadata comment field list (id, by, at, needs, prio, done, done-by, answer, answered-by) that the schema does not document. It is dense and partly overlaps the schema's own 'items as Markdown' phrasing, which keeps it off a 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 concrete verb and destination: bring work kept elsewhere (TODO files, issues, other tools' lists) into the lists, in one call. 'In one call' implicitly distinguishes it from the single-item sibling 'add', but no sibling is named outright, so the agent must infer the boundary.

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 hard precondition ('once the human says yes') and a scoping exclusion ('a log of past work stays in its file: bring only the open work it names'), plus 'this project only'. It never routes the agent to 'add' or another alternative for single items, so the when-not guidance is partial rather than 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavior about pagination (50 items at a time, plus where the next page starts) and the one-item key mode, but does not describe rate limits, permissions, or deeper output behavior.

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 short and reasonably front-loaded. However, the middle sentence ('Answer every question about the work and the lists with it') is vague and does not clearly earn its place compared with the more useful purpose and pagination sentences.

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 ten optional parameters, rich schema descriptions, and strong annotations, the description is minimally adequate. It still leaves important gaps around how to choose among sibling tools and what a returned list item looks like beyond the pagination note.

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 all ten parameters are already well documented in the schema. The description mentions key, open/done status, the 50-item default, and pagination, but it mostly restates what the schema already says rather than adding new parameter semantics.

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 identifies a resource collection (open tasks, requests, questions) and notes that passing a key reads one item instead of listing. However, it does not clearly distinguish this tool from close siblings such as lists, view, or find, and the phrasing is indirect rather than a crisp verb+resource statement.

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 sentence 'Answer every question about the work and the lists with it' implies broad use but provides no real when-to-use/when-not-to-use guidance. It names no alternatives and gives no rule for choosing between this tool and sibling list/view/search-style tools.

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 non-idempotent, so the safety bar is partly met. The description adds genuinely non-structured context: list items behave like tasks and the list name should be passed as `kind` in downstream tools — a cross-tool behavioral fact an agent could not infer. It does not restate the force/refusal semantics (those live in the schema) or explain permissions.

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, front-loaded with the operations before the disambiguation. The compression is aggressive — 'list shows them all' and 'pass its name as kind' are dense enough to need a second read — 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 six optional parameters and no output schema, the biggest operational fact — that a call should carry at most one of add/rename/remove, with `to` only paired to `rename` — is stated nowhere, though the schema hints at it. Purpose and cross-tool behavior are covered, so it is serviceable but leaves the call shape 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 83%, so the schema already explains to/add/remove/rename/project and the force escape hatch. The description adds only the 'pass its name as kind' hint, which concerns how the list identifier is reused elsewhere rather than clarifying this tool's own parameters. 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?

Names three specific verbs (add, rename, remove) applied to a specific resource (the human's own lists such as ideas/bugs), and explicitly contrasts it with 'a heading in the backlog', which maps to the `section` sibling. The pointer 'list shows them all' further disambiguates it from the `list` tool. It loses a point only because the telegraphic phrasing ('lists of your own') takes a moment to parse.

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 concrete trigger ('when they ask') and an explicit non-use case (don't do this for a heading in the backlog, i.e. use `section`), plus routes enumeration to `list`. No mention of when to use `add`/`tick` instead once the list exists, so it stops short of full alternative coverage.

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, so the safety profile is covered. The description adds genuinely non-structural behavior: the tool is human-gated, and the response is not the operation result but 'an address to send the file to' — a two-step upload flow an agent could not infer from the schema. It does not explicitly say whether a successful set replaces an existing logo, which is the one remaining behavioral gap.

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 purpose before the workflow and the no-handling. The first sentence is dense and syntactically winding ('...only once the human says yes to that file: find the project's own mark...'), but every clause carries actionable meaning, so there is little fat to trim.

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, human-in-the-loop mutation with full schema coverage and no output schema, the description covers motivation, preconditions, image selection, refusal handling, and the shape of the reply. The only material omission is whether setting a logo overwrites an existing one rather than being refused, which matters given destructiveHint=true.

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 five parameters and a baseline of 3 applies. The description still adds meaning beyond it: it clarifies that 'no' terminates only the offer, that 'yes' authorizes a specific file, and that the file should be chosen by size/prominence (app icon or brand image over a small favicon), which the 'file' parameter description 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?

Opens with a specific verb and resource: 'Set the project's logo from an image in its repo'. It also scopes the scope of the action (repo-sourced image, human approval) and implies the selection criteria for which image, so an agent knows exactly what it does and none of the sibling tools (edit, add, claim) compete for this action.

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 precondition ('only once the human says yes to that file'), the procedure ('find the project's own mark at its largest... and show it to them first'), and the when-not ('offer it once when the project has none'), plus the scope of a refusal ('a no stops only the offer'). Nothing about when to invoke or not invoke 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 cover the write-but-not-destructive, non-idempotent, closed-world profile. The description adds genuinely non-derived behavior: delivery is asynchronous and indirect ("reaches them in their news under their next tool reply") and no ownership claim is required to send. It stops short of saying what happens if the recipient is unknown or whether re-sending duplicates the message.

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 sentences with the use cases and the delivery behavior front-loaded, zero filler. The second sentence's phrasing ("in their news under their next tool reply") is slightly compressed but still parses.

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 three-parameter send tool with no output schema, the description supplies the two things an agent can't get elsewhere: delivery timing/target surface and the lack of a permission prerequisite. Failure modes (bad recipient, unknown project) and confirmation behavior are unstated, but the essentials for correct invocation are present.

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 67% and the 'to' description is already rich (item key, agent name, session id, or "all"), as is 'project'. The description adds no parameter-level meaning beyond restating that a recipient and content exist, so it neither compensates for the coverage gap nor detracts.

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-resource pair (tell/message another agent) and concretizes it with three example payloads: needing an item, a change to something they build on, a finding. It does not name or contrast any sibling tool (e.g. answer, news), so the agent must infer the boundary with the rest of the set.

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 states the concrete situations that call for it and adds a precondition clarification ("no claim is needed to send one"), which implicitly steers away from the claim tool. There is no explicit when-not case and no sibling named as the alternative, so the routing guidance stops short of the top band.

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 this is a non-read-only, non-destructive, non-idempotent creation, so the safety profile is covered. The description adds real context beyond them: the project starts with empty lists, ownership is either personal or visible to an entire team, and other tools subsequently treat it as the project. It does not disclose collision behavior or what is returned, but that is a modest gap given the annotations in place.

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 purpose is front-loaded and the text is short with no filler, which is good. But the third sentence ("It is your own, or with team that team's, for everyone in it") is garbled to the point of requiring re-parsing, and "The other tools then take it as project" is ambiguous about whether context switches automatically.

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 creation tool with full schema coverage and annotations, the essentials are present: what is created, ownership scope, and downstream effect on other tools. It leaves unclear what the call returns, how name collisions are handled, and whether creating a project makes it the active context, which matters given there is no output schema to fall back on.

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 parameters are documented with examples in the schema, so the baseline is 3. The description reinforces the naming convention ("Name it after that work") and the personal-vs-team ownership choice, but adds no format, length, or validation detail beyond what the schema already supplies.

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 verb and resource ("Start a new project") and adds meaningful scope detail: it is created with empty lists and is intended for work belonging to no existing project. It does not contrast itself with the `projects` or `list` siblings, so an agent must infer the boundary, and the phrasing "It is your own, or with team that team's" is grammatically mangled enough to slow comprehension.

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?

"for work that belongs to none of your projects yet, such as a new repo" gives a genuine when-to-create condition, and the team sentence implies the personal-vs-team choice. However, no alternative tool is named and no exclusion is stated (e.g., what to do when the work does belong to an existing project), so the routing guidance is implied rather than 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 declare readOnlyHint=true but idempotentHint=false, and the description usefully explains why repeated calls differ ('since you last looked', 'each is told once'). The one ambiguity is whether 'told once' means reading consumes/marks items as delivered, which would be a side effect worth clarifying against the read-only hint — but it reads primarily as a cursor-style feed, not a 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?

Two tight sentences with the core delta semantic front-loaded and a dense but non-redundant enumeration of item types. 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 read-only feed with no output schema, the description gives enough to know what comes back and why repeated calls differ. Minor gaps remain: item ordering, whether anything is consumed, and how to re-read history, none of which are covered elsewhere.

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

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

Schema description coverage is 100% and the single 'project' parameter is fully documented (name or id, defaults to all projects). The description adds nothing about scoping the news feed to a project, 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?

The description concretely enumerates what the tool returns — human answers and edits, other agents' claims, ticks, notes, and messages — which is far more informative than the opaque name 'news'. It conveys a delta/changelog semantic ('what changed since you last looked') that differs from static siblings like list/view, though it never names those siblings to sharpen the distinction.

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?

'Since you last looked' and 'each is told once' imply the calling pattern: call it to catch up, and items won't repeat. However, there is no explicit when-to-use/when-not-to-use guidance, no mention of alternatives such as list or view, and no statement of how often to call 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds one piece of real context — that projects scope every downstream tool — but says nothing about result shape, ordering, or behavior for a user with no projects. Adds value, not rich behavior.

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, front-loaded with the action and resource. The trailing clause "for what waits on them" is slightly opaque and could be tightened, but no sentence is filler.

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

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

For a zero-parameter, read-only listing tool with no output schema, the description covers what it returns (projects plus open work per project) and its role as the entry point for the whole toolset. Only the result format/edge cases are left implicit, which is minor here.

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 tool takes zero parameters, so the baseline is 4 and there is nothing the description could or should document at the parameter level. The mention that other tools consume a project identifier is a bonus for the agent's next call, not a substitution for schema detail.

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+resource ("List the projects you are on") and adds what is included with each project, which separates it from siblings like `list` and `lists`. The phrasing "the place to start for what waits on them" is a little abstract, but the core operation is 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 place to start" positions it as the entry point, and "every other tool takes one of them as project" is a genuinely useful routing rule: you must call this first to obtain project identifiers. No explicit exclusions or named alternative, so it stops short of a 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 declare destructiveHint=true and readOnlyHint=false, so the removal capability is consistent and expected. The description adds nothing beyond that — no statement of what happens to the removed heading's items (the `into` parameter's role), and no note on irreversibility, though the schema covers the destination case.

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, front-loaded with the operation set before the usage rule. The clause 'Give one of to, before, after or remove' is slightly compressed/ungrammatical but wastes no space.

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 an 8-parameter mutating tool with no output schema, the description covers the operation choice but never mentions `into` (where items go on removal) or `kind`, both of which change the call materially. An agent could construct a destructive call without realizing it must decide the fate of the heading's items.

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 88%, so baseline is 3, but the description adds a genuine constraint not present in the schema: exactly one of to/before/after/remove must be supplied. It omits `into`, `kind` and `project`, but those are adequately described in the schema itself.

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?

Uses specific verbs (rename, reorder, remove) against a specific resource (a heading in a list), and explicitly separates itself from the `add` sibling for creation. It never reconciles the tool name `section` with 'heading', so the noun mapping is left to inference.

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 real routing guidance: creation belongs to `add`, and this tool takes one of to/before/after/remove. It does not spell out the mapping of intent to parameter (rename→to, reorder→before/after), leaving the agent to infer 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 annotations, the description discloses that the setting defaults off, that a no is persisted so assistants do not re-ask, that only Claude Code or Codex on a Hamloy-linked computer can call it, and how the human can later disable it on their account page. These are substantive behavioral and authorization details not present in the annotations.

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 information is useful and mostly front-loaded, but the first sentence is long and indirect, and some phrases ('on this computer, in this folder') are repeated. Every sentence contributes, but the structure could be tighter and more imperative.

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 the annotations, complete schema descriptions, and no output schema, the description covers the default state, the human-in-the-loop requirement, consequences of each answer, authorization restrictions, and how to reverse the setting. Nothing essential for correct invocation 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 semantic guidance for yes/no: it tells the agent to call with yes: true after consent or no: true after refusal, and explains that no is retained. It does not add much about the project parameter 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?

The description makes clear that this tool records the human's consent for whether the board may start Claude Code or Codex in this project/computer/folder. It is specific about the resource and scope, though it uses a noun phrase rather than a direct verb like 'records' and the name 'start_here' is misleading on its own.

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 states when to use the tool ('ask them, and call this with yes: true once they say yes, or no: true if they say no') and when not to use it ('Never on your own'). It also explains the consequence of a no and that a yes remains possible later, giving complete usage 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 already declare non-read-only, idempotent, non-destructive behavior. The description adds a meaningful side effect not captured by annotations: it drops the caller's claim on the item, and it clarifies reopening semantics.

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, front-loaded with the primary action and immediately followed by the key side effect. No wasted 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 four-parameter mutation tool with full schema coverage and annotations, the description covers the core action and the important claim-dropping side effect. It does not need to explain return values because no output schema exists, though it could say more about note handling.

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 all four parameters thoroughly. The description only restates the done:false behavior and adds no further parameter meaning 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?

The description states a specific verb and resource: "Mark a task or request done." It is clear what the tool does, but it does not explicitly distinguish itself from siblings like edit or claim.

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

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

Usage is implied by the action and by the parenthetical that done:false reopens the item. There is no explicit guidance on when to use this versus edit, claim, or answer.

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, readOnlyHint=false, and idempotentHint=false, which establishes the safety profile. The description adds useful behavior: no-argument listing and fixing what the reply warns about. It does not explain deletion, updating an existing view via key, or what the destructive path actually removes, so it adds some but not rich context beyond the annotations.

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 purpose is front-loaded, and every part is relevant, but the description is a dense run-on packing examples and field vocabulary into two long sentences. It is usable but harder to scan than a structured list would be.

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 12-parameter tool with no output schema, the description supplies the missing view vocabulary, common request mappings, and no-argument listing behavior. It leaves some gaps around delete semantics and the exact shape of the reply, but the annotations and schema carry much of that weight.

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 already 83%, so the baseline is 3. The description adds real semantic value by enumerating the fields available to show, sort, group, and filter on, and by giving concrete examples such as sort [-prio], group prio, order [high, medium, low], and filter [blocked=waiting].

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 view of the lists for the board, triggered when the human wants items shown a certain way. It does not explicitly differentiate itself from siblings like list or lists, but the purpose is clear enough to select the tool.

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 trigger ('when the human asks to see them a certain way') and notes that calling with no arguments lists existing views. The examples map common human requests to concrete configurations. It stops short of naming alternatives or exclusions, but the usage context is strong.

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