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

Annotations already declare readOnlyHint, openWorldHint=false and idempotentHint, so the safety profile is covered. The description adds real value beyond that: it discloses the local-model-vs-keyword fallback, the never-guesses/no-match contract, and that answers are quoted from matching records.

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?

Single dense paragraph that front-loads the core action and example before the read-only and fallback caveats. Every clause carries information; the parenthetical about local-model fallback is slightly awkward but not wasteful.

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

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

With no output schema, the description does the work of explaining the return payload (short quoted answer, ids, rules, handoff notes) and no-match behavior. Only the unexplained `limit` parameter and absent alternative-tool routing keep it from being 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 only 33% (only `project` is documented in the schema). The description covers `project` (optional, default all projects) but says nothing about `limit`, the one undocumented parameter, and adds no format guidance for `question`.

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 ('ask a question in plain words') and resource (FlowState), and describes the return shape (short quoted answer with type #id, plus rules and handoff notes). It's clearly distinguishable from data-listing siblings, but it never names the nearest alternative (e.g. `search`) to sharpen the distinction.

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

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

It gives an example question, states the default (all projects) and the no-match behavior, which implies natural-language lookup use. However it does not state when to prefer this over sibling tools like `search` or `get_context`, leaving the agent to infer the 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 declare destructiveHint=true and readOnlyHint=false, so the agent knows writes occur, but the description never discloses what an outcome write changes, whether it overwrites prior attempt state, or what parent_attempt_id relationships imply. It adds the project prerequisite, which is useful, but for a destructive multi-action tool with no consequences explained, disclosure is thin.

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

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

Two short sentences, front-loaded with the resource and the action list, so it is easy to scan and wastes no words. But the brevity is under-specification rather than efficient density, leaving the reader with almost nothing actionable for a 10-parameter tool.

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, two-action tool with 10 parameters, 20% schema coverage, and no output schema, the description is far too sparse. It should at minimum explain what each action writes, how outcome/confidence relate, and what the required project scoping implies. Key call-correctness information 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 only 20% (10 parameters), so the description must compensate, and it does not. It mentions the project requirement (already in the schema) but leaves action semantics, outcome values, confidence levels, attempt_id, problem_id, and parent_attempt_id unexplained. Most parameters are undocumented in both places.

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

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

The description names the resource ('solution attempts') and lists the two actions (log, outcome), which gives some shape to an otherwise opaque tool name. However, 'Manage' is a vague verb that does not say what logging or setting an outcome actually accomplishes, and it does not differentiate this from siblings like 'problem', 'verify', or 'log_work'. An agent knows the domain but not the concrete operation.

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

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

There is no guidance on when to use this tool versus alternatives such as 'problem', 'log_work', or 'verify', nor when to choose action='log' over action='outcome'. The only conditional given ('Write: requires project=...') is a prerequisite, not usage routing. The agent must infer the workflow 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 only declare readOnlyHint=false and destructiveHint=false; the description goes well beyond by stating it is additive (nothing moved, closed, or deleted), that approvals apply only one suggestion, are reversible via history, and that rejected suggestions are not re-surfaced. That is rich behavioral context an agent cannot get from 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 and the non-destructive guarantee are front-loaded, and every sentence carries information (write semantics, approval model, kind defaults). It is a dense single block, but there is little waste; tightening the parentheticals would help 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?

With no output schema, the description must convey outcomes, and it does — suggestions enter a review queue, user decisions are per-suggestion, and effects are undoable. It does not mention volume, pagination, or how many suggestions are produced, a minor gap for a generator 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 67%. The description adds value the schema lacks: the default that kinds covers all three values, and confirmation that project is required for the write even though the schema marks no required params. It leaves 'model' unaddressed, but that param is already documented in the schema.

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

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

States a specific verb and resource — find duplicates/stale/misfiled records and place them in the review queue as suggestions — and clearly distinguishes itself from siblings like review_list and review_approve. An agent can tell exactly what this produces 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?

Explains the workflow context well: this only generates suggestions, the user approves/rejects each, and rejected suggestions are not repeated. However, it never names the alternative tools (review_list, review_approve, todo) to route the agent, so it falls short of explicit when-vs-which guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds the write-prerequisite constraint, which is genuinely beyond the annotations. It says nothing about failure modes, duplicate handling, or what the call returns.

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

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

Two sentences, no filler, and the core action plus the blocking prerequisite are front-loaded. Every clause 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 6-param creation tool with no output schema, the description covers only the required-project constraint. It omits the nesting capability (parent_component_id) and gives no hint about what is returned, which matters for a create operation. Annotations cover safety, so it is serviceable but thin.

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%, so several params lean on the schema. The description clarifies the project/project_id either-or, which the schema does not express as an explicit alternative — a real addition. But it says nothing about the optional params (description, parent_component_id nesting, model), so it 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: 'Create a component within a project.' The action is unambiguous and separable from create_project, update_component. However, it never names a sibling or scopes itself against them, so it stops short of full 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?

Provides a concrete prerequisite ('requires project="<name>" (or project_id)') rather than pure inference. But there is no when-to-use vs when-not guidance, no mention of when to prefer update_component or list_components, and no condition under which creation should be avoided (e.g. duplicates).

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 openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that - no note that the name must be unique, what happens on a duplicate, or whether creation is idempotent.

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 filler, so it is efficient. It is arguably too sparse for a mutation tool, but it contains no wasted text.

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

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

For a simple 3-parameter tool with full schema coverage and annotations declaring the safety profile, the description is minimally sufficient. It omits any note about the uniqueness constraint's failure behavior or what state the new project starts in, which a creation tool would ideally cover.

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 name, model, and description, including that name is unique. The description adds no parameter meaning, which makes the baseline 3 appropriate.

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

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

States a specific verb (create) and resource (project), so an agent can distinguish it from list_projects and update_project by verb alone. However, it offers no explicit differentiation from the sibling create_component or any note about scope, keeping it just 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?

There is no guidance on when to create a project versus when to reuse or look one up via list_projects, and no prerequisites or exclusions stated. The agent must infer usage entirely from the name.

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 readOnlyHint=false and destructiveHint=true, so the mutation/removal risk is disclosed structurally. The description adds the non-obvious prerequisite that every write needs a project, but says nothing about whether 'remove' is irreversible, whether delete_file purges the underlying file, or about rate limits.

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

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

Two short sentences, front-loaded with the resource and action list; the write prerequisite is placed second. No wasted words, though the 'Write:' fragment is telegraphic rather than explanatory.

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

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

A 15-parameter, destructive, output-schema-less tool needs far more than this. The action-to-parameter mapping (which params matter for which action) is absent, so an agent cannot reliably invoke search vs. attach vs. remove without guessing.

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 13% across 15 parameters, so the description must compensate and largely fails to. It clarifies the project/project_id requirement but leaves tags, query, file_path, file_types, delete_file, copy_to_bundle, and attachment_id semantics entirely to the sparse 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 clear verb ('Manage') and resource ('file attachments') and enumerates the four actions (attach, list, remove, search), which maps directly to the action enum. An agent can tell this is the attachment-management tool, though it does not explicitly differentiate itself from siblings like 'link' or 'problem'.

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

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

Provides one conditional rule: 'Write: requires project="<name>" (or project_id)', which tells the agent a prerequisite for attach/remove. It does not say when to pick attach vs. search, nor name any alternative tool, so guidance is implied rather than explicit.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds a token-cost/efficiency tradeoff between lean modes, which is genuine behavioral context, but says nothing about scope limits, data freshness, or what the two modes actually return.

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 tightly written sentences with the core purpose front-loaded before the lean-mode guidance. Nothing is padded, though the second sentence spends its budget on parameter usage rather than on clarifying what 'context' contains.

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 should help the agent anticipate what comes back — and it never defines what 'project context' comprises or how lean changes the payload beyond token count. For a read tool with annotations covering safety and a fully documented schema, this is adequate but leaves the key ambiguity unresolved.

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

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

Schema description coverage is 100%, so all three parameters are already documented and baseline is 3. The description slightly enriches lean by tying each value to a use case ('minimal tokens at session start' / 'full details'), but adds nothing for hours or project_name beyond what the schema states.

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 clear verb and resource ('Get project context'), so the agent knows it retrieves something. But 'context' is undefined — it doesn't say whether that means learnings, recent changes, rules, or a summary — and no sibling is named or excluded, despite get_learnings, get_recent_changes, and list_projects sitting adjacent in the toolset.

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 says when to use lean=True ('at session start') versus lean=False ('when needed'), which is useful parameter-level guidance. However, it offers no tool-level guidance on when this tool is the right choice over the many other retrieval siblings, which is the more consequential decision.

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 openWorldHint=false, so the safety profile is covered structurally. The description adds the compact/token-saving behavior, a genuine operational note, but says nothing about return format, pagination, or result volume.

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

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

Two short sentences with zero padding; the core action is front-loaded and the token hint follows immediately. It is efficient but borders on under-specification rather than genuine 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?

With three parameters, no output schema, and no definition of what a "learning" actually is, the description leaves an agent unable to predict what it will receive or how category/project_id shape results. It is not complete enough for a 3-param retrieval 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%, so both category (8-value enum) and project_id are entirely undocumented in the schema. The description clarifies compact's effect but leaves the other two parameters with no semantic guidance, only partially 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?

"Get learnings" simply restates the tool name; it names no scope, no return shape, and does not distinguish this tool from siblings like log_learning, get_context, or search. There is a verb+resource pairing, but it carries no information beyond the identifier itself.

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 only guidance is "Use compact=True to save tokens," which is a parameter tip, not a when-to-use statement. Nothing says when to call this versus get_context, search, or log_learning, and no prerequisites or filters are explained.

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

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

Annotations declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, so safety and idempotency are covered. The description adds only that compact=True saves tokens, which is a minor operational hint. It omits what the changes represent, time window behavior, and output format.

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

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

Two short sentences with no wasted words. However, it is under-specified rather than concise, and the compact hint is placed without context.

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 four undocumented parameters, no output schema, and no description of what 'recent changes' entails, the definition is incomplete. An agent cannot confidently invoke this tool without guessing parameter meanings.

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

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

Schema description coverage is 0%, so parameters (hours, compact, project_id, component_id) are undocumented. The description only mentions compact's purpose, leaving hours, project_id, and component_id without any semantic explanation.

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 verb and resource (get recent changes), which is minimally clear. However, it does not distinguish this tool from siblings like history or get_context. It's vague on what 'changes' refers to (logs? code? memory?).

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

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

There is no guidance on when to use this tool versus alternatives such as history or get_context. The only usage hint is about compact mode, not about selecting the tool.

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 openWorldHint=true, but the description adds no behavioral context such as which actions mutate local state, which reach the network, or what sync/clone overwrite. It neither reinforces nor contradicts the safety profile, leaving the agent to infer risk per action.

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

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

Front-loaded and compact with no filler, so it reads quickly. But it is thin rather than efficient for a six-action tool with five undocumented parameters, straying into under-specification.

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 multiplexed, network-reaching, destructive-capable tool with five parameters at 0% coverage and no output schema, the description is inadequate. An agent cannot determine parameter applicability per action or the risk profile of individual actions from this text.

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

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

Schema description coverage is 0% and the description does not compensate: local_path, remote_url, commit_message, and limit are never explained, and it does not indicate which parameters apply to which action. It only restates the action enum, which the schema already provides.

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 (Git operations) and enumerates six actions, so an agent knows it's a multiplexed Git tool. However, it does not differentiate from siblings (notably a separate 'history' sibling tool that overlaps with the 'history' action here), and the action list merely mirrors the schema enum.

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 when-to-use guidance, prerequisites, or alternatives are given. It offers no help deciding between actions (e.g. sync vs set_remote vs clone) or between this tool and the sibling 'history' tool.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly carried by structured data. The description adds useful lifecycle context (a note appears first in start_here, pickup makes it stop showing, project is required for writes) but never explains what the destructive hint refers to, whether leaving a note overwrites anything, or any error/permission conditions.

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 opening sentence states the resource and the action=leave trigger is front-loaded before the continue/pickup path. It is dense and slightly parenthetical-heavy, but every sentence carries workflow information with little 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?

With no output schema, the description should describe what the read path returns, but it only labels action=list as '(read)' without return shape or pagination context. Combined with limit and include_picked_up being undocumented in both schema and description, the definition is adequate but leaves real gaps for a multi-action 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 63%, so the description must add meaning, and it does: it ties project to writes, where_i_was/next_step to leave, and handoff_id to pickup, giving each parameter a role relative to an action. It leaves limit, include_picked_up, and model unaddressed, which keeps it short of 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?

The description names the resource (handoff notes between AIs) and breaks the tool into three explicit actions (leave, list, pickup) with the semantics of each. It also cross-references the sibling start_here, where the note surfaces, so an agent can place this tool 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 concrete triggers per action: 'Stopping mid-task (out of time, context or tokens, or the user ends the chat)? action=leave' and 'When you continue from a note, action=pickup with handoff_id'. The read path (action=list) is also identified, leaving little to inference about when each mode applies.

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?

Well beyond the destructiveHint=true annotation, the description explains that undo is itself recorded ('undoing again redoes it'), that a deleted record is restored, and that the operation is refused when the record changed since the last read. These are exactly the behavioral traits an agent needs before attempting a destructive write.

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 content is dense and mostly earns its place, and the top-level purpose is front-loaded. But it is delivered as one long run-on block with inline 'action=' asides, hurting scannability for a 12-parameter, 3-action tool.

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

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

With no output schema and no annotations covering return shape, the description still sketches what comes back ('old and new values', 'newest first, across projects or one project', the app/model/machine fields). That is good coverage for a complex multi-action tool, though pagination behavior and the 'limit' parameter remain underexplained.

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 67% schema coverage, the description adds real meaning: it maps by_app/by_model/by_machine/since/until/page to the 'who' action and gives a concrete time syntax ('2026-10-17 or 2026-10-17 14:30'). It also ties record_type + record_id to single-record listing and states project is 'required for every write'. It leaves 'model' and 'limit' unexplained, which the schema partially covers.

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

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

The description names specific verbs and resources ('Edit history of FlowState records, and undo') and then breaks the tool into three named actions (list/undo/who), each with a distinct read or write purpose. It does not, however, distinguish itself from siblings like get_recent_changes or log_change, which an agent could plausibly confuse with the 'list' and 'who' actions.

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?

Each action is given a clear context ('action=list (read): recent edits and deletes in a project', 'action=undo (write; project required)'), and real exclusions are stated ('New records are not undone here (set them done/cancelled)', 'Refused if the record changed again since'). It never names alternative tools, so an agent has no explicit routing guidance among overlapping siblings.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false), the description discloses crucial behavior: content lands in a review queue and is not saved as a record until the user approves, and secret-like lines are skipped rather than stored. These are non-obvious safety traits an agent must know before calling.

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 its queue semantics, then format details, then the secrets caveat. It is dense and information-rich, though the parenthetical clauses stack up slightly, making it a bit packed rather than crisp.

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 write tool with no output schema, the description covers the key outcome (items become review entries pending approval) and the secret-skipping behavior. It does not describe the shape of the response or how many items may be produced, a minor gap given the absence of an 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 already 83%, and the description adds meaning: it explains what format=memory and format=flowstate_markdown each ingest, that 'text' should carry the file contents, and that project is required for every write. It adds real value over the enum lists but doesn't touch every parameter (e.g. model/source nuance).

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

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

