fenbs

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description adds value by disclosing the authorization requirement ('Needs the permission to change tasks') and the visibility/signature behavior ('It is signed with your name', 'every assistant reads both'). It does not say what happens if a duplicate is submitted, so it stops short of a 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?

It is dense and front-loaded: the purpose leads, the exclusion and alternative follow, and operational details (permission, signature, scope, duplicate check) come last. Slightly long with several chained clauses, but nearly every clause carries routing or behavioral information.

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

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

For a 4-parameter write tool with no output schema, the description covers purpose, exclusion criteria, alternative tool, required permission, attribution, project scope, and duplicate-handling workflow. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the schema already documents each parameter, so the baseline is 3. The description adds meaning by tying project scoping to behavior ('Leave project blank when it applies to everything' combined with 'every assistant reads both'), clarifying the blast radius of an omitted project rather than just restating the field.

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 concrete verb+resource ('Leave a context note for the next AI assistant') and immediately defines what qualifies as a note ('a FACT you worked out that is nobody's choice -- how the code works, a trap, where something lives'). It explicitly contrasts itself with fenbs_add_decision, so an agent can distinguish it from the nearest sibling without opening either schema.

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

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

It states the when ('a FACT you worked out'), the when-not ('NOT for rules, preferences or anything a person decided'), the alternative for the excluded case (fenbs_add_decision, with a sub-case rule), and a pre-flight check ('Check fenbs_list_context_notes first ... change it with fenbs_update_context_note rather than adding one that contradicts it'). This is about as complete as usage routing gets.

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 write. The description adds substantial context beyond them: the agent's authority limit ('You may write a decision down; you never make one'), the permission requirement ('Needs permission to change tasks'), and the downstream effect of standingRule (rules are surfaced in every assistant's AI context and must be followed).

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?

Long but front-loaded: the core purpose is the first clause, followed by the rule-recording case, the authority constraint, then linking/permission notes. Nearly every sentence earns its place, though the density of distinct instructions is high enough to be slightly taxing.

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 14-parameter mutation tool with no output schema, the description covers the missing pieces: authority boundaries, permission requirements, the search-before-write habit, and the downstream consequence of standingRule. An agent has everything needed to call this 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 description coverage is 100%, so the baseline is 3. The description goes beyond the per-field docs by showing how parameters combine in a workflow ('status decided, standingRule true, them in deciders, their words quoted in reason'), which the schema alone does not express.

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

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

States a specific verb+resource ('Record a decision, or ask a question for a person to decide') and explicitly carves out the boundary against the sibling fenbs_add_context_note ('never as a context note'). An agent can distinguish this from add_context_note, add_lesson, and update_decision without opening any schema.

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

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

Gives explicit when-to-use (person states how something must always/never be done), when-not-to (never as a context note), prerequisites ('Search fenbs_list_decisions first'), and the alternative for changing a rule ('record a new decision with supersedes'). Routing to alternatives is unusually complete.

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

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

Annotations declare this as a non-read-only, non-idempotent write with no destructive hint. Beyond that, the description adds the permission requirement ('Needs permission to change tasks') and the fact that an unknown group name silently creates a new group, both of which are behavioral context not in the annotations. It does not disclose response contents, but no output schema exists and the write semantics are otherwise 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?

Front-loaded with the purpose and definition, then progressively adding triggers, prerequisites, and alternatives. It runs six lines and one clause (the near-miss list) partially repeats the following sentence, but nearly every sentence carries actionable content.

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

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

For a 9-parameter, single-required-field write tool with no output schema, the description covers the decision-relevant essentials: intention, trigger conditions, dedup step, grouping, task linkage, and permission need. It leaves secondary fields (whatHappened, doDifferently, category, project, groupId) entirely to the schema, which documents them fully, so this is adequate though not exhaustive.

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 nine parameters, including the group/groupId precedence rules. The description reinforces the group enum and task linkage but adds no syntax or format beyond what the schema states; 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 verb+resource ('Record a lesson learned') and goes further by defining what counts as a lesson (near miss, wrong assumption, missed step, slow fix). It explicitly demarcates itself from the sibling fenbs_apply_lesson ('A lesson is not a rule'), so an agent can pick between them without opening schemas.

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

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

Gives concrete trigger conditions ('when you finish a task that taught something, or when the person you work for says "we learned that..."'), a prerequisite ('Search fenbs_list_lessons first'), and an explicit alternative with its condition (fenbs_apply_lesson when the lesson should hold from now on). Nothing is left to inference.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds genuine value beyond them: case-insensitive name matching and the guarantee that an existing project is returned rather than duplicated. It also flags an authorization requirement ("Needs permission to change tasks"), a detail annotations do not carry.

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

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

Three tight sentences with zero filler. The core action and the key non-obvious trait (safe to call when the project may already exist) are front-loaded, with the permission caveat last.

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 create tool with rich annotations and no output schema, the description covers purpose, idempotent behavior, matching rules, and auth requirements. Nothing an agent needs to invoke it correctly is missing.

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

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

With one parameter at 100% schema coverage, the baseline is 3, but the description adds semantics the schema does not: the name is matched case-insensitively and typically corresponds to a repository folder. That is real added meaning for the sole 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?

States a specific verb and resource ("Add a project to the board") and adds a domain scoping hint ("for software, usually one per repository"). It is clearly distinguishable from sibling tools like fenbs_rename_project or fenbs_update_project, though it never names an alternative explicitly.

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

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

Gives clear usage context: "Safe to call when it may already exist" tells the agent it need not pre-check for existence. However, there is no explicit when-not-to-use guidance or named alternative (e.g., use fenbs_update_project to modify an existing one).

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

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

Goes beyond the annotations by disclosing real side effects ("The lesson is then marked applied and links to what it became") and an auth requirement ("Needs permission to change tasks"). It also clarifies that asRule only *proposes* — a human decides — which is important behavioral context the annotations do not carry. It does not address re-invocation/duplicate effects despite idempotentHint=false.

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

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

Front-loads the core action and effect, then the two modes, then the side effect and permission note — a logical order with no filler sentences. The em-dash interludes make it dense, but every clause carries information.

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

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

For a 6-param mutation tool with no output schema, it covers the important ground: what gets created in each mode, that the lesson is marked applied, and the permission gate. What's missing is failure/idempotency behavior (calling twice, or applying an already-applied lesson), which matters given idempotentHint=false.

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% (baseline 3), and the description adds genuine meaning on top: asRule "proposes a rule (a decision with standingRule, status proposed)" and that the agent "never decides it" — details absent from the schema. noteBody/ruleText/noteCategory get no added semantics beyond the schema text.

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

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

States a specific verb+resource ("Apply a lesson") and immediately names the observable outcome: "it changes how the work is done from now on." That effect distinguishes it from add_lesson (create), update_lesson (edit), and the raw add_context_note/add_decision siblings, which create those artifacts directly rather than deriving them from an existing lesson.

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 covers when each mode applies: asNote for "a fact or a trap," asRule for something "a person must decide it before it binds; you never decide it," and "Either or both." It gives clear conditional guidance but never names an alternative tool (e.g., when to use add_context_note directly instead), so it stops just short of full when-not 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?

Goes well beyond the annotations: it discloses that archived tasks leave the board but retain refs and history, that search still finds them, that open work is never touched, and that the operation requires permission. This meaningfully frames the destructiveHint=false annotation as a genuinely reversible operation 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?

Front-loads the core action and stays information-dense, but runs to five clauses and could be trimmed slightly. Every sentence nevertheless carries distinct, useful content (scope, reversibility, safety, precondition).

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 output schema, the description covers the action, the filtering modes, the side effects on the board and search, the reversal path, the dry-run precondition, and permission needs. An agent has everything required to call it safely.

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 baseline is 3, but the description adds real value by spelling out the OR-like selection semantics ('every Completed task, or only those not changed for olderThanDays, of one project, or the refs given') that the schema does not make explicit about how filters combine.

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: 'archive every Completed task,' with scope qualifiers (olderThanDays, one project, refs). This is clearly distinguishable from sibling mutation tools like fenbs_delete_item or fenbs_update_item, which the description explicitly references as the reversal path.

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 when-to-use ('Archive only when the person you work for asks'), a mandatory precondition ('run with dryRun true first and tell them how many would go'), and names the sibling that reverses it ('fenbs_update_item archived false puts one back'). Nothing is left to inference.

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

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent write, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say comments are append-only and immutable (note there is no update/delete comment sibling), whether the ref must resolve to an existing task, or what a failed ref does. With annotations present the bar is lower, but this description contributes no behavioral detail.

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 and target come first. It is efficient, though its brevity is close to under-specification rather than disciplined conciseness.

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 would need to explain what is returned or confirmed, and it does not. Combined with undocumented ref/body parameters and no 'session' explanation in the description, an agent lacks enough information to call this confidently beyond the obvious case.

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

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

