agentic-task-system

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

The description discloses the write operation via the 'WRITE/LOCAL' prefix and explains error handling for unknown IDs ('reported without failing known acknowledgements'). With no annotations provided, this adds meaningful behavioral context, though idempotency and other side effects are not mentioned.

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 sentence plus a tag, conveying essential information without waste. It is front-loaded with the operation type and scope ('WRITE/LOCAL'). Every part is informative.

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 tool with one parameter and no output schema or annotations, the description covers the action, effect, and error handling. However, it lacks details on idempotency, return value, and typical usage scenario, leaving minor 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?

The input schema has 0% description coverage for parameters. The description adds that eventIds are 'durable task-event ids' and that acknowledgment removes them from the pending spool, but does not elaborate on format, origin, or validation rules beyond the schema's type and constraints.

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

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

The description clearly states the action ('acknowledges'), the resource ('durable task-event ids'), and the effect ('removes them from the pending spool'). It distinguishes from siblings like list_pending_task_events and poll_task_events by focusing on acknowledgment and removal.

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 explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, typical workflow (e.g., after processing events), or exclusion criteria. The context is entirely implied.

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

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

With no annotations, the description carries the full behavioral burden. It usefully declares this as a WRITE operation, explains forward/dangling-link behavior, and connects to `resolve_task_links`. However, it does not disclose duplicate-link behavior, whether links are bidirectional, failure behavior when `allowMissing` is false, or any side effects beyond creating the link.

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 three tight sentences, front-loads the write action, and adds substantive context about forward links and resolution. Every sentence earns its place; there is no filler or redundancy.

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

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

For a mutating tool with 8 parameters, 5 required, no output schema, and no annotations, this description is not complete enough. It leaves open important operational questions such as duplicate links, missing-target behavior when `allowMissing` is false, and what a successful response looks like.

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 25%, so the description needed to compensate for the undocumented parameters. It clarifies `allowMissing` forward-link semantics but does not explain the relationship between `sourceProjectId`/`sourceTaskId` and `targetProjectId`/`targetTaskId`, nor does it elaborate on the `type` enum values beyond a general grouping.

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?

Clearly identifies a write operation that adds a typed relationship from one task to another, and summarizes the kinds of relationship types supported. It does not explicitly distinguish itself from similarly named siblings like `relate_task` or `add_task_reference`, but the core action and resource are clear.

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

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

The description gives a specific conditional use case for `allowMissing` and points to `resolve_task_links`, but it does not explain when to choose this tool instead of sibling relation/reference tools. No exclusions, alternatives, or when-not-to-use guidance are provided.

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?

Since no annotations are provided, the description carries the behavioral burden. It leads with 'WRITE' to signal a mutating operation and describes the idempotent-ish behavior of re-adding the same URL. It does not mention permissions or reversibility, but it clearly states what will happen on repeated calls, which is the most operationally relevant behavioral detail.

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

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

The description is three short sentences and front-loads the most important behavioral signal ('WRITE'). It wastes no words: action, resource, destination, usage boundaries, and update behavior are all present. The structure is easy to scan and understand.

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

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

For a 6-parameter write tool with no output schema, the description is sufficient to select and invoke it correctly. It explains what the tool does, when to use it, which sibling should be used instead, and what happens on duplicate URLs. The remaining details, such as exact return payload, are not necessary 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?

The schema has 0% property description coverage, so the description must compensate. It does clarify the meaning of url and implicitly explains title and desc by describing what gets updated on duplicate URLs. However, projectId, taskId, and agent are left to inference, leaving some parameter semantics under-specified.

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

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

The description identifies the exact action with the verb 'adds' and specifies the resource being added: an external URL or reference note. It also names the destination ('References' section) and explicitly differentiates the tool from the sibling add_task_link, making the purpose immediately distinguishable from nearby tools.

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

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

It gives an explicit usage rule: 'Use this for links and supporting notes; use add_task_link for relationships to other active tasks.' The description also calls out the duplicate-url behavior, which is important invocation guidance. An agent can confidently choose between this tool and add_task_link without opening the schema.

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

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

With no annotations, the description carries full behavioral disclosure, and it provides meaningful details: it appends an audit record, denial wins over allowance, high-risk actions require approval, and it fails closed on audit failure. It stops short of fully describing the return status or auth model, so not 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?

Three tight sentences deliver a surprising amount of crucial behavior: side effect, decision logic, approval requirements, and fail-closed behavior. There is no filler or redundant restating of the schema.

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

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

The description is robust on side effects and policy behavior, but without an output schema it omits the return value and approval flow details. It also fails to clarify the 'approvals' input and how 'requires approval' manifests in the response, leaving a material gap for a decision 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 the burden is on the description to explain parameters. The description only names action, resource, and reason, and only vaguely references the approvals parameter. Agent, projectId, taskId, and approvals array semantics are left unexplained, which is a significant gap for a 7-parameter tool.

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?

Clearly states it evaluates a task-scoped access request and appends an allow or deny record, so an agent can see this is an audit/write action despite the 'check' name. The WRITE/AUDIT prefix and the specific resource ('task-scoped access request') separate it from read-only sibling tools like get_task_security.

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 when to use it: when a task-scoped access request needs evaluation and auditing. It states required inputs and approval conditions, but it does not explicitly say when not to use it or name any alternatives, leaving sibling differentiation to inference.

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

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