The description opens with a specific verb and resource ('Bring memories or notes into a project's REVIEW QUEUE') and immediately clarifies the write semantics and that nothing is persisted until approval. This clearly distinguishes it from direct-write siblings like log_learning or create_component by routing content through a review queue.

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 the two format modes and when each applies (format=memory for Claude/ChatGPT exports vs format=flowstate_markdown for `flowstate export-md` files). However, it never explicitly names an alternative tool or states when NOT to use this import path versus logging directly.

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

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

Beyond the destructiveHint=true annotation, the description discloses a non-obvious side effect: changes on a shared component alert every linked project via an update todo plus a brief note. It also sets a clear boundary ('FlowState only alerts; it does not change other apps' code'). It stops short of describing reversibility of remove or permission 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?

It is front-loaded with purpose and an example, then proceeds by action and field, so nothing is wasted. It is a single dense paragraph that runs long, which slightly hurts scannability.

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

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

For a 15-parameter tool with no output schema, it covers the main add/remove/list workflows and the critical source/target/link_type semantics. It omits what list returns and a few minor flags (note, model, include_removed), leaving small gaps.

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 only 53% schema coverage, the description does heavy lifting: it explains source options (project, component, item_type+item_id), target options (target_project + target_component, target_type+target_id, or url) and enumerates link_type values with a GitHub/Linear url note. Some parameters (note, model, include_removed) remain unexplained.

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 (link) and resource (things across projects), then immediately scopes it: write for add/remove, project required. The worked example (two apps using one protocol) makes the cross-project linking use case unmistakable and distinguishes it from generic create/update 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 gives an explicit trigger: 'Use when projects share something, e.g. several apps use one protocol,' and enumerates the three actions (add/remove/list) with their flows. It lacks explicit when-not-to-use or named sibling alternatives, capping it below 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, and openWorldHint=false, so the safety profile is covered. The description adds only the project scoping and says nothing about ordering, pagination, result size, or whether it returns components across child projects.

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 a single front-loaded sentence with zero padding, which is good structurally. However, the brevity comes at the cost of under-specification rather than true conciseness, so it only meets the minimum bar.

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?

This is a simple one-parameter read tool, but there is no output schema and the description does not hint at what a listed component contains or how many are returned. For a listing tool the agent needs at least a sense of the return shape and ordering.

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 project_id parameter, so the schema carries no semantic detail. The phrase 'in a project' only weakly implies that project_id scopes the listing; no format, type, or behavior for that id is described.

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 clear verb+resource ('List components') plus a scope ('in a project'), which distinguishes it from create_component and update_component. It stops short of naming any sibling or delimiting what a 'component' is, so it is clear but not fully differentiating.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as search or get_context. The agent must infer usage purely from the tool name.

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 openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the small detail that status is returned with each project; it says nothing about pagination, result limits, or ordering, so it is adequate but not 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?

A single front-loaded sentence with zero padding. It is efficient, though for a tool with a filter parameter it is arguably too sparse rather than optimally sized.

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

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

For a simple read-only list tool with one fully documented enum parameter and annotations covering the safety profile, little is missing. There is no output schema, so the brief mention that status is included is a reasonable touch, though filtering behavior and pagination remain 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 description coverage is 100%, and the single status parameter is documented in the schema with an enum of active/paused/completed/archived. The description never mentions the filter, so it adds no meaning beyond the schema — the baseline 3 applies.

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

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

The description states a clear verb (List) and resource (projects), and adds a scope note about status. It does not differentiate from siblings such as list_components or get_context, but the resource is specific enough that an agent knows what it targets.

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

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

There is no guidance on when to use this tool versus alternatives, no mention of the status filter as a use case, and no prerequisites or exclusions. The agent must infer everything from the name alone.

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, so "Write" is partly redundant, but the description adds a genuinely useful constraint beyond the schema: project is effectively required for every write even though the schema marks only field_name as required. It says nothing about side effects, reversibility, or return behavior.

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

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

Two short sentences with the purpose front-loaded and no wasted words. The telegraphic "Write: requires..." fragment is slightly clipped but efficient.

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

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

For an 8-parameter mutation tool with no output schema and 38% schema coverage, the description covers only the project prerequisite. An agent still lacks guidance on the old/new value pairing, change_type enum usage, and what logging a change actually does.

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 38%, so the description must compensate. It usefully pins down the project parameter's requirement, which the schema understates, but says nothing about the other six undocumented parameters (new_value, old_value, reason, change_type, model, component_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?

States a specific verb+resource ("Log a change to a component") that an agent can distinguish from siblings like log_learning and log_work. It does not explicitly name those siblings or clarify the boundary, 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 gives a prerequisite ("Write: requires project=...") but no when-to-use vs when-not guidance and no routing among the many log_* siblings. Usage is implied rather than explained.

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 and destructiveHint=false, so the write-safe profile is covered. The description adds one genuine behavioral constraint not in annotations: writes require project=<name> or project_id. It says nothing about deduplication, validation failures, or what happens to learnings after capture.

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 the critical project requirement. 'This is your memory - use it!' is motivational filler but takes little space.

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

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

No output schema exists, and the description does not need to cover return values. But for an 8-parameter tool at 50% schema coverage with no annotation detail on mutation effects, the description leaves the classification parameters (category, source) and the model/component_id fields unexplained.

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

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

With 8 parameters and only 50% schema description coverage, the description compensates partially by clarifying the project/project_id requirement, which the schema's required array omits. However, it adds nothing for category, source, context, model, or component_id, leaving several parameters documented only by enum values or not at all.

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 combination ('Capture an insight or learning') that an agent can immediately map to a write operation. It does not explicitly name its read counterpart get_learnings, so sibling differentiation is left to inference.

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

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

'This is your memory - use it!' gives a soft nudge toward use but no when-not conditions and no comparison to alternatives like log_change or log_work. The prerequisite (project required for writes) is stated, which is the most actionable guidance present.

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

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

Annotations declare this is a non-readonly, non-destructive, non-open-world write (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description goes further by explaining the suggested=true review-queue behavior, the secret-detection refusal, and the default component for changes and problems. These are useful behavioral details beyond the annotations. It does not cover permissions or rate limits, but that is acceptable given the annotations already establish the write 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?

The description is a single dense paragraph but well-structured: it front-loads the core action and required parameter, then moves through the kind definitions, optional fields, and behavioral notes. Every sentence adds some information, though the density could make it harder to scan. It is appropriately sized for an 11-parameter tool.

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 burden of explaining return behavior, and it does so partially by describing the review-queue outcome for suggested=true. It also covers secret refusal and defaults, which are important edge cases. However, it does not clarify what happens on success (e.g., an ID is returned) or how errors are surfaced, leaving a small gap for a write 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?

The input schema has 91% description coverage, so the schema already documents most parameters thoroughly. The description adds some meaning by explaining the kinds and the default for component on changes and problems, but it largely repeats what the schema already provides. For example, it lists priority and source values that are already enums in the schema. The value-add over the schema is minimal.

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 'Record work as you go (write; project required)' — a specific verb and resource with a clear write scope. It enumerates the five kinds (decision, change, problem, learning, todo), which helps an agent understand the broad purpose. However, it does not explicitly distinguish itself from siblings like log_change, log_learning, or problem; an agent might wonder whether to use those specialized tools instead.

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 implies usage by listing kinds and optional fields, but offers no explicit when-to-use or when-not-to-use guidance. It never says whether this is the preferred entry point over the more specific siblings (log_change, log_learning, problem). The agent must infer that this is a general-purpose alternative, but the toolset’s structure suggests otherwise.

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 and destructiveHint=true, so the safety profile is covered. The description adds the write-prerequisite (project name/id) which is useful operational context, but it never warns that 'delete' is irreversible or that destructive behavior is confined to that action, leaving a gap between the blanket destructiveHint and the actual four-action 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?

Two short sentences, purpose front-loaded before the action list and the write prerequisite. The formatting is slightly run-on (the action list collides with the 'Write:' clause), but nothing is padded or redundant.

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

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

An 11-parameter, four-action dispatcher with no output schema and 18% schema coverage needs per-action parameter guidance and return-shape hints. The description supplies neither, so an agent cannot reliably tell which fields matter for which action.

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 18%, so the description carries the compensation burden and largely fails. It clarifies that 'project' accepts a name or id and is required for writes, but the other nine parameters (name, steps, category, method_id, project_id, description, code_example, related_component_id, model) are never explained, nor is it stated which parameters apply to which 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?

States a specific resource (project methods) and enumerates the supported verbs (create, list, update, delete), with a clarifying gloss of what a 'method' is (auth flows, deployment steps, patterns). It does not, however, distinguish this tool from siblings like create_component or rules, so an agent must infer the boundary.

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

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

It gives one concrete precondition for writes (project="<name>" or project_id) but never says when to choose this tool over the many sibling CRUD tools, nor which action fits which situation. Usage is implied by the action list rather than 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known, and the description adds only the write precondition. It does not say which action is destructive (solve? log?), what happens to existing data, what authorization is needed, or what the actions return. For a destructive multi-action tool this leaves substantial behavioral gaps.

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

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

Two short sentences with the action list front-loaded and no filler. Efficient, though brevity here borders on under-specification for a 14-parameter tool.

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, 14-parameter, four-action tool with 21% schema coverage and no output schema, the description is far too thin. It omits per-action parameter requirements and any behavioral context an agent would need to invoke log/solve 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 only 21% across 14 parameters, so the description carries the burden of compensation and fails to. It documents project (name or id) but says nothing about title, summary, severity, description, key_insight, code_snippet, problem_id, component_id, or winning_attempt_id – notably which parameters are required per action. The action enum is merely repeated from 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?

"Manage problems" is a plausible but vague verb+resource pairing, and the enumerated actions (log, list, solve, get_tree) largely restate the enum already present in the schema. It never distinguishes this tool from siblings like log_learning or todo, so an agent must infer scope. Adequate but with a clear differentiation gap.

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 only guidance is the write precondition ("requires project"), which is a prerequisite rather than a routing rule. There is no statement of when to use this tool versus log_learning/log_change/todo, and no exclusions or alternatives named. Usage is left entirely 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, but the description adds substantial behavioral context: the transformation into a normal record, the consent/precondition constraints, the 'never approve your own suggestions' rule, and the write-requires-project requirement. This is meaningful disclosure well beyond the annotation flags.

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, then constraints in compact sentences. Slightly dense with multiple conditional rules packed together, but each sentence carries necessary guidance rather than filler.

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

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

For a 10-param mutation tool with no output schema, the description covers the critical aspects an agent needs: consent preconditions, the write requirement, and edit-before-approve semantics. Minor gaps remain (no mention of move_to's misfiled-item cleanup purpose, no outcome confirmation), but it is largely 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 60%, and the description compensates by explaining that summary/details and priority/category/component act as edits applied before approval, and that user_request must quote the user's words. It adds real meaning over the schema, though move_to and model are left entirely to the schema.

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

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

States a specific verb (Approve) and resource (review item), plus the concrete outcome: the item 'becomes a normal FlowState record.' This clearly distinguishes it from the sibling review_reject, which the description implicitly contrasts by referencing approve/reject decisions.

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

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

It gives explicit when-to-use and when-NOT-to-use conditions: only call when the user has explicitly told the agent 'in this chat' to approve or reject that specific item, never self-initiate, never approve own suggestions. It also names the alternative path (edit-then-approve by passing corrected fields), leaving nothing 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 readOnlyHint, idempotentHint, and openWorldHint=false, so 'Read-only' mostly repeats structured data. The description does add real value beyond annotations by explaining what populates the queue and that disposition is a human decision, which shapes how the agent should behave after calling 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?

Three short sentences, front-loaded with purpose, then the read-only constraint, then the workflow expectation. No filler and nothing that should be moved earlier.

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, and the description usefully characterizes the returned items, so return-value burden is low. The one gap is that it frames the tool purely as 'waiting in the review queue' while status can also list approved/rejected/all records, leaving that capability unmentioned.

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% and the description adds no parameter meaning at all. 'limit' and 'status' carry no descriptions in either place, and the status enum's ability to return approved/rejected/all items is never mentioned, so the agent must infer filtering behavior 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 ('List items waiting in the review queue') and immediately clarifies the queue's contents (auto-captured session summaries, records logged with suggested=true). Together with the workflow note about approving/rejecting, an agent can distinguish this from siblings review_approve and review_reject 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?

'Show them to the user; approving or rejecting is the user's decision' gives clear behavioral context: this tool only surfaces items and routes the decision to the human/review_approve/review_reject. It lacks an explicit named alternative or when-not condition, so it falls 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 (readOnlyHint=false, destructiveHint=true), and the description adds real context beyond them: set requires an explicit user request in-chat, user_request must quote the user's words, and every change is logged with them. It also explains the project-override lifecycle (clear=true removes it). It does not spell out the full consequence of the destructive flag for future captures, but the effect on queueing is described.

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

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

Front-loaded purpose followed by mode semantics and then the safety directive, with no filler sentences. It is dense and slightly crammed with directives, but each clause carries distinct operational meaning for a policy tool.

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, no-output-schema tool the description covers the critical behaviors: mode meanings, override scoping, and the set precondition. It does not describe what action=get returns, which is a modest gap given no output schema exists, but nothing needed to invoke it 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 coverage is 71%, and the description extends it: it defines each mode value in prose (off/auto_only/types/everything), ties mode=types to the kinds list, and clarifies the project/clear override semantics versus the install-wide default. Only 'model' is left to the schema alone, a minor 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 pair (read/change) plus the resource (review mode) and immediately defines what it governs: which new records wait in the review queue. The get/set distinction is spelled out, so an agent can tell what each call 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?

Gives explicit conditions: action=get is read-only, action=set ONLY when the user has explicitly asked in this chat, and an explicit prohibition ('never change it on your own initiative or to get your writes saved'). This is a clear when/when-not rule, which is exactly what an agent needs for a policy-setting tool.

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

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

Annotations declare readOnlyHint=false, destructiveHint=true and openWorldHint=false, so the write/non-open nature is already known. The description adds real value beyond that: the item is retained, nothing is deleted, and a user-supplied reason is stored. It does not resolve the mild tension with destructiveHint=true (i.e., whether a rejection is later reversible), which keeps this 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?

Well front-loaded: purpose, then retention behavior, then the guardrail, then the write requirement. Slight redundancy in the repeated instruction about the user's words and the clause about not approving one's own suggestions, which belongs more naturally to the approve sibling.

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-parameter mutation with no output schema, the description covers the important gaps: what happens to the item, the authorization precondition, and the project requirement. It could say what happens on success or whether a rejection can be undone, but nothing essential 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 80%, so item_id, reason, model and project are largely documented already (baseline 3). The description reinforces two constraints that matter operationally: user_request must actually quote the user's words, and project="<name>" is mandatory for every write, which is stronger than the schema's generic "Required for every write" 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 verb and resource ("Reject a review item") and immediately defines the resulting semantics: the item is kept and marked rejected with the user's reason. Together with the sibling review_approve, an agent can tell exactly which of the two decision tools this is 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 states the trigger condition and the prohibition: call ONLY when the user has explicitly asked in this chat for a decision on this specific item, and never act on the agent's own initiative. The approve/reject decision context routes the agent appropriately and leaves nothing 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?

Adds real context beyond annotations: rules appear in full at the top of every start_here brief, are capped at 300 characters and 2,000 per project, and removal demands a verbatim user_request quote. It does not cover error behavior or what happens when the 2,000-rule cap is hit, so it falls 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?

Front-loads the definition of hard rules, then packs action semantics into tight parentheticals with zero filler. Dense but readable; the parenthetical action map is slightly cramped but every clause 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?

Covers all three action paths for a 7-param mixed read/write tool with no output schema, including the write prerequisites. Minor gaps remain around include_removed semantics and failure modes, but nothing that would misroute an invocation.

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 71% (above baseline 3), yet the description still clarifies rule_id ('R<id> in the brief'), constrains user_request to the user's own words, and ties project to writes. It adds value over the schema, though include_removed and model are left to 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 resource (a project's hard rules) with a concrete definition ('things never to do') and enumerates the three operations (list/add/remove) with verb-level clarity. An agent can distinguish this from siblings like start_here (which displays rules) or log_learning 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?

Explicit routing conditions are given per action: add 'when the user states a rule', remove 'ONLY when the user asks you in this chat', and list is marked read. This is as close to when/when-not guidance as a multi-action tool 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 readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description goes beyond them by disclosing the matching mechanism (word and word-ending matching, plus meaning-based matching that only works when a local model is installed) and by pointing to the reply's mode field as the ground truth for which path ran.

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, no padding, and the content-type scope is front-loaded before the matching mechanics. It is efficient, though the second sentence is a fairly dense clause stack.

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

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

With six parameters, 33% schema coverage and no output schema, the description is only moderately complete. It covers search semantics and the semantic-mode prerequisite, but leaves parameter behavior (limit, project_id, mode values) and the shape/ordering of returned results 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 project and content_types carry descriptions), so the description needs to compensate. It partially does by explaining keyword vs. meaning matching, which is what the undocumented mode enum controls, but it never names the mode parameter or its auto/keyword/meaning values, and limit, query and project_id remain unexplained in both places.

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 clear verb (Search) plus the exact resource universe (todos, decisions, changes, learnings, problems, solutions), so an agent can tell it is a cross-type finder rather than a writer. It does not, however, contrast itself with sibling retrieval tools such as get_learnings, get_recent_changes, or history, and the tool name alone ('search') is generic.

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: enumerating the six content types hints that this is the tool to reach for when you want to look across categories. There is no explicit when-to-use, no when-not-to-use, and no named alternative (e.g., 'prefer get_learnings for a known content type'), even though many siblings compete for the same intent.

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 and readOnlyHint=false, so the batch has write/destructive potential, but the description never says which of the seven actions are reads versus writes or destructive (e.g. does save_state overwrite existing state?). It adds only the project requirement, leaving the actual destructive behavior undisclosed despite the annotation flagging 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?

Three compact sentences: purpose first, then the action list, then the write constraint. The action enumeration is dense but earns its place as the only routing information provided; nothing is wasted, though there is no structure grouping read vs write actions.

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, 7-action dispatcher with no output schema and destructive potential, the description is far too thin. An agent cannot tell which actions mutate data, what each returns, or how the many optional parameters map to specific actions.

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 26% across 19 parameters, so the schema does most of nothing here and the description must compensate. It clarifies the project/project_id alternation for writes, but says nothing about skill vs skill_id vs skill_type, metric_type, promoted_only, effectiveness_score, or how the per-action parameter subsets work.

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 domain (learned skills and session state) and enumerates the seven concrete actions, so an agent can see what the tool covers. However, it never distinguishes this tool from close siblings like log_learning, get_learnings, rules, or session, which also deal with learnings and session state, leaving real boundary 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?

The only guidance is a prerequisite note ('Write: requires project=...'), which tells the agent how to call a write but not when to choose this tool over log_learning/get_learnings or which of the seven actions fits a given situation. There is no when-to-use, when-not-to-use, or alternative routing.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, so the agent knows some operations can destroy data. The description notes 'Write: requires project=...', adding a required precondition for mutations, but it doesn't specify which actions are destructive, what gets destroyed (e.g., ending a session deletes it?), or permission requirements. Given the tool bundles both read and write actions, the description could do much more to disclose which actions have which effects.

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

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

The description is very brief—two sentences—and front-loads the action list. However, the information is sparse and not well-structured for such a complex tool, and the write requirement is appended without explanation, making it feel terse rather than efficient.

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, only 15% schema coverage, no output schema, and no annotations beyond hints, the description is grossly incomplete. It doesn't explain what each action does, which parameters apply to which actions, what the tool returns, or what side effects occur. An agent cannot reliably invoke this tool based on the supplied information.

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 15%, so the description must compensate, but it only mentions the project parameter requirement for writes. Ten other parameters (limit, model, summary, outcomes, project_id, session_id, key_decisions, focus_problem_id, focus_component_id, user_prompt_summary, assistant_response_summary) are entirely undocumented in both the schema and the description, leaving the agent without essential knowledge about what they do or when they are 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?

The description states 'Manage sessions' and lists six actions, which conveys the general purpose but is vague. It doesn't distinguish this tool from siblings like start_here or handoff, which could also manage session-related workflows, and 'manage' is a generic verb that doesn't specify the tool's unique scope.

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 lists available actions but gives no guidance on when to use this tool versus alternatives, nor any conditions for choosing among the actions. Siblings such as start_here and handoff suggest overlapping functionality, yet the description doesn't clarify boundaries.

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/closed-world, but the description adds real behavioral context: the exact contents of the brief, the character budget, and the non-obvious side effect that it 'opens a FlowState session automatically'. The automatic session creation is a disclosed state change that sits in mild tension with readOnlyHint=true, though it is a bookkeeping effect rather than a data mutation.

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 imperative 'CALL THIS FIRST' and then the payload description. It loses a point for repeating the size values that the schema already documents (quick/standard/deep and the 4,000/12,000 limits appear in both places).

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 enumerates what the brief contains, its size cap, and the fallback behavior, which is everything an agent needs to call it correctly. Nothing material is left unspecified.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: project accepts a name or id, folder is matched to a project when project is omitted, and omitting all arguments returns the project list. These usage semantics are not derivable from the field descriptions 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 ('Returns a brief' with the project's hard rules, todos, problems, changes, decisions) and distinguishes itself from siblings like get_context and list_projects by declaring it is the entry point ('CALL THIS FIRST'). 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?

Explicit when-to-use ('in every conversation about a project') plus an explicit fallback path for the edge case: call with no arguments, or with folder, when the project is unknown. This is the rare definition that routes the agent through both the happy path and the failure path.

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, and the description adds a useful write prerequisite ('requires project="<name>" (or project_id)') plus priority alias behavior. However, it never explains what is destructive (no delete action is even listed), whether updates are reversible, or any rate limits, so it adds only modest context beyond the annotations.

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

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

The action list is front-loaded and the paragraph is dense with no filler sentences; every clause maps to a real parameter or behavior. It is somewhat run-on but appropriately sized for an 18-parameter dispatcher.

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 multi-action tool with 18 params and no output schema, the description covers the action set, write prerequisites, priority semantics, and list filtering well enough to call the tool correctly. The remaining gaps (status/compact/due_date semantics) are minor given the absence of an 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 description coverage is only 50%, so the description must carry more weight. It usefully explains parent_todo_id (subtask), the priority aliases ('older names high and medium also work'), and the project/project_id requirement, but leaves status, compact, model, component_id, and due_date undocumented in both places.

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 'Manage todos' and then enumerates the six concrete actions (add, update, list, next, block/unblock), each with a short gloss, so an agent can tell what the tool does. It does not differentiate from any sibling, but no sibling competes for the same todo-management role, so this is 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?

Each action gets operational context: 'next' is defined as 'open, unblocked, highest priority', block/unblock is explained via blocked_by/blocked_by_problem, and list filtering/sorting is spelled out. There is no explicit when-not guidance or pointer to alternative tools, so it falls 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 readOnlyHint=false and destructiveHint=true, so the destructive write nature is covered. The description restates 'Write' and the project requirement (which the schema also documents), adding little beyond what structured fields already convey, and omits what update destroys or how omitted fields are handled.

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

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

Two short fragments, front-loaded with the purpose. No filler, though the terseness leaves gaps it could have addressed.

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

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

A destructive 6-parameter write with 33% schema coverage and no output schema needs to explain mutation scope (partial update vs replace, what gets destroyed). The description is far too thin for that complexity.

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%, so the description should compensate, but it only mentions project. Six parameters (name, model, status, description, component_id) are undocumented by both schema and description, and it doesn't explain the status enum or that updates may be partial.

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 ('Update a component') that cleanly separates it from siblings like create_component and list_components based on the verb alone. It stops short of describing what fields can be modified, but the core operation is 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?

'Write: requires project="<name>" (or project_id)' implies this is a mutation needing project scope, which is real usage context. However, it gives no when-to-use vs alternatives and no exclusions; it reads more as a parameter prerequisite than routing guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds only the write-prerequisite, and despite the destructiveHint it never says what is destroyed or whether changes are reversible, leaving the important behavioral trait unexplained.

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

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

Two very tight sentences with the mutation nature and the identifier requirement front-loaded. It is efficient, though the terseness edges toward under-specification rather than pure 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?

For a destructive mutation tool with no output schema, low schema coverage, and 6 parameters, the description should explain what changes and what a write affects. It covers only the identifier prerequisite, leaving an agent without enough context to invoke it confidently.

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

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

Schema coverage is only 33% and the required array is empty, yet the description usefully asserts that 'project' (or project_id) is required for every write, partially compensating for the gap. It adds no meaning for name, status, model, or description, so half the parameters remain undocumented.

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

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

States a specific verb+resource ('Update project details'), which an agent can distinguish from create_project and list_projects in the sibling list. It doesn't explicitly name a sibling, so it stops 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?

The 'Write:' label signals this is the mutation path and gives a prerequisite (project name or id), which implies when to reach for it. However, it never contrasts with update_component, create_project, or any alternative, so usage is implied rather than 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 already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known without the description. The description adds one genuinely useful prerequisite (writes require project= or project_id), but it never says that delete is irreversible, what gets removed, or that list can run without a project. Useful but far from complete for a destructive mutation tool.

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

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

Two compact sentences, front-loaded with purpose before actions and prerequisites. Minor cosmetic flaw: the action list runs straight into 'Write:' with no separator, making the sentence boundary ambiguous.

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

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

A 10-parameter, destructive, multi-action CRUD tool with no output schema and 20% schema coverage demands far more detail than two sentences. The description omits how each action pairs with the params, what list returns, and the consequences of delete, leaving real gaps for correct invocation.

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 20%, so the description must carry the burden for 8 undocumented parameters. Instead it restates what the schema already says: the action enum values and the project requirement (already in the project property description). It leaves name, value, variable_id, is_secret, description, and category semantics unexplained.

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 ('Manage project variables') and names the concrete facets (servers, credentials, config) plus the full action set (create, list, update, delete). What it lacks is any differentiation from the many sibling project tools; nothing tells the agent why 'variable' rather than 'rules' or 'log_learning' applies.

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 action list and the 'Write: requires project=' prerequisite give implied guidance on how to invoke write operations. But there is no explicit when-to-use / when-not-to-use statement and no routing to alternatives among the 30+ siblings, so the agent must infer the scope.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true for the whole tool; the description usefully splits that into per-action read/write labels, which the annotations cannot express. However it never explains the destructive consequences (e.g., source overwriting a prior source, mark mutating a record), so the disclosed safety profile is thinner than the destructiveHint implies.

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?

Action-by-action ordering is well front-loaded and every clause carries information. The opening 'Keep facts current' is the only low-value sentence, and it costs 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?

For an 8-parameter, three-mode tool with no output schema, the description covers action semantics but omits what stale actually returns, the role of limit/model, and what happens to previously stored sources on overwrite. Adequate to invoke, incomplete for confident use.

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

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

Schema coverage is only 38%, so the description carries the burden, and it does: it binds record_type+record_id to mark, maps source to its three enum values, and ties project to writes. It still never explains 'limit' (default 20) or the 'model' parameter, leaving some 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 name 'verify' is generic, but the description compensates by decomposing the tool into three explicit modes (stale read, mark write, source write) with concrete resources (paths, ports, hosts, URLs, config). It also distinguishes itself from the sibling log_change by routing changed facts elsewhere.

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?

Each action states its condition: stale for facts untouched 60+ days, mark once you have confirmed a record still holds, source to record provenance. The closing line 'If a fact changed, log the change instead' is an explicit alternative-path rule, though no explicit 'when not to use' beyond that.

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