Schema description coverage is only 33%, with 'ref' and 'body' undocumented in the schema. The phrase 'by ref' weakly implies ref identifies the task and 'comment' implies body is the text, but the format of ref (item id, task key, slug) is never clarified, so the description only marginally 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 and resource ('Add a comment to a task') and identifies the target via 'ref'. It is distinguishable from siblings like fenbs_add_context_note or fenbs_add_lesson by naming 'task', though it never explains how a comment differs from those note/lesson siblings, which is the nearest ambiguity.

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?

No indication of when to comment versus using fenbs_add_context_note, no prerequisites, and no exclusions. The agent is left to infer the intended context entirely.

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 the safety profile (readOnly=false, destructive=false, idempotent=false), and the description layers on substantial context the annotations cannot: permission requirement, the 14-day similarity check and its 'created: false' outcome, free-board limit notices with upgradeUrl, and refusal handling. This is real behavior disclosure beyond the structured fields.

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

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

Front-loaded with the core action and dense but purposeful. Every sentence carries load for a 19-parameter tool, though the single unbroken block makes the dedup flow harder to scan than a few short clauses would.

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 19-parameter mutation tool with no output schema, the description covers permissions, dedup semantics, plan-limit messaging, refusal handling, and the roles of the many optional fields, and it sketches the return shape (created flag, matches, refs). An agent has what it needs to call it correctly.

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

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

Schema coverage is 89%, so the schema already carries most parameter meaning. The description nonetheless adds cross-parameter guidance the schema lacks: the note/plan/steps/whereItStands separation of duties, and the human-facing lane names. It stops short of detailing several optional fields, keeping it just above the schema-only 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?

Opens with a specific verb+resource, 'Add a task to a board', and immediately names the constraints and the distinct dedup behavior that separates it from a plain insert. It explicitly routes to siblings (fenbs_comment, fenbs_update_item) so an agent can tell it apart without opening schemas.

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

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

Gives explicit when/when-not: comment on an open match via fenbs_comment, move a finished match back with fenbs_update_item, or re-call with unlessSimilar:false alone when the item is genuinely different. It also names the automated-source condition (pass key) and the exception, so nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds traits the annotations cannot express: the deletion is currently irreversible ("cannot be restored from fenbs yet") and it "Needs permission to change tasks." It also prescribes a disclosure protocol (state the note and reason first). It stops short of describing behavior on a nonexistent id or repeated calls, so not a full 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?

Front-loaded with the destructive action and its condition; the identifier sourcing and the update alternative follow in priority order. The final clauses are dense and slightly run-on ("...so when a note is only out of date, update it instead; say which note you are deleting and why before you do it"), 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?

For a 2-parameter destructive mutation with no output schema, the description covers what is deleted, how to identify it, irreversibility, the permission requirement, and the alternative tool. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% and both parameters already document their source and exact-match semantics, including the duplicate-title refusal. The description restates the id-or-title choice and its provenance (fenbs_list_context_notes) without adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("Delete a context note") plus the qualifying condition ("wrong or no longer applies"), which cleanly separates it from fenbs_delete_decision, fenbs_delete_lesson, and fenbs_delete_project. An agent can identify the target artifact and intent without opening the schema.

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

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

Names the sibling that supplies the identifier (fenbs_list_context_notes) and states the when-not case explicitly: "when a note is only out of date, update it instead." That routes the agent to the update path rather than deletion, which is exactly the decision this tool needs to gate.

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

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

Annotations already flag destructiveHint=true and non-idempotent, but the description adds value beyond them: the number is never reused, and restore recovers deciders, links, and versions. It also discloses the task-change permission requirement. What is left implicit is whether the deletion is immediate or soft, but the recovery detail largely covers the risk profile.

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, front-loaded with the core action, then recovery semantics, then the rationale and permission caveats. No redundant restatement of the title or annotations.

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 tool with annotations covering safety, the description supplies irreversibility, recoverability detail, an audit expectation, and a permission gate. The only real gap is what a 'ref' looks like, which sibling tools likely share as a convention.

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 one parameter at 0% schema description coverage. 'By ref' confirms the parameter is an identifier but adds no format, source, or example beyond the schema's field name, so the description only marginally 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 (delete) and resource (decision) with an identifier scheme ('by ref'). It distinguishes itself from the sibling fenbs_restore_decision and the update/get/list decision tools by naming the recovery counterpart explicitly, so an agent can tell them apart without opening a schema.

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

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

Gives concrete invocation prerequisites: 'Say why before you do it' (a rationale must accompany the call) and 'Needs permission to change tasks' (an authorization gate). It also points to fenbs_restore_decision as the undo path, though it stops short of an explicit when-not-to-use condition.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=false), the description discloses the exact blast radius: number, comments, followers and links survive, files are permanently removed, and restore reverses everything except files. It also states the permission requirement, which annotations never convey.

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

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

Four tight clauses, front-loaded with the action, then recoverability, then the irreversible caveat, then the permission note. No filler; every sentence changes how the agent should behave.

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

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

For a single-parameter destructive tool with no output schema, the behavioral picture is essentially complete. The only gap is the undocumented ref format, which is a minor omission against otherwise thorough disclosure.

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 one parameter with 0% schema description coverage, so the description carries the burden and only says 'by ref'. It implies the argument is an identifier but never states the format or where the ref comes from, leaving ambiguity an agent must resolve elsewhere.

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 a task by ref') and immediately qualifies the operation as a soft delete. It distinguishes itself from the sibling restore tool by naming fenbs_restore_item as the reversal path, so an agent can tell the two apart 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 explicitly tells the caller to justify the deletion first ('Say what you are deleting and why before you do it') and points to fenbs_restore_item for recovery, along with the permission prerequisite. It does not, however, contrast with adjacent destructive siblings like fenbs_archive_completed, so the exclusion set is incomplete.

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, so the safety baseline is covered; the description goes well beyond that by disclosing that the identifier is never reused, that restore returns the lesson with its links and versions intact, and that an elevated permission is required. These are exactly the consequence/permission details an agent needs before invoking a destructive call.

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

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

Four short sentences, front-loaded with the action and its consequence, with no filler. The only friction is 'Say why before you do it', which implies a reason argument that does not exist in the schema and could briefly misdirect an agent.

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

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

For a single-parameter destructive tool with no output schema, the description supplies the destructive consequence, the reversibility path, and the permission requirement. Only the parameter's format and a clearer handling of the 'say why' expectation are 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?

There is one parameter ('ref') at 0% schema description coverage, and the description only echoes it as 'by ref' without stating the identifier format, where to obtain it, or whether it accepts titles. It adds token value over the bare schema but does not compensate 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 and resource ('Delete a lesson by ref') and immediately names the sibling that undoes it (fenbs_restore_lesson), so it is distinguishable from the rest of the delete_* family at a glance.

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

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

Names an explicit alternative (fenbs_restore_lesson) as the recovery path for this destructive action, and states a precondition ('Needs permission to change tasks') plus a required workflow step ('Say why before you do it'). It does not, however, contrast this with sibling deletes such as fenbs_delete_item, so routing among delete tools is left to inference.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered; the description goes well beyond that by disclosing that tasks are NOT cascade-deleted, the divergent outcomes with and without moveTo, and the restore interaction. This is exactly the 'what actually gets destroyed' context a mutation tool needs.

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

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