With no annotations provided, the description carries the full burden and does a good job: it explicitly warns 'Read-only', discloses the ordering behavior, states that invalid lifecycle items are excluded, and promises provenance on every item. It still omits potential error conditions or result format, so minor gaps remain.

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

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

The description is short and highly structured: it opens with read-only, states the resource and action, then lists ordered behaviors. Every sentence carries unique information and there is no redundant or filler phrasing.

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

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

The description captures the core behavior and result items are explained well enough at a high level, but there is no return format, no mention of how the optional limit applies, and no note of error or edge cases. Given no output schema and no annotations, the agent is left to guess important operational details.

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

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

The schema has 0% description coverage and the description does not explain projectId, taskId, or limit further. Although the parameter names are self-evident, the description mentions nothing about how limit interacts with the retrieval or candidate generation, so it does not compensate for the low schema coverage.

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

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

The description states a clear action, 'Builds execution context for a task,' with concrete processing details: typed relationships first, retrieval candidates, invalid lifecycle exclusion, and provenance. It is sufficiently distinct from simple getters like get_task or graph tools like task_graph, though it does not name a sibling explicitly.

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

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

The description implies when to use it — whenever execution context for a task is needed before acting — and the read-only tag suggests safe use. However, it gives no explicit guidance on when not to use it or which sibling to prefer for simpler cases like a single task read, so the guidance remains mostly inferred.

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

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

No annotations are provided, so the description bears the full behavioral transparency burden. It clearly discloses that this is a WRITE operation, describes the immediate side effect (a new item appears in the task app), and states the return value, including the new id.

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

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

The description is front-loaded with the WRITE callout, then a compact definition, use case, side effect, return value, and sibling routing. Every sentence earns its place and there is no filler.

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

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

For a 6-parameter create tool with no annotations and no output schema, the description covers the purpose, the human-facing nature of the write, the immediate behavioral consequence, and a clear return guarantee. Schema covers parameters, so nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much parameter-level semantics beyond the schema, though it does imply the item model and reinforces the main purpose of title. With all parameters already documented well in the schema, additional detail is unnecessary.

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

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

The description states a specific verb and resource: creates a new item (task/note) in the store. It clearly frames the tool as the agent-to-human write side of a two-way bus and names update_task as the alternative for modifying existing items, which distinguishes it from 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 explicitly tells the agent when to use this tool, to hand the human a note, action, or reminder, and explicitly tells it to use update_task instead when changing an existing item. This is direct routing guidance between competing write tools.

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

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

No annotations are provided, so the description carries the full burden for safety and behavior, and it does so well by opening with 'Read-only' and specifying that it 'deterministically' checks a task and reports concrete invalid conditions. It could add details about output format or auth, but the read-only guarantee and the enumerable fault list add meaningful context beyond the name.

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 entire definition is a single dense sentence with the most decision-relevant attribute ('Read-only') first and a compact enumeration of checking criteria. Every phrase is informative, and there is no disconnected noise or repetition.

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

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

Given no output schema and no annotations, the description gives the core validation operation and the kinds of issues reported, but it does not specify whether the tool returns a list, boolean, or status object. It also does not define the semantics of maxDepth, leaving a gap for an agent making actual calls.

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 compensates almost none of that and fails to mention any parameter by name. maxDepth in particular has no explained semantics (traversal depth limit), while projectId and taskId remain only self-explanatory by their names.

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 focused verb ('checks') and a specific resource (whether a task still supports its parent objective) and enumerates concrete defect classes reported. It clearly distinguishes itself from hierarchy getters/mutators such as get_task_hierarchy or set_task_hierarchy.

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

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

There is no explicit guidance on when to use this tool versus alternatives or which sibling tools it complements or replaces. The wording 'checks whether' weakly implies a read-only validation role, but the description leaves the decision to the agent without any exclusions or context.

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

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

Annotations are absent, so the description carries the full burden — and it meets it by disclosing the read-only safety profile head-on ('Read-only: never writes'). It also reveals behavioral nuance beyond the schema: dual retrievers fused via RRF, dense+sparse hybrid behavior for embedding-capable adapters, and provenance attached to results. It stops short of edge behavior like how the fallback behaves when no adapters or the exact ranking output shape, which keeps it from 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?

Three sentences, front-loaded with the highest-value facts: read-only safety and search scope come first, and the RRF mechanics are compressed into a single sentence. The only waste is the closing 'never writes', which repeats the opening 'Read-only' — a small redundancy that costs a point.

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

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

For a tool with no output schema and no annotations, it covers the essentials: what gets searched, how ranking works, what comes back (provenance), and a pointer on interpreting the explain field tied to the RRF equation. It is missing only a bit of extra detail about result shape and edge behavior to be fully self-sufficient.

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 schema already documents limit, query, and explain semantics. The description adds no new parameter-level meaning beyond reaffirming query as free-text matched against titles and bodies. Baseline 3 is correct when the schema does the heavy lifting.

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

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

Opens with an explicit verb and resource: 'Search the task store by free-text QUERY'. The mechanism (adapter signals plus Core keyword retrieval fused via Reciprocal Rank Fusion) and the return (best-matching items with provenance) further pin down what it does. It also distinguishes itself from the nearest sibling by name (`similar`), so an agent can tell them apart without opening either schema.

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

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

Gives a concrete usage frame — 'Use this for "what do I have about X"' — that defines the intended query-by-topic scenario. It also states an explicit when-not: 'To find items like a KNOWN item instead, use `similar`.' That direct alternative routing leaves little to inference.

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

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

With no annotations present, the description carries the full burden and handles it well: it opens by declaring 'Read-only' and states both the success and failure modes ('Returns the single item object, or an error if not found'). Minor gaps remain, such as no mention of authentication prerequisites, rate limits, or a complete field list, but the essential behavioral safety traits are disclosed.

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

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

The description is three terse sentences with meaningful content in each: the read-only trait, the fetch action with returned fields, the usage sequencing, and the return/error behavior. It is appropriately front-loaded with 'Read-only' and 'Fetch one item'; the minor grammar issue ('give you the ids') is a slight polish defect but does not hurt clarity.

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

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

Given a small 2-parameter input with 100% schema coverage and no output schema, the description supplies enough — the inputs, the return type ('single item object'), the key fields (body, tags, due date), and the error case. It is nearly complete; only a fuller enumeration of the returned object shape would push it to a 5, which is not really required for an agent to call the tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents both parameters thoroughly, including where the ids come from ('from find results' and 'from find results or list_projects'). The main description does not add detail beyond the schema, so the baseline of 3 for high coverage 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 specific verb and resource: 'Fetch one item (task/note) by its project id + task id', and identifies the returned content (full markdown body, tags, due date). This clearly differentiates it from sibling read tools like get_task_hierarchy and get_task_security, and the mutation tools like update_task and set_task_lifecycle.

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

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

The description provides explicit sequencing guidance — 'Use after find/list_projects give you the ids' — positioning the tool in a specific workflow and separating it from the listing/search siblings. It does not enumerate exclusions for near-alternative reads such as context_for_task, task_graph, or similar, though the intent is fairly clear.

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

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

With no annotations present, the description carries the full burden. It explicitly declares a non-mutating behavior and states what data is returned: the item role and its explicit parent relationship. It does not detail error cases, but for a simple getter the core behavioral contract is disclosed.

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

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

The text is two concise sentences with the read-only qualifier front-loaded. It includes useful role vocabulary without filler, making every sentence earn its place.

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

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

For a simple two-parameter read-only tool, the description covers the return value and non-mutating nature well. However, with no output schema and no parameter guidance, the description alone is not fully complete; an agent must infer parameter semantics from names.

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

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

Schema description coverage is 0%, so the description was expected to compensate for the parameters, but it does not explain projectId or taskId. The parameter names are somewhat self-explanatory, yet the description adds no additional semantic detail about how they are used.

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 starts with 'Read-only' and uses a specific verb 'Returns the item role and its explicit parent relationship,' making the tool's purpose concrete. It also enumerates the possible roles, further disambiguating it from sibling tools like set_task_hierarchy.

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 'Read-only' qualifier signals this is for inspection rather than modification, but the description does not explicitly name alternatives such as set_task_hierarchy or evaluate_task_hierarchy. No when-to-use or when-not-to-use conditions are given.

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

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

With no annotations provided, the description carries the full behavioral burden. It clearly states Read-only and explains the unconfigured default, but it does not describe the exact output shape, how defaults appear in results, or any access or auth prerequisites.

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 only two sentences and contains no filler. Read-only is front-loaded, and the returned policy dimensions plus the key default behavior are stated efficiently.

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 two-parameter read-only getter with no output schema, the description covers what is returned, the main safety trait, and an important edge case. It is only slightly incomplete because it does not describe return formatting or parameter semantics explicitly.

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 0% description coverage and the description does not explain the meaning or constraints of projectId and taskId. Their names are somewhat self-evident, but the description adds nothing about scoping, formats, or relationship to the security policy.

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 operation and resource: it returns the security policy for one task. The Read-only qualifier and the enumerated policy dimensions make it easy to distinguish from siblings like set_task_security and check_task_access.

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 does not say when to use this tool versus alternatives such as set_task_security, check_task_access, or get_task. The default-behavior note is useful but does not help an agent choose between related security tools.

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

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

The description declares the tool is read-only, a key behavioral trait. However, lacking annotations, it does not elaborate on other behaviors such as sorting, pagination, or performance implications of filters.

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 concise sentence, front-loaded with 'Read-only', containing no unnecessary words.

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

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

Given six parameters, no output schema, and minimal annotations, the description lacks information about return format, pagination, and other behaviors, making it insufficient for a comprehensive understanding.

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 0% schema description coverage, the description partially compensates by naming four filters (task, agent, action, advancement) that map to parameters, but omits projectId and limit and provides no type or format details.

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 clearly states the tool is 'Read-only' and lists 'action-ledger records' with optional filters. It distinguishes itself from sibling tools like 'record_action' which is a write 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?

The description mentions optional filters, implying usage contexts, but does not explicitly state when to use this tool versus alternatives like event listers or when not to use it.

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

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