Front-loaded with the action, and every sentence carries load-bearing information (cascade behavior, restore behavior, pre-check, permission). The middle sentence is dense and clause-heavy, slightly reducing readability, but 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?

No output schema exists, yet the description covers the destructive scope, the effect on child tasks under both parameter paths, reversibility via restore, and the permission requirement. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real meaning for moveTo: it explains the consequence of supplying it ('they move to that project for good') versus omitting it (tasks resurface on restore). The 'project' parameter remains schema-only, which keeps this below 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?

Opens with a specific verb+resource ('Delete a project') that is immediately distinguishable from the many sibling delete tools (delete_item, delete_decision, delete_lesson, delete_context_note) by resource. An agent knows exactly what this does without opening the schema.

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

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

Explicitly routes the agent: it names fenbs_restore_project as the inverse operation and fenbs_list_projects as the recommended pre-check ('Say how many tasks it has before you do it'), and states the prerequisite ('Needs permission to change tasks'). Conditions and alternatives are all spelled out rather than inferred.

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

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

Annotations only give readOnly=false/idempotent=false/destructive=false; the description adds substantial context beyond them: the no-op dry-run ("Nothing changes without ship"), exactly what shipping does (task becomes Completed with resolution shipped, old text preserved in History), failure surfacing (non-matching refs returned in notShipped), and the permission requirement.

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

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

Front-loaded with the trigger and the two-phase shape, and nearly every sentence carries operational weight. It is a dense single block, though, and phrasing like "where it stands" repeated inline slightly taxes readability.

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

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

For a mutating, non-idempotent tool with no output schema, the description covers the workflow, side effects, exclusions, permissions, and partial-match returns. The exact shape of the first-call result is only described conceptually, so it stops just short of fully complete.

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 every parameter is already documented in the schema; baseline is 3. The description reinforces commit provenance (git log formatting) and the interdependency that ship refs are chosen from a prior call's matches, but adds little syntax or meaning the schema lacks.

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 two-phase verb+resource: find tasks whose commits just went live, then mark the fully-live ones as shipped. It is unmistakably distinct from the CRUD siblings (add/update/delete/restore) and even from fenbs_release_task, since it frames the work as deploy-driven commit matching.

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

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

Explicit when-to-use ("After a deploy or release"), explicit sequencing (call first without ship, then call again with ship), and an explicit exclusion rule ("Leave out a task with part still not live, such as an app update or a second repository"). The permission prerequisite ("Shipping needs permission to move tasks") is also stated.

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

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

Annotations only declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the description adds genuine value: the permission requirement for 'business' flags and the failure mode on personal boards. It also documents 'on=false' as the unflag path, which the agent needs to know this tool is bidirectional rather than purely additive.

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?

Compact and front-loaded: the action comes first, then mode semantics, then intent. Phrasing is slightly convoluted (nested quotes around 'mine'/'business' and reversed word order in 'which "mine" is the flag'), but nothing is padded.

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 mutation with no output schema, the description covers permission requirements, the error condition on personal boards, the default for 'on', and uses for a flag. The remaining gap is the identity of 'ref', which is left to inference.

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

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

Schema coverage is only 33% (only 'on' is documented there), so the description must compensate. It explains 'mine' and 'business' thoroughly, but leaves 'ref' entirely unexplained beyond the implied 'the task'. That is one of two required parameters left undefined, so it only partially closes the 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?

The description opens with a specific verb+resource ('Flag a task, or take a flag off') and immediately distinguishes the two flag modes ('mine' vs 'business'), which is the non-obvious part of this tool. It does not need sibling differentiation since no other flag tool exists among the siblings, but it also never states that 'ref' identifies the task to flag.

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 conditions for choosing each mode: 'mine' works on any board and needs only visibility, while 'business' needs the 'Flag for everyone' permission and is refused on a personal board. It also frames intent ('look at this') and points to the note/plan/comments for rationale. No real exclusion of the tool itself, but the enum routing guidance is strong.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: the Rules are 'binding, so follow every one', the '· 2 files' convention, and what each returned section means. It does not cover pagination or size limits, keeping it just short of 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?

Front-loaded with purpose and sequencing, then walks the returned sections in order. It is dense and long, but with no output schema nearly every clause earns its place by explaining what comes back; the section-by-section inventory is the only place length feels close to excessive.

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 a single optional parameter, the description fully compensates by enumerating the return structure (Rules, project, Where we left off, In progress, Waiting on you, Glossary, notes, lessons, counts, pre-approved). An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100% and the parameter is already documented, but the description adds real semantics: omitting project yields everything-applicable notes, while passing it yields that project's status, rules, words and notes. This goes beyond the schema's 'by name' phrasing.

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

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

States a specific verb and resource ('Read the AI context for this board'), and the scope (board-wide vs per-project) cleanly separates it from siblings like fenbs_list_context_notes and fenbs_get_item. An agent knows exactly what this returns.

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

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

Explicit sequencing ('Call it straight after fenbs_whoami', 'before touching the work') and explicit scoping ('only ask for the project you are working on'). The relationship to sibling tools (fenbs_get_item for files) is also named.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds content-level context about what a decision record contains (question, rationale, decider, linked tasks, versions), but says nothing about error behavior for an unknown ref or any access constraints.

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 zero wasted words; the resource and identifier come first, followed by a compact enumeration of the payload an agent can expect.

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

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

With no output schema, the description shoulders the burden of describing the return, and it does so by listing the decision's fields. It is slightly incomplete on failure modes and ref discovery, but adequate for a simple one-parameter read 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 description coverage is 0% for the single 'ref' parameter, so the description must compensate. It partially does by giving the 'DEC-004' example, which conveys the expected identifier format, but doesn't state that ref is required or that it must be an existing decision ID.

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+resource: retrieve one decision identified by a ref, and gives a concrete ref example (DEC-004). It implicitly separates itself from the sibling fenbs_list_decisions by emphasizing 'One decision', though it never explicitly names an alternative 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?

Usage is only implied: fetch a single decision when you already have its ref. There is no explicit when-to-use vs when-not-to-use guidance, no mention of switching to fenbs_list_decisions to find a ref first, and no exclusions.

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

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

Goes well past the readOnly/idempotent annotations by disclosing that the link expires in ~15 minutes, is regenerated fresh on each call (so links must not be cached or shared), and that file attachment is a human-only web/phone action. These are exactly the operational traits an agent needs and cannot infer from 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?

Four compact sentences, front-loaded with the purpose before prerequisites, expiry behavior, and constraints. Every sentence carries distinct, actionable information 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?

There is no output schema, and the description covers the return value (a time-limited link), its provenance, and the constraints on using it. For a two-parameter read-only tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented (ref as the task ref with example, id as the file id from fenbs_get_item). The description largely restates that provenance, adding no format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: produces a link to one file attached to a task, for opening or downloading. It distinguishes itself from fenbs_get_item (which is named as the source of the file id) and from any upload/list siblings.

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

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