With no annotations, description carries full burden. Explicitly states 'Read-only' and notes that task bodies are not stored, providing key behavioral context. Lacks mention of ordering or pagination 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 sentences, zero waste. Front-loaded with 'Read-only' and immediately states purpose. Every sentence adds value.

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?

Adequate for a simple list tool with one optional parameter and no output schema. Covers basic behavior but omits details like return format, ordering, or pagination semantics.

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 has one optional parameter 'limit' with type/constraints, but description gives no explanation of its purpose or effect. 0% schema description coverage, and description does not compensate.

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?

Description clearly states verb 'lists', resource 'durable task-event envelopes', and condition 'not acknowledged'. Distinguishes from siblings like acknowledge_task_events and poll_task_events.

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 explicit guidance on when to use this tool vs. alternatives. Does not mention scenarios where this should be preferred over similar tools like poll_task_events.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It explicitly states the operation is read-only and describes the return shape as an array of { id, name }. That is meaningful beyond the scalar value of the 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?

The description is three short sentences, each adding distinct value: read-only disclosure, the listing scope and output shape, and when to invoke it. There is no fluff or repetition.

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

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

For a parameterless list tool, the description is complete: it says what it returns, that it is read-only, and how to use it first to obtain a projectId. No hidden behavior or missing necessary context remains.

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

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

The tool has zero parameters, so the 100% schema coverage baseline is 4. The description need not document parameter behavior, and it appropriately offers no invented parameter details.

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

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

The description states a specific action (list projects/folders) and clearly specifies what each result contains (id and name). It is not a tautology and it identifies the tool's distinct purpose within the sibling set, since no other sibling is a project listing tool.

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

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

The description gives explicit usage context: call this first to discover a projectId needed for get_task, create_task, or update_task. It does not name a direct alternative tool or explicitly say when not to use it, but this is a discovery-first listing tool, so the guidance is sufficient.

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?

Since annotations are absent, the description does the full work of telling the agent this is a read operation, and it does say 'Read-only.' It also clarifies that the tool surfaces URLs and reference notes, not entire tasks. Missing behavior includes how unknown task or project IDs are handled, whether returned links are resolved or raw, and what exactly the response structure looks like—no output schema backs it up.

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 gets the job done in one sentence. 'Read-only' is front-loaded, the exact target location ('## References' section) is included, and it has no filler.

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

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

For the simplicity of this tool—two string IDs, no nested objects, no output schema—the description is nearly complete. It tells the agent what the tool reads, what is visible, and that it has no side effects. The remaining gap is that the parameter semantics are not explained anywhere, which is relevant, but the overall calling context is straightforward.

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 no description for either projectId or taskId, and the tool description adds nothing about them. 'Read-only' and 'a task's References section' only hints at taskId; projectId is never even loosely explained. Because schema coverage is 0%, the description should compensate for this gap and does not.

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 clearly states a specific verb ('lists') and a precise resource: a task's 'References' section. It also distinguishes the tool from mutation siblings by identifying it as 'Read-only' and describing the exact data returned (external URLs and reference notes). It does not explicitly separate itself from get_task or context_for_task, which might overlap for an agent, so it's not a perfect 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 description implies when to use the tool: when an agent needs the references attached to a task. The 'Read-only' label helps avoid using it for mutation. However, it does not mention alternatives such as add_task_reference, remove_task_reference, or get_task, nor does it state conditions for when not to use it.

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

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

Description clearly labels as WRITE/LOCAL, describes side effects (durably stages, advances checkpoint), and declares observation-only nature. With no annotations, this adequately covers behavioral traits.

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

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

Three sentences, front-loaded with operation type, no wasted words. Each sentence adds distinct value.

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

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

Given simplicity (1 non-required param, no output schema), description covers purpose, behavior, and usage. Could briefly explain what 'deterministic event envelopes' are, but overall adequate.

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?

Single parameter has schema description (coverage 100%), so baseline is 3. Tool description does not add any further meaning beyond the schema.

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

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

Description uses specific verbs (diffs, stages, advances) and mentions return type. It hints at distinction from siblings (e.g., unacknowledged pending spool) but could explicitly differentiate from acknowledge/list/snapshot tools.

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

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

States events are observation-only and must be acted on separately, implying usage pattern. But does not explicitly state when to use this tool vs siblings like acknowledge_task_events or list_pending_task_events.

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

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

With no annotations provided, the description carries the full burden, and it provides useful behavioral specifics: it is a WRITE operation, the source body is not copied, and the new item receives explicit outcome/completion metadata plus an evidence link back to the source. It does not cover permissions, reversibility, or side effects on the source, but it goes beyond a generic 'promote exploration' statement.

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

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

The description is short and front-loaded with a 'WRITE.' signal, then a one-sentence statement of purpose and behavior. It is efficient and readable, although some additional essential context needed for a 18-parameter tool is absent. As structure alone, it is good.

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 tool with 18 parameters, no output schema, no annotations, and 0% schema coverage leaves the description as the only guide. Two sentences do not explain which IDs are required, how 'sourceProjectId' and 'targetProjectId' relate, what 'kind' selects, or how the evidence link is represented. The description is far from sufficient to invoke the tool correctly.

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

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

Schema description coverage is 0%, and there are 18 parameters including 5 required ones. The description only hints at 'outcome/completion metadata' and an 'evidence link', which vaguely relates to outcome, doneWhen, and source/target IDs, but it does not explain the meaning or relationships of the parameters. This falls far short of compensating for the complete lack of schema descriptions.

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

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

The description uses a clear verb ('creates') and resource ('committed execution item') and explains the source ('exploratory material'). It distinguishes the operation from plain create_task by emphasizing that the source body is not copied and that the new item carries outcome/completion metadata and an evidence link. It does not explicitly name a sibling alternate, but the semantics are clear enough to differentiate.

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 the intended use case: converting exploratory work into a committed execution item. However, it does not explicitly state when to prefer this over create_task or related lifecycle tools, and it offers no exclusions or alternative conditions. This is only slightly above no 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?

No annotations are provided, so the description carries full burden. It discloses that the tool performs a write operation ('appends'), is auditable, and includes specific fields. However, it lacks details on idempotency, error handling, concurrency, or persistence guarantees.

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 sentence that front-loads 'WRITE' and conveys all key information without any extra words. It is efficient and easy to parse.

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 write tool with no output schema, the description provides a high-level purpose but lacks details on return value, error conditions, or typical usage patterns. It is adequate but not comprehensive.

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

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

Schema coverage is 0%, meaning parameters are not described in the schema beyond names. The description mentions fields like sources, approvals, output, and advanced, adding some context. But it does not explain formats, constraints, or the relationship between required and optional parameters.

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

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

The description starts with 'WRITE' indicating the action type. It clearly states the tool appends an auditable agent action or outcome to a local ATS JSONL ledger, listing included fields (sources, approvals, output, advanced). This distinguishes it from sibling tools like list_actions (read) or poll_task_events (poll).

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 for recording actions but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives or prerequisites. Sibling tools are listed but not compared.

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?

There are no annotations, so the description carries the burden of explaining behavior. It clearly discloses that this is a mutating operation, that a completed task is refused, and that the return value is routedTo: 'related' | 'references'. It does not document side effects or failure behavior in detail, but it is meaningfully transparent for a small 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?

Three short sentences with no filler. The core behavior is front-loaded, the usage guidance is placed centrally, and the return value is stated at the end. Every sentence provides usable information.

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

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

The description explains routing logic and the return value, but with seven parameters, four required, and no schema descriptions, a tool's wording is not enough. Important invocation details like project/task ID semantics and what type values mean are left out.

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%, but the description does not compensate for the parameters. It does not explain sourceProjectId, sourceTaskId, targetProjectId, targetTaskId, desc, or agent, and only contributes indirect meaning to type ('typed link', related). An agent cannot confidently map the required IDs or description field from the text 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?

The description states a specific behavior: auto-routing a relevant target into the appropriate section based on whether it is an active task, a note, or a completed task. It clearly differentiates from manual sibling tools like add_task_link and add_task_reference by emphasizing that no section choice is needed. The 'WRITE.' prefix also makes the action direction clear.

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

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

It explicitly says to 'Prefer this when you just know a target is relevant and do not want to choose the section yourself,' which gives a concrete trigger condition. It does not explicitly name alternative tools or list when not to use it, but the context makes the intent understandable.

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

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

With no annotations, the description carries the behavioral burden, and it does so well: it explicitly warns 'WRITE', clarifies exact-match semantics, and documents the idempotent no-op result ('Returns removed=false when the relationship was already absent'). It could go further on permissions or side effects, but the core behavior is clearly disclosed.

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

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

The description is compact and informative, with the WRITE warning and core action up front, followed by one valuable edge-case note about the return value. There is no redundancy or 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 tool with six parameters, no annotations, and no output schema, the description is adequate but not fully complete. It explains the operation and one return case, but does not describe the success return path, error behavior for nonexistent tasks, or authorization expectations.

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

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

The schema has 0% description coverage, so the description must compensate conceptually. 'Exact typed relationship' and 'source task' map meaningfully to the sourceTask/sourceProject/type fields, but they do not clarify all parameters individually, especially the optional 'agent' parameter.

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

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

The description pairs a specific verb ('removes') with a specific resource ('one exact typed relationship') and distinguishes this from bulk or fuzzy link operations. The 'exact typed' qualifier also separates it from sibling tools like resolve_task_links or add_task_link.

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 intended use is implied: call this tool when you want to remove a single, exactly matched task relationship. However, the description does not explicitly name alternatives or state when this tool should be preferred over related sibling tools such as add_task_link or remove_task_reference.

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

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

With no annotations, the description carries the full behavioral burden. It labels the call as a WRITE and discloses the key idempotency behavior: removed=false when the URL is absent. It doesn't mention authorization, errors, or exact return object shape, but the essential behavior is transparent.

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

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

Every sentence earns its place: the first names the operation, the second handles idempotency. The WRITE marker is useful and front-loaded, making the tool's general kind immediately clear.

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 small, idempotent mutating call, this is nearly complete: it states the action, the affected data, and one important return-value boundary. There is no output schema, so this last point matters greatly; the description adequately conveys the outcome. The only clear gap is unspecified semantics for the optional agent parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It only clarifies the url parameter (the reference to remove) and indirectly taskId, but does not explain projectId or the optional agent parameter. These remain ambiguous, making the description insufficient as parameter documentation.

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

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