Explicitly tells the agent the prerequisite (task ref plus file id from fenbs_get_item) and adds handling rules (don't paste the link on the board, cite the ref and filename instead). It stops short of naming a hard exclusion or a competing tool, but the context is unambiguous.

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 read-only, idempotent, non-destructive, closed-world behavior. The description goes further by disclosing the nested shape of the response (what is returned and the capped history size of 20 with newest-first ordering), which is valuable 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?

Front-loaded with the primary purpose, but the long clause about earlierStands/earlierPlans and the history cap is dense and could be tightened. Every part is relevant, yet the phrasing is more verbose than necessary.

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

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

For a read tool with no output schema and only two parameters, the description covers the returned content and the history semantics well. It doesn't explicitly mention permissions or pagination, but those are less critical here and annotations cover safety.

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 documents 'ref' only by type, with no description, and documents 'history' fully. The description clarifies that 'ref' is a task reference like 'FET-014' and explains that history:true returns all earlier versions (last 20 each) rather than just the latest, compensating for the 50% schema coverage.

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 task by ref, e.g. "FET-014"') and enumerates the returned sub-resources (fields, steps, jobs, decisions, comments, files). It clearly distinguishes this single-task fetch from list/search siblings and from fenbs_get_file.

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 when to use it (fetch a single task by ref) and explicitly points to fenbs_get_file for opening an attached file. It doesn't state exclusions such as 'use fenbs_search when you don't have a ref', but the context is clear enough.

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 closed-world, so the safety profile is covered. The description adds real value beyond that by disclosing the shape and breadth of the payload, notably that it includes linked tasks, what the lesson was applied as, and earlier versions. It stops short of noting behavior for a missing/invalid ref, but it meaningfully exceeds the annotation baseline.

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 that leads with the operation and ref, then lists the returned fields without filler. It is dense but every clause describes actual returned content; only the trailing enumeration makes it slightly run-on.

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

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

With no output schema, the description carries the return-value burden and does so by naming the key fields (narrative, status, linked tasks, applied-as, versions). Combined with annotations covering the read-only/idempotent profile, an agent has enough to call it correctly. Only error/not-found behavior and ref validation 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?

There is one parameter (ref) with 0% schema description coverage, so the schema gives no format guidance. The description partially compensates by showing the expected identifier shape, 'ref (LES-004)'. It does not say whether the ref is case-sensitive, what happens on an unknown ref, or whether any other identifier form is accepted.

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

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

States a specific verb+resource: fetch 'one lesson by ref', and enumerates exactly what that lesson record contains (what happened, what we learned, status, linked tasks, applied-as, earlier versions). This clearly separates it from list-style siblings like fenbs_list_lessons. It does not explicitly name a sibling, but the singular 'one lesson by ref' framing makes the scope unambiguous.

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: an agent should call this when it already holds a lesson ref and wants the full record, as opposed to fenbs_list_lessons for enumeration. There is no explicit when-to-use statement, no mention of prerequisites (e.g. needing a valid ref), and no named alternative. Adequate but with a clear gap.

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, so the safety profile is covered structurally. The description adds value beyond that by stating the permission requirement for add/update/delete and by pointing to fenbs_get_context for the full read view. It does not elaborate on what delete removes, but the annotation carries that.

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 resource definition is front-loaded, followed by a compact action-to-parameter map and a short usage rule. Sentences are dense but each carries information. Slightly cluttered by packing four action signatures into one line, but no real waste.

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 7-parameter tool with 29% schema coverage and no output schema, the description covers the action-parameter mapping, permission requirement, when to add, board-vs-project scoping, and the read sibling. Annotations carry the safety profile. It is close to complete, with only minor gaps in parameter constraints and return expectations.

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 only 29%, so the description must compensate, and it does: it maps parameters to each action (list: project, q; add: term, definition, alsoCalled, project; update: id plus any of those; delete: id). This clarifies which fields apply where, which the schema alone does not. It stops short of explaining value formats or constraints.

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 resource (the project glossary: the words a project uses and what each means here) and enumerates the four actions it supports, so an agent understands scope immediately. It even names the sibling that surfaces the full glossary (fenbs_get_context), aiding differentiation. Not quite a 5 since it never explicitly frames this as the management counterpart to read-only glossary views.

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 concrete when-to-use guidance for add ('when a term has a meaning here that a newcomer, or the next assistant, would get wrong') and notes that a project's words and the whole board's both apply. It also flags that add/update/delete require task-change permission. Missing explicit when-not guidance for list/update/delete, so not a full 5.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: the two-step delete flow, that a non-empty group returns itemCount (including deleted items), that deleteItems requires the person's clear confirmation, and that writes need permission to change tasks. It does not describe add/rename side effects or failure modes, so it falls just short of full disclosure.

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

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

Purpose and scope are front-loaded, and the delete flow follows in a logical order. The paragraph is dense with semicolons and a few phrases are awkward ('Delete without a choice first', 'and other groups') and '0 means No group' is repeated, which costs some readability but not enough to bury the key instructions.

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

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

There is no output schema, and the description compensates by describing return information (itemCount) and the delete branching. For a four-action, six-parameter management tool it covers the risky paths well, though it says little about add/rename behavior or what list 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 67%, so the schema already documents id, name, deleteItems and moveToGroupId. The description still adds value by mapping the area enum values to concepts ('Routine processes, Links or Lessons learned page'), restating that 0 means No group, and framing deleteItems vs moveToGroupId as a mutually exclusive choice tied to the confirmation requirement.

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 set of verbs (list, add, rename, delete) and a precise resource (saved groups), then narrows scope further with 'Groups belong to this board and one page.' It also names the sibling tools used for the adjacent record-moving operation, so an agent can distinguish this tool from fenbs_routines/fenbs_listings without opening a schema.

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

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

It gives an explicit when-not: to move a record, use fenbs_routines, fenbs_listings or fenbs_update_lesson with groupId instead of this tool. It also prescribes the delete workflow step by step (first delete without a choice, then either moveToGroupId or deleteItems with clear confirmation), which is genuine when/how guidance rather than implied usage.

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, non-idempotent, non-destructive, closed-world, so the safety bar is partly covered. The description adds real context beyond that: the job exists so "the next window sees it is running," that finish/abandon can happen in any lane, and the DEC-341 constraint forbidding local/temporary paths. It does not say what abandonment does to the record, which keeps it at 4.

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 and lifecycle are front-loaded in the first two sentences, and the DEC-341 constraint plus per-action requirements follow in order of importance. The middle sentence is long and packed with a parenthetical and two clauses, 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 10-parameter, three-mode tool with no output schema and annotations that already cover safety, the description covers the essentials: what a job is, the three actions, per-action required inputs, and the path-prohibition rule. It omits what abandon does to the record and whether recurrence/idempotency matters (only partly covered by idempotentHint=false), so it is not fully complete.

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 90%, so the baseline is 3, but the description adds information the schema cannot express: the conditional requirement mapping (tool/what for start, jobId for finish or abandon) and the rule that branch + base commit must be supplied instead of a path. That is genuine added meaning over the flat required list of ref/action.

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 a background job") plus scope (". . . you start on an In Progress task") and the three lifecycle actions (start, finish, abandon). It is unambiguous and cannot be confused with any sibling tool (decisions, lessons, items), though it never explicitly names a sibling to contrast against, which is the only thing separating it from a 5.

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 spelled out per action: "Start needs tool and what; finish or abandon needs jobId," plus "Finish and abandon work in any lane." That tells the agent exactly which parameters each mode requires. It stops short of exclusions or naming an alternative when a job should not be recorded, so it is not 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuinely new behavioral content: the result is membership-scoped and includes the caller's role per board, which matters because there is no output schema. It omits ordering/pagination behavior, so it is not fully transparent.

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 sentence, front-loaded with the verb and resource, with the scope qualifier and returned field packed into a single clause. No filler, no redundancy with the title or annotations.

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 list tool with full annotation coverage, the description supplies the one thing structured fields cannot: what each entry contains (board plus the caller's role). It is nearly complete, lacking only ordering/format detail, which is minor for a small membership-scoped collection.

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 schema imposes nothing to interpret; per the rubric, 0 params sets a baseline of 4. The description correctly implies no filtering or paging inputs are accepted, consistent with the empty schema.

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

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

States a specific verb (list) and resource (boards) plus the scope of the result (boards you are a member of, with your role). It is clearly a read/list operation, but it never clarifies its relationship to adjacent list tools such as fenbs_list_projects or fenbs_listings, so the agent must guess how a 'board' differs from a 'project'.

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 when-to-use guidance and names no alternative. It does not tell the agent whether this is the entry point for discovering board IDs needed by other tools, nor when to prefer fenbs_list_projects instead. Scope wording ('you are a member of') is a filter, not usage direction.

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds value by disclosing the returned shape — title, project (or 'everything'), category, author, timestamp, and truncated text — plus the fact that ids are the payload other tools require. It does not discuss ordering or limits, so it falls short of 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?

Three tight clauses, front-loaded with the resource and its ids, then the return fields, then the disambiguation from fenbs_get_context. 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?

With no output schema, the description carries the return-value burden and does so by enumerating the fields each note exposes. Combined with the clear routing against fenbs_get_context and the named downstream consumers, an agent has everything needed to call and interpret this 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 both parameters are already documented, and the description largely restates them ('full: true gives the whole text'). It adds only marginal meaning by clarifying that 'everything' refers to notes that apply to everything, which the schema hints at but does not spell out. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('The context notes on this board with their ids') and immediately differentiates itself from the sibling tools that consume those ids (fenbs_update_context_note, fenbs_delete_context_note) and from the reading-oriented fenbs_get_context. An agent can place this tool without opening any schema.

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

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

Explicitly routes the agent: 'fenbs_get_context is what to read before working; this is how to find a note to change.' It also names the downstream tools that need the returned ids, giving both when-to-use and when-to-use-something-else.

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 genuinely new context: newest-first ordering, the working definition of a 'rule,' and the cross-reference that deleted decisions can be restored via fenbs_restore_decision. It stops short of describing result size or pagination, so a 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?

Front-loads the resource and ordering, then the guidance, then the filter list. Dense and mostly waste-free, though the middle 'Search before...' sentence packs three conditions into one long clause that slightly dilutes 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?

No output schema exists, so the description must convey the return content, and it does (decided-by, rationale, open questions, newest first). For a read-only, annotated list tool with 8 optional filters this is close to complete, with only pagination/volume behavior left unstated.

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

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

With 63% schema coverage and 8 parameters, the description compensates for the undocumented q, status, and project filters by naming them. It adds real meaning beyond the text, e.g. the literal search idiom q "DEC-4" finds that one, and reinforcing that task filters to the decisions a task depends on. Not exhaustive, but meaningfully additive.

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 (list) and resource (decisions) and describes the return shape: 'what was decided, by whom and why, and the questions still open,' ordered newest first. An agent can distinguish this listing tool from fenbs_get_decision and the other fenbs_list_* siblings without opening a schema.

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

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

Gives explicit when-to-use conditions: 'Search before changing anything that looks deliberate, before recording a new rule (one may already cover it), and before asking a question that may already be answered.' These are concrete preconditions tied to other operations, going well beyond a generic 'use this to list'.

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=true, idempotent=false, readOnly=false; the description adds real context beyond them: writes require task-change permission, references are permanent and board-local, and it warns that account stores only where a credential lives, never the credential itself. It does not cover rate limits or reversibility of deletes, keeping it below a 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?

It is front-loaded (purpose, then scenarios, then action semantics, then cross-tool notes) and every sentence carries information, with no filler. It is dense and em-dash heavy, reading as a long single block rather than tight scannable lines, which keeps it from a 5.

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 21-parameter CRUD tool with no output schema, it covers actions, lifecycle status, permissions, and cross-tool behavior (due items surfacing in fenbs_get_context). It stops short of describing the shape of list/get results, which an agent might still need, so a 4 is appropriate.

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 62%, so the description must compensate partly, and it does by mapping actions to parameters (list -> project, kind, status, dueWithinDays, q; get/update/delete -> id) and clarifying ref-vs-id usage. It adds meaning beyond the schema for action-to-param routing, though it leaves some params (linkType, targetUrl, whatIsListed) to the schema.

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

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

The opening states a specific resource and scope: 'every place this work is listed or linked' with concrete categories (MCP directories, backlinks, app stores, profiles, domains). It is clearly distinguishable from sibling resources like items, decisions, and lessons, though it never names a sibling or explicitly contrasts with one, so it falls short of a 5.

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 maps concrete situations to actions: publishing a version -> list then follow howToUpdate, submitting somewhere -> add, checking a backlink -> update lastCheckedOn. That is clear when-to-use context, but there is no 'when not to use' or named alternative tool, so it is a strong 4 rather than 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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful domain semantics (the item/task naming convention and what resolution "built" means), but the schema already states "built means done, not live yet," so the added value is thin and no return-shape, ordering, or pagination behavior is disclosed.

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

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

Three short sentences with the core purpose front-loaded, followed by the filter surface and one clarifying semantic note. Nothing is wasted and nothing is buried.

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 9 parameters, 4 enums, no output schema, and no stated defaults (e.g., what an unfiltered call returns, whether results are summarized or paginated), the description is adequate but leaves real gaps. The annotations cover safety, but behavior for the many optional filters is only partially addressed.

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 89%, so the schema already carries parameter meaning, and the description only restates the filterable fields (lane, kind, project, category, resolution, free text) without adding syntax, defaults, or combinability rules. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ("List tasks on a board") and pre-empts the item/task terminology mismatch that would otherwise confuse an agent reading sibling names like fenbs_get_item and fenbs_create_item. It does not explicitly name an alternative tool, so it stops short of full sibling differentiation.

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 filter list implies the tool's role (browse/filter a board's tasks), and the resolution note hints at a use case, but there is no explicit when-to-use guidance, no statement of when to prefer fenbs_search or fenbs_get_item, and no mention of the required board parameter or prerequisites.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds value beyond them by disclosing the 'newest first' ordering and cross-referencing fenbs_get_context and (via schema) fenbs_restore_lesson, though it does not discuss pagination or result size.

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

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

Front-loaded with the core purpose, then filtering options, with little waste. Minor awkwardness in 'read them before work like what they describe' slightly muddies the otherwise dense phrasing.

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 7-param, 0-required list tool with no output schema, the description covers purpose, ordering, cross-tool overlap, and the main filters. It is complete enough to invoke correctly, though it leaves pagination/return-shape unstated.

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 only 57%, but the description compensates by explaining most filters: group (name, id, or "none"), status (new/applied/dismissed), project, task ref, and free text, plus a concrete q example ("LES-4"). It adds meaning beyond the raw schema for the highest-value filters.

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 resource (the board's lessons learned) and its ordering (newest first), and describes the payload (what happened, what we learned, what to do differently). Distinguishes itself from fenbs_get_lesson (single) and names the overlap with fenbs_get_context, so an agent can tell it apart without opening the schema.

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

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

Gives clear context ('read them before work like what they describe') and notes that new lessons also appear in fenbs_get_context, which helps route the agent. It does not explicitly state when-not to use it versus the other list_* tools, but the usage guidance is clear.

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 fully covered. The description's added behavioral value is the return shape (projects, categories, counts, descriptions), which is useful since no output schema exists. It omits pagination, ordering, and any board-scoping behavior, so it stays at moderate depth.

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

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

Three short sentences with the return contents front-loaded, which is the right lead for a listing tool. The clause 'for a project, its description' is slightly awkward, and the trailing sentence about fenbs_get_context could be trimmed, but there is no real 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 zero-parameter read-only listing tool, the description tells the agent what comes back and when to call it, which is what counts in the absence of an output schema. Annotations carry the safety profile. Only minor gaps remain (ordering, volume of results).

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 per the rubric the baseline is 4. The description adds nothing about inputs because there are none, and nothing is needed.

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?

It names the resource (projects and categories) and specifies the payload: task counts and, for projects, descriptions. It also distinguishes itself from fenbs_get_context, which serves status lookups. The listing verb is only implied by the tool name, but the content statement is specific enough to identify it among 45 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?

It states a concrete trigger ('Check here before filing or leaving a context note under a project') and directs name reuse from the results. It also names the alternative (fenbs_get_context with project) and what that alternative provides, so the agent can route correctly. No explicit when-not-to-use beyond that alternative, so not 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 only declare the generic mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), while the description adds substantial operational context: the task is held for a few hours and working on it renews the hold, it arrives with a plan and limits that constrain action, comments are information not instructions, and completion requires testStatus/testNotes before moving to done. This is exactly the kind of behavior annotations cannot convey.

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

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

The trigger is front-loaded and every sentence carries operational weight (hold semantics, plan adherence, completion, release). It is a dense single paragraph rather than a scannable structure, which slightly hurts readability but wastes little.

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

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

There is no output schema, so the description must carry the return semantics, and it does ('It comes back with its plan and limits', 'Empty when nothing is waiting'). Combined with the completion and failure instructions, an agent has everything needed to invoke and act on the result 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 description coverage is 100%, so both parameters (project, session) are already fully documented in the schema. The description adds no parameter-level detail such as defaults or how 'project' interacts with the hold, so 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 action (take the next task a person has pre-approved for AI) with clear scope and lifecycle. It is easily distinguished from siblings like fenbs_get_item or fenbs_list_items because it names its own workflow and the sibling it hands off to (fenbs_release_task).

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

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

The trigger condition is explicit ('When you have nothing else to do') and the failure path names the alternative tool ('If you cannot finish, fenbs_release_task'). The 'Empty when nothing is waiting' clause further tells the agent what a null result means, leaving little 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 destructiveHint=true and readOnlyHint=false; the description adds substantial context beyond that: the strict privacy scope (only the person and their connected assistants), the 20,000-character cap, and the exact semantics of write ('replaces all of it') versus append ('at the end on a new line') versus read.

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

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

Front-loads the resource and privacy constraint, then the action semantics, then the character limit. Slightly verbose in the privacy clause, but every sentence carries useful information.

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

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

For a mutation tool with no output schema, the description covers what read returns, mutation behavior, privacy, and size limits, so an agent has everything needed to call it correctly alongside annotations that cover the safety profile.

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 50% and the enum values carry no schema descriptions, so the description does the work by defining what each action does and clarifying that 'text' is the whole new text for write versus the suffix for append — meaning beyond the schema's brief param note.

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 resource (the private scratch notepad of the person you work for) and the three concrete operations (read/write/append). It explicitly differentiates from siblings by saying decisions, rules, tasks and context notes belong in their own tools.

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 when-to-use ('scratchpad, not a record') and names the categories that belong elsewhere, which routes the agent away from the update_*/add_* siblings. It does not name specific alternative tool names, but the exclusion guidance is 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?

Goes well beyond the annotations (destructiveHint=true, readOnlyHint=false): it discloses that delete is soft and restore reuses the same ref, that refs are permanent and never reused, that writes require permission to change tasks, and that update touches only the fields given. This is exactly the kind of operational nuance annotations cannot carry.

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

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

Front-loads the purpose and definition before the action-by-action routing, and every sentence serves a function. It is dense for six actions but not padded; the prompt/skill definitions are justified given the ambiguity of the term 'prompt'.

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 all six actions, permission requirements for mutation, and return behavior (list returns summaries without bodies; get exposes body, notes, earlier versions) despite there being no output schema. For a 10-parameter multi-action tool this is complete enough to call correctly.

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

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

With 80% schema coverage the schema already documents most fields, but the description adds real meaning: kind defaults to prompt, '' clears notes/project, [] clears tags, and ref is required for get/update/delete/restore. Some of this overlaps the schema text, so it is not fully additive.

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 the resource precisely as the board's Skills and prompts library, then defines both terms so the agent knows the artifact class. The verb set (list/get/add/update/delete/restore) is explicit and the sibling names are all about unrelated artifacts (decisions, lessons, items), so this tool is easy to disambiguate.

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 clear when-to-use context ('save useful prompts here', 'check the library before writing a long prompt from scratch') and explicitly routes list-vs-get ('list returns summaries without bodies: call get with ref to read the body'). It does not state when NOT to use this tool or name non-overlapping alternatives, 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 only declare the generic mutation profile (readOnly=false, destructive=false, idempotent=false). The description adds real side-effect detail beyond them: the task is reassigned to the Next Up queue for someone else, and the reason is posted publicly on the task. It does not clarify whether the reason becomes a comment or a field, but the key consequences are disclosed.

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 action and its condition, then the consequences. No filler, nothing repeated from the schema.

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 annotations covering the safety profile and no output schema, the description covers the essential behavior (reassignment plus public reason). It leaves open whether the caller must be the current assignee and what the response returns, but nothing critical to 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 50%: 'why' is documented in the schema, while 'ref' is bare. The description reinforces that the reason travels with the task ('your reason is posted on it') but adds nothing about the 'ref' format or what a valid task reference looks like. Adequate, not compensating 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 (give back/release) and a precisely scoped resource (a pre-approved task you already took and cannot finish). The reverse workflow framing implicitly distinguishes it from the pickup sibling fenbs_next_approved_task, though no sibling is named explicitly.

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

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

The condition for use is clear: you took a pre-approved task and cannot finish it. The 'cannot finish' qualifier implies when-not to use it, but no alternative tool is named and no explicit exclusion is stated.

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 it is a non-read-only, non-destructive, non-idempotent mutation. The description adds real value beyond that: a uniqueness check that prevents accidental project merges, a cascade to all usages, and an explicit permission requirement. It stops short of saying what happens to the old name in history or how failures surface.

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, front-loaded with the core action and scope, followed by the collision guard and the permission requirement. Every sentence carries distinct information 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 two-parameter mutation with no output schema and full schema coverage, the description supplies the important behavioral facts (cascade scope, name-collision refusal, permission need). Minor gaps remain around what the return value or error looks like and how the rename interacts with existing references.

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

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

Schema coverage is 100%, and the schema already documents both parameters ('The new name.' / 'The current name.'). The description adds no format, length, or validation detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (rename) plus resource (project) and clarifies scope with 'everywhere it is used,' which signals a cascade update rather than a local edit. It does not, however, distinguish itself from the sibling fenbs_update_project, leaving the agent to infer which one to pick.

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 constraint set ('Refuses a name another project already has') and the prerequisite ('Needs permission to change tasks'), but there is no explicit statement of when to use this versus fenbs_update_project or fenbs_add_project. The agent gets guardrails but not 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 only give the generic write profile (readOnlyHint=false, idempotentHint=false). The description adds real behavioral context: emails are sent to every signer, state moves Awaiting sign-off -> Decided (and locked), and it 'Needs permission to change tasks'. That auth requirement and the locking behavior are valuable beyond the annotations. It omits error/partial-approval 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 purpose is front-loaded in the first sentence and every sentence carries information about workflow or constraints. The em-dash asides ('You can ask; you can never sign -- a sign-off is a person, signed in') are somewhat stylistic and partly overlap with the schema's 'Not AI assistants' note. Overall efficient with minor redundancy.

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

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

For a mutating, email-sending tool with no output schema, the description covers the state machine, permission need, and who signs. The notable gap is the unexplained 'ref' parameter, which an agent needs to supply but cannot disambiguate. Otherwise it is adequately complete.

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 50%: the signers array is documented in the schema, but 'ref' has no description anywhere. The description reinforces 'the complete list of signers, by email' and that signers cannot be AI assistants, but it never explains what 'ref' refers to. It adds marginal value over the schema rather than compensating for the undocumented ref.

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: 'Ask board members to formally sign a decision off'. An agent can immediately distinguish this sign-off request from siblings like fenbs_add_decision or fenbs_update_decision. It stops short of naming any sibling explicitly, so it lands at a clear-but-undifferentiated 4.

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 the workflow context ('Say what was decided first', 'it is Awaiting sign-off until all of them approve') so an agent understands this happens after a decision exists. However, it never states when NOT to use it versus update_decision or comment, nor any explicit alternative. Usage is implied rather than delineated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely new behavioral fact beyond the annotations — the required permission to change tasks — but it is terse and does not detail scope, reversibility, or failure modes.

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, front-loaded with the action, followed by the discovery hint and the permission note. No padding and nothing that fails to earn its place.

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

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

For a single-parameter restore tool with no output schema, the description covers the action, how to find a deleted target, and the permission requirement. It is nearly complete, missing only the ref format and any note on what the restored state contains.

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 one parameter with 0% schema description coverage, so the description must carry the load. Saying 'by ref' identifies the parameter's role, and the pointer to list_decisions implies where a ref comes from, but the expected format of the ref value is never specified.

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 ('Restore a deleted decision') and scopes it with 'by ref'. It is clearly distinguishable from sibling restore tools (restore_item, restore_lesson, restore_project) and from delete_decision/update_decision, all without opening a schema.

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

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

Tells the agent how to locate the target of a restore by naming fenbs_list_decisions with deleted: true, which is the precondition for using this tool. It gives clear context but no explicit 'do not use when...' exclusion, 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 cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds material context beyond them: exactly what is restored, that files are NOT restored and are permanently gone, and that permission to change tasks is required. This is the kind of disclosure that prevents surprise data loss.

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 tight sentences, front-loaded with the action and its scope; the files caveat and permission note each earn their place. The get_item aside is useful but slightly parenthetical rather than core, keeping it from a perfect 5.

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 output schema and one undocumented param, the description covers what changes, what is irrecoverably lost, and the authorization requirement. It does not describe the return value or failure modes, which is a minor gap given there is no output schema.

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 single 'ref' parameter is undocumented, so the description carries the burden. 'By ref' hints that it is a reference identifier distinct from the 'number' also mentioned, but no format or source for the ref is given. Baseline for a minimal one-param schema with no added 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?

Specific verb (restore) + resource (deleted task) plus the scope of what is recovered (number, comments, followers, links). The word 'task' implicitly separates it from the sibling restore_decision/restore_lesson/restore_project tools, so an agent can route without opening any schema.

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

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

Gives clear context for when this applies and even a diagnostic hook ('fenbs_get_item on a deleted ref says it is deleted') to confirm the target is deleted. It does not explicitly name the sibling restore tools as alternatives or state when not to use it, 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 idempotentHint=true and destructiveHint=false, so safety is covered structurally. The description adds a genuine behavioral fact beyond the annotations: the operation 'Needs permission to change tasks,' an authorization prerequisite the agent would otherwise not know.

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, purpose front-loaded, then the how-to-find-the-ref hint, then the permission caveat. No filler and nothing redundant with the annotations.

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

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

For a one-parameter restore tool with no output schema and annotations covering idempotency and safety, the description supplies purpose, input sourcing, and an auth requirement. It omits error/return behavior, but that is a minor gap given the annotation coverage.

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 single 'ref' parameter has no description, so the description carries the burden. It usefully explains that the ref identifies a deleted lesson exposed via list_lessons with deleted:true, but never states the ref's format or whether it is an id, slug, or key, leaving a real 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+resource ('Restore a deleted lesson') and names the identifying parameter ('by ref'). It is clearly separable from sibling restore_* tools, which target decisions, items, and projects rather than lessons.

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 concrete context for locating the input ('fenbs_list_lessons with deleted: true shows them'), which is exactly the guidance an agent needs before calling. It stops short of naming when-not to use it or the conditions under which restore fails, so it is clear but not exhaustive.

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

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

Goes well beyond the annotations: it discloses the cascading effect on tasks, the exact refusal condition with a resolution step, and an auth requirement (permission to change tasks) — none of which appear in the annotation block. The non-idempotent, non-destructive hints are consistent with the described 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?

Four short sentences, front-loaded with the action and cascade, followed by discovery, precondition, and auth. No filler and every clause carries operational meaning.

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

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

For a one-parameter mutation with no output schema, the description covers the cascade behavior, the refusal path, discovery via the list tool, and the permission requirement. Nothing needed to invoke it correctly is missing.

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

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

Only one parameter, and the schema already documents it at 100% coverage ('The deleted project, by name.'). The description's mention of name conflicts reinforces that the parameter is a name rather than an id, but adds no syntax or format detail. Baseline 3 applies when the schema carries the 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?

States a specific verb+resource (restore a deleted project) and immediately distinguishes itself from the sibling restore_* tools by describing the cascade: every task not moved elsewhere is restored too. An agent can tell this apart from fenbs_restore_item or fenbs_restore_decision without opening any schema.

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

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

Gives clear usage context (deleted projects surfaced by fenbs_list_projects), a pre-condition (refuses if a live project holds the name), and a remediation path (rename first). It stops short of naming fenbs_rename_project explicitly, leaving the agent to infer which sibling to reach for.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false. Description adds important behavioral context beyond annotations: 'fenbs keeps how to run it, never the code' (clarifies data storage boundary), 'References are permanent and board-local', 'Writes need permission to change tasks', 'Before deploying or testing something, list them and follow the matching one.' However, it doesn't explicitly warn about destructive delete actions or lack of idempotency.

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 a dense block of text with multiple concepts packed in. While informative, it lacks clear structure (no bullet points or headings) and front-loading is mixed — it starts with the resource definition but then jumps between usage, logging details, and action enumeration. Some sentences could be split or organized for better 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?

Given 22 parameters, no output schema, and 64% schema coverage, the description is largely complete for an agent to use the tool correctly. It covers usage scenarios, logging behavior, permission requirements, and parameter semantics. However, it doesn't explain what each action returns (e.g., list vs get output) or how get_run/list_runs results are structured, leaving some gaps for an agent consuming results.

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 64%, so description must compensate. It does: explains actions (list, get, add, update, delete, log_run, get_run, list_runs) and their parameters, describes how measures work (names, comparison with last run), explains ref/id interchangeability, and specifies list_runs paging with take and beforeId. This adds substantial meaning beyond the schema's parameter 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 resource (routine processes: checks, scripts and procedures work depends on) and enumerates its fields (howToRun, checks, ruleRefs, everyDays), giving a clear picture of what the tool manages. It distinguishes itself from siblings by naming fenbs_groups and fenbs_get_context as related tools. However, it doesn't concisely distinguish from all 40+ siblings in one sentence, slightly reducing clarity.

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

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

Explicitly states when to use: 'Before deploying or testing something, list them and follow the matching one.' Also provides post-run logging guidance with detailed instructions for log_run, including result values and measure naming. Names alternatives (fenbs_groups) and cross-references (fenbs_get_context).

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

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

Annotations declare readOnly=false, idempotent=true, destructive=false, but the description adds real behavioral detail beyond them: whereItStands is overwritten yet the old text is retained and viewable via fenbs_get_item, secrets must never be stored, and changing tasks requires permission. These are non-obvious safety and mutability semantics an agent needs.

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

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

Front-loaded with the purpose and triggers, then elaborates the write semantics. Mostly earns its length, though the single dense paragraph is somewhat rambling and could be tightened.

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 10-parameter, zero-required mutation tool with no output schema, the description supplies triggers, overwrite/history behavior, permission needs, and the secret warning. The only real gap is not explaining the return payload, since it instead points to fenbs_get_context.

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 ten parameters thoroughly. The description weaves some of them into a workflow narrative (doneSteps, project) but adds little syntax or format meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('Save progress -- the hand off') and details exactly what it writes in one call (task state, steps ticked, project status). It also names sibling tools (fenbs_get_item, fenbs_get_context) so an agent can distinguish this writer from the readers it feeds.

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 triggers: before stopping, when the person says 'save progress' or 'hand off', or before a window is cleared. Clear context for use, though it doesn't contrast against alternative save/update siblings like fenbs_update_item.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial non-obvious behavior: the full ranking algorithm, result capping at 25/100, the { entityType: 'more', total, shown } sentinel row, and the entityType/ref/href shape of non-task rows. These are things the agent could not infer from structured fields and directly affect how it interprets results.

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 nearly every clause carries information, but the ranking enumeration is a dense run-on that takes effort to parse. It is appropriately sized for the complexity, just not maximally scannable.

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

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

With no output schema, the description takes on the burden of explaining return shape and does so: ranked ordering, truncation behavior, the sentinel 'more' row, and per-entity row fields. Nothing an agent needs to interpret or page through results 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 67%, and the description compensates well: it explains that q words must all appear, that limit caps at 100 with a 25 default, and that full switches from summary rows to the matching record. This adds real meaning beyond the schema, though the q matching semantics (AND across words) are only implied rather than stated crisply.

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 first sentence gives a specific verb (Search) plus the full resource scope (tasks, routines, links and runs across every board you can see), which cleanly separates it from sibling listers like fenbs_list_items or fenbs_get_item. An agent can identify the tool's role without opening the schema.

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

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

It gives actionable usage guidance ('narrow q rather than raising limit', 'Exact RTN/LNK/RUN queries stay in their namespace'), which steers the agent away from bad calls. It stops short of explicitly naming sibling alternatives (e.g., when to prefer list_items or get_item), so it is clear context rather than full when/when-not 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 readOnlyHint=false, destructiveHint=false and idempotentHint=true, so safety and repeatability are covered by structured data. The description adds real context beyond that — partial-update semantics (only passed fields change), an audit trail (recorded in History under your name), and a permission requirement (permission to change tasks) — but it does not contradict anything and the annotations already carry the core behavioral profile.

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

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

Front-loads the key decision (update instead of duplicate) before identification and mechanics. Five short sentences, each carrying distinct information — identification, partial-update semantics, audit, permission — with no repetition of the schema.

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 output schema, the description covers what changes (only passed fields), how to target the record (id or exact title), the ambiguity case (handled in schema), the audit trail, and the permission prerequisite. An agent has everything needed 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?

Schema description coverage is 100%, so every parameter (id, match, body, title, project, category) is already documented in the schema, making 3 the baseline. The description contributes one meaningful extra: the partial-update contract that unspecified fields are preserved, which is not obvious from the schema alone.

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

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

States a specific verb and resource (change a context note) and immediately scopes it to notes that are out of date. It also distinguishes itself from the sibling fenbs_add_context_note by explaining that updating is preferable to adding a contradicting note, so an agent can pick between the two without opening a schema.

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

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

Explicitly states the condition for use (the note is out of date) and the alternative it replaces (adding another contradictory note). It also routes the agent to fenbs_list_context_notes when an id is needed, so both the when and the how-to-find-the-target are covered.

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

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

Adds substantial context beyond the annotations: only passed fields change, the prior version is retained whole, deciders is a full replacement while linkTasks/unlinkTasks are additive, and the call requires permission to change tasks. These are exactly the behavioral traits the readOnly/idempotent/destructive hints cannot convey.

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

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

Front-loads the core action, then layers the constraint, the replace-vs-add distinction, and the alternative in tight sentences. Every sentence carries operational information; nothing 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 16-parameter mutation tool with no output schema, the description covers the critical behaviors an agent must know to call it safely. It omits any notion of the return value or confirmation behavior, a minor gap given the annotations already signal idempotency and non-destructiveness.

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

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

With 75% schema description coverage the schema already documents most params, but the description adds non-obvious semantics the schema does not: deciders replaces the whole list, linkTasks/unlinkTasks add and remove without disturbing others, and supersedes is the sanctioned path instead of rewriting. It does not touch the remaining params, so not 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 specific verb+resource ('Change a decision by ref') immediately, and the scope (field-level partial update, version history preserved) distinguishes it from fenbs_add_decision and fenbs_delete_decision among its siblings.

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

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

Explicitly routes the agent away from this tool for a substantive change to a decided decision ('record a new one with supersedes rather than rewriting history'), and states the hard precondition that a ref alone is refused. No inference needed.

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 (idempotentHint=true, destructiveHint=false), it discloses permission requirements ("needs permission to move tasks", "permission to edit tasks"), preservation semantics for replaced content ("it replaces the old one, which is kept"), the archived lifecycle (only Completed tasks, ref and history retained, still searchable), and claim-release behavior for release/takeover. Nothing here contradicts 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, but the rest is a single unstructured block that jumps between unrelated fields with no grouping, which hurts scanability for a 26-parameter tool. Several sentences duplicate schema descriptions that already carry 88% coverage (resolution, testStatus, size, whereItStands), so not every sentence earns its place.

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

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

For a 26-parameter mutation tool with no output schema, it covers the critical gaps: permissions, defaults, replace-vs-merge behavior for plan/steps/links, and cross-tool routing for bulk operations. Error behavior (an unknown ref, a permission denial) is never described, and the output contract is left to the annotations, which is a minor gap given no output schema exists.

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 defaults and intent the schema does not: "Leaving resolution out when moving to done still defaults to shipped", "xl means split it", and the relatesTo/unrelate merge-vs-replace distinction. Much of the remaining text (resolution, testNotes, testStatus, archived) restates schema descriptions, so it is additive rather than transformative.

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 "Change a task by ref. Only the fields passed change." states a specific verb (change), resource (task, identified by ref) and the partial-update semantics that distinguish it from fenbs_create_item and fenbs_delete_item. Sibling differentiation is present but scattered rather than stated up front (fenbs_save_progress for multiple tasks, fenbs_archive_completed for bulk archiving).

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 conditional guidance for individual fields (when to pass release, takeover, archived, doneSteps vs steps) and names alternatives explicitly: "To save several tasks at once, use fenbs_save_progress" and "To tidy the whole Completed lane, use fenbs_archive_completed." It never states when *not* to call this tool overall (e.g., use create_item for new work), so it stops short of full when/when-not 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 non-readOnly, idempotent, non-destructive. The description adds meaningful behavior beyond that: partial update semantics ("Only the fields passed change"), prior-version retention ("the version before is kept whole"), and an authorization requirement ("Needs permission to change tasks"). This is solid added context, though the return shape is unstated.

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?

It is dense but front-loaded, with the core update semantics stated first and per-field behavior following. Every sentence carries operational detail, though the field-by-field clauses make it slightly crowded.

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 13 parameters, no output schema, and 62% schema coverage, the description covers the tricky behavioral aspects (partial update, versioning, group clearing, status transitions, permission needs). Remaining gaps are minor since the schema itself documents most individual fields.

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 62%, so the schema documents most params but leaves gaps. The description reinforces group/groupId precedence and status/link behavior, but says nothing about title, lesson, project, category, whatHappened, or doDifferently. It adds some meaning but does not fully compensate for the coverage gap, so 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?

The description opens with a specific verb+resource ("Change a lesson by ref"), clearly identifying it as a partial-update operation on a lesson. It partially differentiates from siblings by noting that the 'applied' state is reached only via fenbs_apply_lesson, but it does not otherwise distinguish itself from update_item/update_decision. Clear but sibling differentiation is only partial.

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 explains field-level semantics well (groupId 0 clears the group, dismissed vs new status, linkTasks/unlinkTasks). However, it gives no guidance on when to use this tool versus add_lesson, delete_lesson, or restore_lesson, so overall tool-selection guidance is only implied.

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

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

Annotations already declare the mutation/idempotency/destructive profile, yet the description adds real value beyond them: partial-update semantics ('Only the fields passed change'), that '' clears a field, that the prior version is retained (recoverability), and the permission requirement. It doesn't describe error behavior or response shape, keeping it at 4.

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 dense paragraph, front-loaded with the mutation verb and the field list before the behavioral caveats and cross-reference. The parenthetical field explanations are justified, though the sentence is long enough to be slightly harder to scan.

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 5-param mutation tool with no output schema and annotations covering safety, the description supplies field meanings, clearing semantics, versioning, permission, and a viewing alternative, which is nearly everything needed. It omits failure/validation behavior, so not a 5.

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 20%, so the description must carry the load and largely does, glossing each of status, whereWeLeftOff, description, and aiContext. It also documents the empty-string clearing convention, a semantic not present in the schema; only the required 'project' param is left unglossed (self-evident).

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 ('Change') and resource ('a project's'), then enumerates the exact mutable fields (description, status, whereWeLeftOff, aiContext). This distinguishes it cleanly from siblings like fenbs_rename_project and fenbs_update_item without opening either schema.

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

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

Gives clear context for when to use it (editing project fields) and explicitly points to fenbs_get_context as the read counterpart, plus states the permission prerequisite. It stops short of exclusions, e.g. it never says 'to rename the project use fenbs_rename_project', so a sibling-routing gap remains.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioral value beyond that: it is a permission-discovery call whose result determines what subsequent calls are permitted. It doesn't describe the return shape or whether it's cacheable.

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, zero waste, with the identity question leading and the call-ordering directive second. The rhetorical-question opening is slightly less direct than a declarative statement but still front-loads the purpose effectively.

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, annotation-rich read tool with no output schema, the description supplies the essentials: what it returns (identity, per-board role) and when to invoke it. It is complete enough to call correctly; only the concrete return shape is left unspecified, which is acceptable given no output schema exists.

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 are zero parameters, so per the rubric the baseline is 4. The description correctly implies no input is needed and doesn't invent parameters that the empty schema doesn't define.

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 clear, specific purpose: returning the caller's identity and their role on each board. It's unambiguous and distinguishable from sibling tools (no other sibling answers 'who am I'), though it doesn't explicitly differentiate from e.g. fenbs_groups or fenbs_list_boards.

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 sequencing guidance ('Call this first') and the reason ('it tells you what you are allowed to do before you try'), which is stronger than generic context. It doesn't name alternatives or exclusions, but none are meaningfully needed for a zero-argument self-lookup.

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