The description names a specific verb, resource, and action: removes a reference by URL from a task's '## References' section. This clearly distinguishes it from sibling tools like add_task_reference, list_task_references, and especially remove_task_link, which deals with links rather than references.

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 use case is implied: when a reference by URL should be removed from a task's References section. There is no explicit when-to-use vs alternatives, but the clear operation and direct mapping to add_task_reference make it inferable.

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?

The description is transparent that the tool is 'read-mostly' and writes 'only if a title changed', and it discloses the result format: which links resolved vs which are still missing. Since no annotations exist, the description carries the full burden, and it covers the most important side effects. It omits permissions and concurrency behavior, but this is sufficient for a read-dominant, conditionally writing 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?

The description is compact and front-loaded with the most important mental model ('Read-mostly'). Each sentence adds a distinct piece of information: the operation, the return value, and the write condition. There is no filler or repeated schema information.

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

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

For a simple three-parameter tool with no output schema and no annotations, the description covers the action, the condition under which writes occur, and the returned information about resolved vs missing links. The only notable gap is the meaning of the 'agent' parameter, which prevents perfect completeness, but a caller can generally infer the needed inputs from the task context.

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

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

The input schema has zero description coverage, and the tool description provides no guidance on any of the three parameters. projectId and taskId are inferable from their names in a task context, but 'agent' is undefined and the relationship among them is not explained. The description does not compensate for the low schema coverage.

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

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

The description states a specific operation (back-resolving a task's forward links) and precisely explains what is done: refreshing placeholder titles to real titles. The phrase 'for each stored link whose target now exists' and 'returns which links resolved and which are still missing' clearly differentiates this from siblings like add_task_link or remove_task_link.

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 clearly implies when to use this tool: when a task's forward links may point to targets that have since been created and placeholder titles need to be become real titles. It does not explicitly exclude alternatives or name substitute tools, but the write condition and resolution behavior provide enough context to select this over link-structure tools.

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

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

There are no annotations, so the description carries the full disclosure burden. The 'WRITE' prefix and 'replaces or clears' do convey the core mutation behavior and the domain of the hierarchy 'single explicit parent'. However, it omits permissions/security implications (despite set_task_security siblings), reversibility/undo behavior, and what happens to existing children when the parent is cleared. It adds meaningful context, but a mutation of this surface area needs more behavioral disclosure.

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

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

A single sentence with an upfront 'WRITE' marker and a dense but exact statement of both behaviors. Every word earns its place — the role enum values are compressed, the parent operation is encoded as 'replaces or clears', and there is no repetition of schema field names or annotation data. It is short yet complete at the level it attempts.

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

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

Given high complexity, 7 nullable parameters, 2 required IDs, no annotations, no output schema, and a request with 31 overlapping siblings, the description is not complete enough. It never addresses what taskId and projectId mean together, how parentTaskId differs from parentProjectId, why agent exists, or what happens when both parent and clearParent are set. Agents are forced to reason about the required-value semantics and error surface entirely on their own.

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

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

Schema description coverage is 0%, so the description must compensate and partially does: 'exploration/goal/project/task role' directly maps the kind enum, and 'replaces or clears' maps to parentTaskId, parentProjectId, and clearParent. It does not clarify the semantics of the two required fields taskId and projectId (how they coexist), the meaning of agent, or the precedence between clearParent and a supplied parentTaskId. Meaningful value added beyond the schema, but several parameter relations stay unresolved.

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

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

The description uses a specific verb ('Assigns'), names a clear resource (the hierarchy role: exploration/goal/project/task), and adds the distinct parent relationship semantic of 'replaces or clears'. The WRITE prefix and focus on a 'single explicit parent' distinguish it from read siblings like get_task_hierarchy and from relationship tools like relate_task or add_task_link, though it does not name those siblings explicitly. Not a 5 because it never states what it does NOT do or names the overlapping set_* tools it competes with.

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 context ('assigns a role', 'optionally replaces or clears the parent') but provides no when-to-use/when-not-to-use guidance and no alternatives. With 31 siblings including promote_exploration, relate_task, add_task_link, and set_task_lifecycle, an agent receives no explicit routing away from those overlapping tools. The usage context is inferable but never stated, landing at 'no guidance' rather than 'implied usage'.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It states "WRITE," indicates mutation, says the tool adds or updates, and notes that it preserves the human-authored body. However, it does not disclose whether the operation is idempotent, whether it merges or replaces existing intent, or any authorization or side-effect implications.

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

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

The description is compact and front-loaded with the "WRITE" signal, a direct verb phrase, a concise inline enumeration, and valuable trailing context about portability and ATS compatibility. No filler is present.

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

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

For a 9-parameter mutating tool with no annotations or output schema, the description gives a helpful broad overview but does not fully explain update semantics, the meaning of the agent parameter, or return behavior. It is above minimal but leaves real 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?

Schema description coverage is 0%, so the description must compensate. It maps several listed intent concepts to likely parameters such as outcome, why, doneWhen, authority, constraints, and approvalRequired, but it does not explain agent, projectId, or taskId. This is useful but incomplete for a 9-parameter tool with no schema descriptions.

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

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

The description identifies a clear verb and resource: it adds or updates portable execution intent in the task body, and enumerates the intent fields. It does not explicitly distinguish itself from siblings like set_task_lifecycle or update_task, but the scope is specific enough to be recognized.

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 explicit guidance is given about when to use this tool versus alternatives. It does not mention conditions for use, exclusions, or a preferred workflow, leaving the agent to infer context from the description 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?

With no annotations, the description carries the behavioral disclosure burden. It does state 'WRITE' and discloses an important behavior: archived, expired, future, and superseded tasks are excluded by context assembly. However, it does not say whether changes are reversible, how validFrom/validUntil interact with status, or what happens to existing lifecycle state.

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 short and front-loads the mutation nature with 'WRITE.' Both sentences earn their place with meaningful behavioral information. It is concise but somewhat cryptic, especially the term 'portable lifecycle state.'

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?

The tool has six parameters, no annotations, no output schema, and zero schema-description coverage. A single high-level sentence is insufficient for reliable invocation: it leaves uncertain how validFrom/validUntil should be formatted, what status is acceptable, and whether this should be preferred over update_task.

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

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

Schema description coverage is 0%, so the description must compensate. It only broadly maps to status and validity windows, but does not explain date formats, required-status rules, the semantics of optional fields, or how 'agent' relates to the write operation.

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

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

The description uses a specific verb ('set') and resource ('portable lifecycle state and validity windows'), which clearly distinguishes it from set_task_intent and set_task_hierarchy. It could be more concrete about exactly what 'portable lifecycle state' means, so it stops short of perfect clarity.

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

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

The intended use is implied: call this when setting lifecycle state or validity windows. The description does not explicitly compare against update_task or set_task_intent, and it provides no when-not-to-use guidance 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?

There are no annotations, so the description carries the full burden. The description labels the operation as WRITE and clarifies that the policy is not a sandbox, but it does not disclose side effects, whether existing security settings are overwritten, permission requirements, or what happens to the policy once set. These are important behavioral gaps for a mutation tool without annotation support.

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

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

The description is two short sentences, front-loads the operation kind ('WRITE'), and each sentence adds substantively distinct information. There is no filler, repetition of the tool name, or redundant restating of schema properties.

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?

The tool has 9 parameters, no output schema, no annotations, and a sparse description. An agent cannot tell what response format to expect, how the policy is applied, how approval arrays interact with other fields, or what the 'decision point' semantics mean for a client. The description is not enough to confidently and correctly invoke such a specialized security 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 schema has 0% description coverage, and the description mentions none of the nine parameters. It only gives high-level context about a security policy and adds no meaning for required fields like projectId and taskId or important arrays like allowedActions and deniedResources. The agent is left entirely to infer the semantics of the parameter names without additional intent or example.

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 'WRITE' and explicitly states it 'Sets a portable task security policy,' providing a clear verb and resource. It further differentiates this tool from similarly named siblings by explaining that the policy is 'a decision point for cooperating clients' and not a sandbox for external tools. This is enough for an agent to distinguish it from set_task_lifecycle, set_task_intent, and get_task_security.

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

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

The description gives clear context about when this tool is relevant by stating the policy is for cooperating clients and explicitly says it does not sandbox unrelated external tools. However, it does not name an alternative tool or spell out when to choose a sibling like get_task_security or check_task_access, so it misses the highest bar for explicit when/when-not 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?

No annotations provided, so description carries full burden. It declares read-only, requires an embedder-backed adapter, describes error behavior, and specifies return format. Fully transparent.

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

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

Three sentences, front-loaded with purpose and read-only hint. Every sentence adds value: purpose, usage constraints, required adapter, error handling, return type. No waste.

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

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

For a tool with no output schema, it clearly states inputs, behavior, requirements, error cases, and output (array of items ranked by similarity). Complete and self-contained.

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% with descriptions for both parameters. Description adds critical context: 'from find results' for taskId, and default value and hard cap for limit. Adds value beyond 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?

Description clearly states 'Find items semantically similar to a KNOWN item' using verb+resource. It distinguishes from the sibling tool 'find' by explicitly stating 'not a text query — for text search use find'.

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 explicit use cases ('show me related notes', 'dedupe') and explicitly states when not to use it (for text queries) with a named alternative ('find').

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?

Despite no annotations, the description clearly states the tool 'only observes task state; it never launches an agent or performs an external action,' which directly addresses potential concerns about side effects. However, it does not mention if previous checkpoints are overwritten or if there are any performance impacts.

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 concise sentences front-load the key purpose and safety guarantee. No redundant words or irrelevant details.

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?

The description covers purpose and behavioral guarantees but does not mention what the tool returns (e.g., success confirmation or checkpoint ID). Given no output schema, this is a notable omission for completeness.

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?

Input schema has 100% coverage with a clear description of 'dueWithinHours' parameter. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states it 'creates or replaces the local corpus-diff event checkpoint,' which is a specific action. It contrasts with siblings like 'acknowledge_task_events' and 'poll_task_events' by emphasizing it only observes state and never launches agents or external 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?

No guidance on when to use this tool versus alternatives like 'poll_task_events' or 'list_pending_task_events'. The description includes 'WRITE/LOCAL' but does not explain scenarios where snapshotting is appropriate.

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

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

With no annotations supplied, the description carries the full disclosure burden. It explicitly states 'Read-only', describes the traversal direction, and reveals non-obvious outputs such as lifecycle validity and unresolved references. It omits depth behavior and error semantics, but the disclosed information is meaningful and accurate.

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 appropriately short and well structured: a one-word safety statement, then the core behavior, then the output summary. Every sentence contributes unique information and nothing is 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?

The description gives a solid high-level picture but is not fully complete for autonomous invocation. There is no output schema or annotation support, and the description does not cover depth semantics, project scoping, or how task_graph differs from the many related relationship/hierarchy tools. It is adequate but has clear 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?

Schema description coverage is 0%, so the description must compensate; it only indirectly hints at taskId via 'around one task'. It does not explain projectId, the meaning of depth, how depth interacts with traversal, or what each returned graph element represents. Thus the description fails to rescue the missing parameter semantics.

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

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

The description uses a specific verb ('traverses') and a clear resource ('typed incoming and outgoing task relationships around one task'). It also concretely names the outputs: nodes, edges, lifecycle validity, and unresolved references. This distinguishes it well from sibling mutating tools like set_task_lifecycle or update_task.

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

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

The read-only, graph-traversal wording implies use when inspecting task connectivity, but the description does not explicitly say when to use it, when not to use it, or how it relates to similar tools such as get_task_hierarchy or relate_task. The usage context is inferable, not 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?

With no annotations, the description carries the full burden and does a good job: it flags the write nature, explains the before-image mechanism, shows the side effect of recording an action.reverted entry, and offers dryRun preview. It could also mention failure cases like having no undoable write, but most key consequences are disclosed.

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

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

Four concise sentences, tightly packed with distinct facts. The WRITE marker is front-loaded, followed by behavior, invocation options, and side effects. No fluff or repetition.

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

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

For a tool with two optional parameters and no output schema, the description covers main behavior, selection of the write to undo, preview mode, and a side-effect. It doesn't describe the shape of the preview plan or behavior when no undoable write exists, but overall the agent has enough to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds real meaning beyond the schema by explaining the omission behavior for actionId and the purpose of dryRun. This is a meaningful contribution, though params are simple.

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?

Description states a specific behavior: "Reverses a recorded write" using the ledger's before-image, and gives concrete outcomes (restore updated task, delete created task). It is not a tautology and is distinct from related action-recording and action-listing tools.

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

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

The description clearly explains when to omit actionId, when to pass dryRun, and that actionId comes from list_actions. It does not explicitly mention when not to use it or name an alternative tool, but the guidance is sufficient for a focused undo operation.

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

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

With no annotations, the description carries the burden. It flags 'WRITE', discloses the side effect (item modified in the human's task app), explains partial-update behavior, and states the return value. It stops short of discussing idempotency or permissions, but the principal behavioral details are covered.

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

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

The description is short, front-loaded with 'WRITE', and each sentence adds one distinct point: purpose, side effect, prerequisites, return value, and alternative. There is no filler.

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

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

With 7 params fully documented in the schema and no output schema, the description supplies the missing return value. It also covers prerequisites and how to get required fields, so an agent has enough context to act safely.

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

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

Schema coverage is 100%, so each parameter already has a description. The description still adds cross-field semantics (only provided fields change, omitted fields stay untouched, required IDs come from find/list_projects), which enriches the meaning beyond the schema.

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

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

The description uses a specific verb ('patches') and clear resource ('existing item') and distinguishes itself from create_task. It explicitly clarifies partial-update semantics, so an agent cannot confuse this with creation or replacement.

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 names the alternative (create_task) explicitly for when-to-not-use and tells exactly how to obtain the required parameters ('find' or 'list_projects'). This gives clear when-to-use and when-not-to-use 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?

Despite no annotations, the description fully discloses behavioral traits: it is read-only, performs pure ID-to-URL construction without opening or writing, and returns a URL string. This transparency exceeds the burden for an unannotated 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?

The description is concise with three sentences, front-loading the key trait ('Read-only') and main action. There is no irrelevant information, and every sentence contributes meaning.

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

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

For a simple tool with two well-described parameters and no output schema, the description is complete. It explains the return value (URL as a string) and the source of input IDs, leaving no obvious 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?

The input schema provides 100% coverage with clear descriptions for both parameters ('Id of the project...' and 'Id of the item...'). The description adds minimal value beyond referencing sources ('from find/list_projects'), so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: building a paste-ready deep link to an item in its native app. It uses specific verbs ('Build', 'hand the human a clickable reference') and distinguishes from sibling tools that perform mutations (create_task, update_task) by emphasizing read-only behavior and URL construction.

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

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

The description provides clear context for when to use the tool ('when you want to give a human a clickable reference') and what it does not do ('does not open anything or write'). While it doesn't explicitly exclude alternatives or state when not to use, the guidance is sufficient for an agent to understand appropriate usage.

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