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

Annotations only declare the operation is non-read-only, non-idempotent and non-destructive; the description goes substantially further by disclosing the actual response contract (lean default, `full` opt-in) and the conditional `delivery` array with per-mention reach/skip reporting and `hint` suggestions. It stops short of permissions, threading behavior or failure modes, but adds real behavioral value beyond the structured fields.

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

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

Front-loaded with the one-line purpose, then dense, information-bearing detail about the response shape and mention-delivery semantics. No filler, though the closing sentence about omitting `delivery` when nobody is mentioned restates what the preceding sentence already implied.

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

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

With no output schema, the description correctly carries the burden of describing return values and does so well (lean vs full, delivery/hint). For a mutation tool with nested `metadata` semantics this is nearly complete; the gap is the absence of any comparison to comment_doc, which an agent choosing among 60+ siblings would want.

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's explanation of `full` largely restates what the schema description already says, and it never touches `metadata`, `is_internal` or `parent_comment_id` – the semantic load stays with 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?

Opens with a specific verb+resource: "Add a comment to a task." An agent can tell what it does. However, it never differentiates itself from sibling tools like comment_doc or list_comments, so the boundary of when this exact tool applies is left implicit.

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

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

Usage context is implied rather than stated: the discussion of @-mention delivery and the `hint` field tells the agent this is the tool for posting task comments that may notify people. There is no explicit when-to-use/when-not-to-use guidance and no mention of the alternatives (comment_doc, list_comments) that a sibling-aware agent would need.

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

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

Annotations declare only that this is a non-idempotent, non-destructive write. The description goes well beyond that: it explains the actual consequence (the dependent is held back from its assignee until the blocker meets the condition), what each condition releases on, that evidence_url releases an edge of any condition, and that responses carry `warning` and `condition_satisfied`. That is real context an agent could not derive from the annotations.

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

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

Four sentences, front-loaded with the direction and the default behavior, then the non-holding edge types, then the sibling routing. No restatement of the tool name and no filler; every clause either defines effect or dispatches the agent elsewhere.

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

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

No output schema exists, and the description still covers the effect of the write, the condition matrix, the evidence short-circuit, and the response fields that matter (`warning`, `condition_satisfied`). For a 5-parameter dependency mutation this is sufficient to invoke 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 the baseline is 3 and the schema already carries the heavy detail on conditions and evidence. The description adds the framing that 'blocks' is the type the condition applies to and that the two task IDs are direction-sensitive ('swapping the two makes the blocker wait instead'), which is meaningful beyond the schema's per-field notes.

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

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

Opens with a specific verb and resource plus the direction semantics: 'Add a dependency edge: task_id depends on depends_on_task_id.' It immediately distinguishes the edge types by effect (blocks holds back work; relates_to/is_child_of only record a link), so an agent can tell what it is creating without opening the schema.

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

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

Explicitly routes modification and deletion to update_dependency and remove_dependency, and explains the release condition per edge type so the agent can pick a type deliberately. It stops short of covering the creation-side alternatives — notably when to use an is_child_of edge versus the sibling create_subtask, and no guidance on cycles beyond the schema's 'must differ from task_id'.

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

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

Adds substantial context beyond the annotations: it explains the done-evidence gate that blocks move→done on a link left as 'open', and why no webhook can backfill a pre-existing merge. It also clarifies that re-calling with a status update corrects the existing link rather than failing, which is real behavioral detail for a write 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?

Front-loads the action, then the inference rule, then the status caveat, then the gate consequence — a sensible ordering with no filler. The final sentence is long and stacks two ideas (default 'open' and the done-gate), which slightly hurts scanability for a 19-parameter tool.

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

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

For a 19-parameter write tool with no output schema, the description covers the default path and the one high-risk case (linking an already-merged PR). The optional delivery-state parameters are left to the fully-documented schema, which is reasonable, though a one-line steer to mark_vcs_deployed for deploy/CI state would close the loop.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds meaning by stating that provider, link_type and external_id are inferred from the URL and only needed for unrecognised links, and by pinning down the exact meaning of status='merged'. It leaves the delivery-state family (ci_*, deployed_*, acceptance_*) entirely to the schema, which is acceptable given full 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?

Opens with a specific verb and resource ('Link a task to a pull request, commit, or branch') and then defines what the link semantically is (the task↔PR join that automation and reporting read). That distinguishes it from adjacent tools like mark_vcs_deployed, which handles deployment state rather than the link itself.

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

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

Gives clear operational guidance: only task_id and url are required, the rest is inferred from a GitHub/GitLab URL, and status should be passed only when the PR was merged/closed before linking. It does not name an explicit alternative tool for deployment-state updates, so the when-not/alternative dimension is implied rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true, covering the safety/mutation profile. The description adds value by disclosing the return shape: a lean confirmation (id, status_id, assignee, updated_at) by default versus the full task when full=true. It omits what happens to a previously assigned or checked-out task, so it stops short of 5.

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

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

Two tightly written sentences with the core action front-loaded and the return-value caveat immediately after. Nothing is redundant or wasted.

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

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

For a mutation tool with a complete schema and annotations covering the safety profile, the description supplies the one thing not in structured data: the default lean response versus the full=true response. Minor gaps remain on permission requirements and reassignment side effects, but the essentials to call it correctly are present.

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

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

Schema description coverage is 100% and the schema already documents task_id, assignee_id, assignee_type, and full in detail. The description only restates the lean-vs-full distinction already present in the full parameter's schema entry, so baseline 3 is appropriate.

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

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

States a specific verb (assign) plus resource (task) and target (a user or agent), distinguishing it from siblings such as release_task, checkout_task, and move_task. An agent can identify the operation without opening the schema.

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

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

The description gives no explicit when-to-use, when-not, or alternatives. It never mentions release_task/checkout_task or the relationship between assigning and those state transitions, leaving usage to inference from the name alone.

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

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

Annotations already establish that this is a non-read-only, idempotent, non-destructive, closed-world mutation. The description adds meaningful behavior beyond that: acquisition is atomic, the lock is exclusive, it is TTL-based, and it expires automatically after ttl_minutes. It does not describe what happens on contention or failure to acquire, so it falls short of a 5.

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

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

The description is front-loaded and appropriately short for the tool. It is slightly repetitive, since "exclusive lock" and exclusive access are stated more than once, but the repetition is minor and does not obscure the key behavior.

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

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

Given the rich annotations, fully described schema, and no output schema, the description covers the essential behavior: atomicity, exclusivity, TTL expiration, and default TTL. It could be more complete by mentioning release_task/extend_checkout or lock-acquisition failure behavior, but it is sufficient for an agent to understand the core operation.

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 task_id and ttl_minutes including the default. The description restates the TTL semantics and default without adding syntax, constraints, or edge-case meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: "Atomically acquire an exclusive lock on a task." It immediately clarifies the concurrency purpose by stating it prevents other agents from checking out the same task simultaneously, which distinguishes it from generic task reads/updates and from the complementary release/extend 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 implies when the tool is useful by explaining that it prevents simultaneous checkout and grants exclusive access. However, it does not explicitly state when to call it versus alternatives such as release_task, extend_checkout, or get_task_context, nor does it describe exclusion conditions.

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

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

Annotations only flag destructive+idempotent; the description adds far more: the tool refuses rather than no-ops under withdraw_marker, a withdrawal comment here is a silent no-op, agent keys get a 403 on user-owned gates, and a posted comment does not by itself clear the gate. These are exactly the failure modes an agent would otherwise hit blind.

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

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

Front-loaded with the action, then the branch table. It is dense and jargon-heavy (clear_endpoint / withdraw_marker / negator comment) in one unbroken block, but every clause carries routing information rather than filler.

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

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

Covers the state-dependent behavior, refusal semantics, and where to inspect current gate state (human_gate on get_task), which is a lot for a one-param mutation with no output schema. It stops short of saying what a successful release returns or how the task's blocking state changes.

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 with 100% schema description coverage, so the schema already defines task_id as "Task ID whose gate to clear." The description adds no format, sourcing, or precondition detail beyond it. Baseline 3 applies.

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

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

Opens with a specific verb+resource ("Release a human gate") and immediately frames the tool against its counterpart set_human_gate and against the raw-armed / human-armed variants. An agent can tell exactly which gate population this applies to without reading the schema.

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

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

Gives explicit conditional routing: clear_path="clear_endpoint" means use this tool; clear_path="withdraw_marker" means it refuses and a negator comment is the correct action; anything else is user-only and yields a 403 naming an alternative. This is a when/when-not/alternative triad stated as fact, not inference.

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

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

Annotations cover the safety profile (writable, non-destructive, non-idempotent), and the description adds genuinely new behavior: anchoring is server-side, caller-computed offsets silently mis-anchor, errors surface as 409 for ambiguous slugs, and replies carry moved_to. Some of this repeats the doc parameter schema, but the offset warning and thread visibility are real added context.

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

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

Front-loads the core action and the anchoring rule, then covers edge cases (moved docs, ambiguous slugs) last. Dense and mostly non-redundant, though the moved_to/409 material overlaps with the doc parameter description.

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

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

No output schema exists, and the description covers the return-relevant cases an agent needs: moved_to on relocated docs and 409 on ambiguous slug. It does not describe the comment object returned on success, which is a modest remaining gap for a write tool.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds meaning by explaining why quote must be copied verbatim, why no offset parameter exists, and that reply_to inherits the thread anchor. It doesn't add syntax examples beyond the schema's slug 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?

States a specific verb and resource ('Comment on a document') and immediately explains the two operating modes: anchored to a passage via quote, or whole-document. The line about the comment appearing in 'the same thread humans see in the document UI' makes the effect concrete and separable from sibling tools like list_doc_comments.

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

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

Gives clear conditional guidance: send quote to anchor, omit it to comment on the whole document, use quote_context when a quote is ambiguous or the server said so. It does not name or compare against sibling alternatives (e.g. add_comment), so the agent gets context but no explicit when-not routing.

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

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

Beyond the annotations (which only give the safety profile), it discloses concrete behavior: the body is not echoed back, the return includes metadata and version, and the version chains directly into update_doc. It also explains the 400 refusal on '/' in slug and how nesting works via parent_id — rich context annotations cannot express.

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

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

Front-loaded with the core action, then the two non-obvious operational facts (version chaining, body not echoed) and the slug constraint. Every sentence carries distinct, useful information with no padding.

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

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

No output schema exists, yet the description fully explains the return value (metadata plus version) and its downstream use, and covers the one tricky parameter constraint. 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?

With 100% schema coverage, the baseline is 3; the description adds real meaning by explaining the slug one-segment/no-slash constraint and the 400 consequence, plus how parent_id produces a <parent-slug>/<slug> path. This compensates and enriches the schema rather than repeating it.

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

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

States a specific verb and resource ('Create a document in a project') and clearly distinguishes itself from siblings by referencing update_doc's base_version workflow. An agent can tell exactly what this does versus get_doc or update_doc.

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

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

Explains the key workflow context — that a create followed by an edit needs no read in between because the version is returned. It gives clear usage context but stops short of explicitly naming when to prefer another sibling (e.g., get_doc for existing docs).

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

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

Annotations cover the safety profile (not read-only, not destructive, not idempotent), and the description adds substantive behavior beyond them: instances are auto-spawned and each gets the previous instance's summary. It doesn't explain permissions or what happens on schedule end/update, but the core mechanism is disclosed.

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

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

Three tight sentences with the core action front-loaded. Minor redundancy in repeating 'on a schedule,' but nothing wasteful.

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

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

For a 13-parameter mutation tool with no output schema, the description covers purpose and the instance-chaining behavior but says nothing about what is returned or the schedule's lifecycle (e.g., ends_at, max_instances interplay). The rich schema fills most gaps, leaving this adequate but not complete.

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

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

Schema description coverage is 100%, so the schema already documents all 13 parameters, including the templating placeholders and cron usage. The description adds little parameter-level meaning beyond mentioning that instances receive the prior summary, so the baseline 3 applies.

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

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

States a specific verb and resource: creates a recurring task schedule that spawns task instances. It's clearly distinct in meaning from create_task (one-off) and trigger_recurring_now, though it never names those siblings 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?

Provides concrete usage contexts ('weekly reports, daily checks and periodic audits'), which tells an agent when this is the right choice. It stops short of exclusions or naming alternatives like create_task for one-off work, so it's clear context without routing.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write. The description adds a genuinely useful behavioral nuance about status defaulting (project default, not parent's), but says nothing about what happens to inherited fields, auth requirements, or what is returned on success.

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

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

Two sentences, no filler, with the core action stated first and the one non-obvious default behavior called out immediately after. Every sentence earns its place.

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

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

For a 12-parameter creation tool with full schema coverage and a clear annotation profile, the description covers purpose and the key defaulting nuance. It omits any mention of the return value (e.g., the new subtask ID), which would be useful since no output schema exists, but otherwise it is sufficient to call correctly.

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

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

Schema description coverage is 100%, so all 12 parameters are already documented in the schema. The description's note that the status default is the project's status rather than the parent's adds meaning beyond the schema, but only for one of twelve parameters. Baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ('Create a subtask') plus the parent relationship, which separates it from the generic create_task sibling. It does not explicitly name create_task as the alternative, but 'under a parent task' is enough for an agent to disambiguate.

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

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

It provides one real usage rule — set status_slug for the initial status and be aware it defaults to the project's status, not the parent's. However, there is no guidance on when to use create_subtask versus create_task, nor any prerequisite or permission context.

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

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

Annotations already declare this is a non-destructive, non-idempotent write, so the safety profile is covered. The description adds the return value (task with id) and the status_slug default, but says nothing about validation failures, required permissions, or what happens on duplicates.

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

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

Three compact sentences, each earning its place: purpose/return, key parameter behaviors, and the duplicate-check instruction. Front-loaded with the action and outcome.

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 14 parameters, 100% schema coverage, and no output schema, the description covers what an agent most needs: return shape, the three most consequential optional parameters, and a pre-check. It leaves minor gaps around validation and sibling routing.

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 baseline is 3; the description still earns credit for explaining inter-parameter relationships the schema states only in isolation: assignee_id combined with assignee_type, parent_task_id creating a subtask, and status_slug defaulting to the project's first status.

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

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

States a specific verb and resource ('Create a new task in a project') and adds that it returns the created task with its id. It does not differentiate from the sibling create_subtask, and even implies subtask creation is done via parent_task_id, which blurs the boundary.

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

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

Explicitly instructs to 'Search list_tasks first so you do not file a duplicate', a clear precondition that steers the agent away from blind use. No guidance on when to use this versus create_subtask or create_recurring_task.

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

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

Annotations already declare destructiveHint=true and non-idempotence, but the description adds important context: deletion is permanent, no further instances are created, and existing task instances are unaffected. It also points to the non-destructive pause alternative, which is valuable behavioral context beyond the annotations.

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

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

The description is two concise sentences with no wasted words. The permanent-deletion consequence is front-loaded, followed by the pause alternative.

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

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

For a one-parameter destructive tool with clear annotations and no output schema, the description covers the essential consequences and the alternative action. Nothing an agent needs in order to invoke it correctly appears to be 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 single recurring_schedule_id parameter is already fully documented in the schema. The description does not add syntax or format details beyond what the schema provides, so the baseline 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 uses a specific verb and resource: permanently delete a recurring task schedule. It clearly distinguishes deletion from pausing by naming update_recurring_schedule with is_active=false as the alternative.

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

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

It states when to use this tool: to permanently stop future instances from being created. It explicitly names the alternative action for pausing, which gives an agent clear routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' in the text is largely redundant. However the description adds genuinely new behavioral context: the output is YAML and is exactly the format import_workspace_config consumes, which matters for safe round-tripping. With annotations carrying the safety profile, this is solid added value.

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: what it exports, its safety profile, and the round-trip guarantee with import. The round-trip warning is placed where it lands before an agent acts on the file. 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 no-parameter, no-output-schema tool, the description covers format, contents, and the import compatibility contract, which is what an agent needs to use the result correctly. It does not clarify whether the YAML is returned inline or written to a file, a small remaining gap with no output schema to fall back on.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly adds nothing about arguments because there are none. The high schema coverage is moot here.

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

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

The description gives a specific verb (Export) and resource (workspace configuration) plus the exact payload contents (rules, project templates, settings) and format (YAML). The round-trip pairing with the import_workspace_config sibling makes the boundary between the two tools unambiguous.

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

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

It states the intended usage context clearly: 'keep it as a backup before any import', which names the sibling tool to pair with and the moment to call it. It lacks an explicit 'when not to use' or note about alternatives beyond import, so it falls short of a 5.

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

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

Goes well beyond the annotations by disclosing the session prerequisite, reliance on the cached checkout_token, and three distinct failure modes, which the agent genuinely needs. The ttl clamp is repeated from the schema, so one of its statements is slightly redundant; still, the failure/session semantics are real added value on top of readOnlyHint/openWorldHint/idempotentHint.

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 action and its motivation, then prerequisites, then constraints. No filler and nothing meaningful omitted.

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 only two params, full schema coverage, annotations covering the safety profile, and no output schema, the description supplies everything else needed: why to call it, what session state must exist, and how it fails.

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 restates the ttl_minutes clamp that the schema already documents and adds no new format, range, or default guidance for task_id or ttl_minutes beyond what is in the schema.

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

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

Specific verb+resource ("Push the expiry of an existing checkout_task lock forward") with the motivating condition ("work that runs longer than the original ttl_minutes"). It explicitly ties itself to the sibling checkout_task, so an agent can distinguish it from release_task or checkout_task immediately.

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?

Clearly states when to reach for it (long-running work outliving the original TTL) and enumerates the failure conditions (lock never acquired here, released, or expired). It does not name a fallback tool to use when those conditions hold, so a triggering-the-wrong-tool exclusion is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered; the description adds real value by specifying permanence and the authorization rule that agents may only delete their own agent-scope memories, with project/workspace memories refused. It does not explain failure behavior for unknown UUIDs or the non-idempotent repeat-delete case flagged in annotations, so it stops short of a 5.

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

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

Three short sentences, each carrying distinct information: the action, the permission boundary, and the corrective alternative. The action is front-loaded 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?

For a one-parameter destructive tool with full annotation coverage and no output schema, the definition covers action, scope, permissions, and the main misuse case. Minor gap: it does not say what happens if the UUID does not exist or points to a memory the caller cannot see.

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

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

Only one parameter, and the schema already documents it at 100% coverage, including the crucial detail that it is the id field from recall(full=true) rather than the key. The description's 'by its UUID' reinforces but adds nothing beyond the schema, so the high-coverage baseline of 3 applies.

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

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

States a specific verb, resource, and identifier ('Permanently delete one memory entry by its UUID'), which cleanly separates it from siblings like remember, recall, and get_memory. An agent knows exactly what it does and what it does not do.

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

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

Gives an explicit when-not ('To correct an entry, call remember with the same key instead of deleting it') and names the alternative tool. It also constrains the universe of deletable memories, though it stops short of saying when deletion is the right call versus archiving or leaving entries alone.

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

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

Annotations already declare this a safe read-only, idempotent operation, and the description goes far beyond them: it discloses the exact auth header accepted on step 1 (X-Agent-Key only) and the specific failure modes for wrong credentials (401) and extra headers on step 2 (400 signature break). These are non-obvious operational traps an agent would otherwise hit.

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 critical constraint (bytes never inlined) is front-loaded, and the numbered two-step flow is easy to follow. There is some redundancy — 'Downloading an artifact is two GETs' restates 'the bytes are never inlined: download them with the two GETs below' — but the procedural detail earns most of its length.

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

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

With no output schema, the description does not enumerate the metadata fields returned by the tool itself (only mentioning download_path and browser_only_url), so an agent can't fully anticipate the response shape. For a read-only lookup with full param coverage, though, everything needed to call it correctly is present.

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

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

Schema coverage is 100%, so both parameters are already documented. The description nonetheless adds real meaning to include_content by stating download_api_url is the step-1 API endpoint, 'NOT the file and NOT a link to open', correcting a likely misinterpretation.

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

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

States a specific verb and resource ('Get artifact details'), and immediately clarifies scope by saying 'the bytes are never inlined' — distinguishing it from a content-fetch tool and implicitly from the sibling list_artifacts. An agent can tell what it returns (metadata) versus what it does not (file bytes) without opening the schema.

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

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

Clearly signals when this tool is not enough: to actually obtain bytes the agent must follow the two-GET flow, and browser_only_url is explicitly called out as a human page that will not work for an agent. It lacks an explicit routing sentence to list_artifacts for enumeration, which keeps it from a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive, so repeating 'Read-only' adds nothing. However, the description does disclose genuine behavior the annotations cannot: results are merged from workspace and project level and carry source annotations, which tells the agent why it may see inherited rules.

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

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

Three short sentences, each doing distinct work: what it returns, safety, and sibling routing. Nothing is padded and the core definition is front-loaded.

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

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

With no output schema, the description gives enough shape (merged rules with source annotations) to interpret the return, and the parameter is fully documented by the schema. The precise return structure and merge precedence ordering are left implicit, a minor gap for a read tool.

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

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

Only one parameter and schema coverage is 100%, with the schema already explaining that project_id is a UUID from list_projects. The description adds no further parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get the effective assignment rules for a project') and immediately glosses the resource in plain language ('how new tasks are routed to agents or people'), so an agent knows what it returns without opening the schema. It also distinguishes itself from two same-family siblings by name.

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

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

Explicitly routes the agent away from get_workflow_rules (status transitions) and get_my_rules (what binds you), which is exactly the disambiguation needed. The nearby sibling get_project_rules is not mentioned, leaving one plausible alternative unaddressed, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the merge of project_memories (key canonical:*) and workspace_memories (kind:canonical), the exclusion of ephemeral session-checkpoints, and automatic slug alias resolution. It does not discuss result ordering or limits, keeping it short of a 5.

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

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

Three sentences, front-loaded with what is returned before the source mechanics and the disambiguation. Dense but each clause carries information; the parenthetical source-key syntax is slightly technical for the general reader but earns its place.

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

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

With no output schema, the description compensates by naming the content types returned (facts, decisions, strategy docs) and the sources merged. Combined with annotations and full schema coverage, an agent has what it needs to call this correctly; only result shape details like pagination or ordering are unstated.

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

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

Schema coverage is 100%, so both topic and project are already documented including the alias-resolution note. The description's alias example (mesh-dev == evc-mesh) largely restates what the schema says, adding only a hint that the topic query spans merged sources rather than one store.

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

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

States a specific verb (query) and resource (canonical knowledge layer), then enumerates the content returned: curated facts, decisions, and strategy docs. It also names the two underlying sources, so an agent can distinguish it from generic memory tools at a glance.

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

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

Explicitly says "Use it for the curated answer on a topic" and routes competing intents: recall for all-memory search, get_canonical_updates for decisions broadcast since a time. Both alternatives are named with the condition that selects them, so nothing is left to inference.

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

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

Annotations already cover safety profile (readOnly, idempotent, non-destructive, closed-world), so credit is for added context: the privacy:public restriction and the targeted-at-you-or-all-agents filter are genuinely useful disclosure. Beyond that, it is silent on ordering, pagination, and volume of the feed, which matter for a change feed an agent polls at session start.

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

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

Three short sentences, front-loaded with the action and scope, then the sibling disambiguation. No filler 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?

No output schema exists, so the description carries some burden, and it does name what comes back (privacy:public, targeted records) and the cursor default. It stops short of describing record shape or feed ordering, a minor gap for a three-optional-parameter read tool.

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

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

Schema description coverage is 100%, so the schema already documents agent, scope, and since including the server-resolved default. The description only echoes 'since a given time' and the targeting semantics already stated in the agent parameter, adding little.

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

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

States a specific verb and resource ('Fetch canonical decisions broadcast since a given time') plus the exact filtering scope (privacy:public records targeted at you or all agents). It also distinguishes itself from the similar-sounding sibling get_canonical by naming its different access pattern.

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

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

Explicitly frames usage as 'a change feed for session start' and routes topical lookups to get_canonical instead. The filtering scope statement also implies when-not (records not targeted at you or all agents are excluded).

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by describing the return shape (event stream with summaries, decisions, errors, plus accumulated knowledge) and the default time window. It does not mention pagination limits beyond the schema's own limit param, so not a full 5.

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

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

Two dense sentences: the first front-loads the core purpose and payload contents, the second routes the agent to siblings. No filler, no repetition of the tool name.

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

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

No output schema exists, and the description compensates by naming what the event stream contains and the default time window. Combined with full schema coverage and read-only annotations, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so baseline is 3. The description earns above baseline by clarifying the default temporal window (last 24h), which explains how the optional `since` parameter interacts with the default behavior — a detail the schema does not spell out.

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

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

States a specific verb and resource (get recent activity for a project) with an explicit scope and default window (last 24h), then lists what the payload contains (event stream with summaries, decisions, errors, plus accumulated project knowledge). An agent can distinguish it from get_project_knowledge and recall purely from this sentence.

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 selection rule ("Use it for 'what changed lately'") and names two alternatives with the exact conditions that favor them: get_project_knowledge for durable facts, recall for one fact. Both include-and-exclude guidance is present.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: the context-cost rationale for not fetching bodies, the fact that the returned version is what update_doc requires as base_version, and the two error/redirect behaviors (moved_to on stale paths, 409 with candidate paths on ambiguous slugs). It stops short of describing what the metadata payload contains, but the critical behavioral 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?

Front-loaded with the default behavior – the single most important fact – before alternatives and edge cases. The final sentence about moved_to and 409 largely duplicates text already present in the doc parameter's schema description, which is the only real waste.

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

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

No output schema exists, so the description must carry return expectations, and it does: metadata plus outline, optional section or full body, moved_to on stale references, 409 with candidate paths, and the version value used for later writes. An agent has everything needed to call this correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the tradeoff behind body vs section (size/context cost) rather than just restating them, and by tying the response's moved_to/409 outcomes back to how doc references resolve. The project_id-only-with-path rule is left entirely to the schema, which keeps this from a 5.

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

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

"Read a document" states a specific verb and resource, then immediately qualifies the scope: default returns metadata plus outline, not the body. It also distinguishes itself from siblings implicitly by noting the returned version is the base_version for update_doc, so an agent knows this is the read side of a read/modify pair.

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

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

Explicitly routes among the three read modes: default outline, section="<heading>" for one part, body=true for the whole page, with stated preference for section=. It also names a fourth use case (version_only-style cheap change check implied by base_version) and explains the moved_to recovery path, so there is no ambiguity about which call to make.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety is covered; the description adds genuinely new behavior by documenting the failure mode ('Errors if no entry has exactly that key'). It does not discuss what happens when the key is ambiguous across scopes, which project_id/scope resolve only implicitly.

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

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

Two sentences, front-loaded with the verb and resource, then the selection condition and the error case. 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 four params, no output schema, and a single-required-param surface, the description covers purpose, trigger, and error behavior adequately, and the schema handles the rest. The only gap is how ambiguity across scopes/projects is resolved, which an agent must infer from parameter 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 100%, so every parameter, including scope, project_id and include_archived, is already documented at the field level. The description only reinforces that the key must be the exact value recall returned, which the schema also states. Baseline 3 is correct.

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

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

States a specific verb and resource ('Full text of ONE memory by exact key') and immediately pins the scope with the capitalized 'ONE'. It references the sibling tool recall and the '…' cut marker, so an agent can tell this apart from recall/recall_with_graph without opening a schema.

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

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

Gives a concrete trigger condition: use this when a recall result is truncated with the '…' cut marker. It names recall as the source of the key, implicitly framing the alternative. It does not state when NOT to use it (e.g. when the recall result was already complete), so it falls just short of the top band.

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

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

Annotations already establish that the tool is read-only, idempotent, non-destructive, and closed-world, so the description does not need to repeat safety traits. It adds useful behavioral context by stating that the result includes workspace-level and project-level rules with source annotations, though it does not describe rate limits, auth requirements, or response shape.

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 compact sentences with no wasted clauses. It is front-loaded with the core purpose and then moves efficiently into scope and sibling-tool differentiation.

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

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

For a one-parameter, read-only tool with rich annotations and full schema description coverage, the description provides enough context to call it correctly. It explains what rules are returned, the workspace/project-level scope, and when to prefer this tool over sibling rule-listing tools.

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 100% description coverage for the single project_id parameter, including the distinction between providing a UUID and omitting it. The description does not add parameter-level detail beyond the schema, so the 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 uses a specific verb and resource: "Get ALL governance rules that apply to you," and enumerates the rule categories (workflow constraints, assignment policies, behavioral requirements). It explicitly distinguishes itself from sibling tools get_project_rules, get_assignment_rules, and get_workflow_rules, so an agent can select it without opening other schemas.

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

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

It gives a clear triggering condition: "This is the one to call before acting in a project." It also contrasts alternatives by explaining that get_project_rules lists every configured rule regardless of target, while get_assignment_rules and get_workflow_rules return only a single rule family.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the non-blocking nature, the compact cold view (only in_progress, review, and top 5 todo), the meaning of the `omitted` counter, description omission with has_description, and envelope/valueless field suppression. This is genuine behavioral context, though written so densely it requires careful parsing.

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

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

Front-loaded correctly: purpose, then alternatives, then default-view behavior. The omission rules are packed into long parenthetical clauses and 'full=true returns the complete items' is stated twice, so it reads heavier than necessary, but no sentence is filler.

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

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

With no output schema, the description carries the return-shape burden and does so: it explains the envelope, `omitted`, suppressed fields, and where to get full records (get_task / full=true). The delta/revision/session parameters are left entirely to the schema, which is acceptable given 100% coverage, but a one-clause pointer to the delta path would close the last gap.

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 nonetheless adds semantics the schema doesn't spell out — that full=true restores descriptions and omitted items, and that passing status_category also defeats the default truncation. That behavioral link between parameters is real added value.

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

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

States a specific verb and resource — 'Get YOUR assigned tasks' — with the scope ('YOUR', non-blocking) front and center. It explicitly distinguishes itself from list_tasks and poll_tasks, so an agent can tell the three apart without opening schemas.

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

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

Names both alternatives and the exact condition that selects each: list_tasks to browse/search others' tasks in a project, poll_tasks only to block until a new assignment arrives. The 'only' qualifier on poll_tasks is an explicit when-not signal.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds scope information (what the payload contains) but nothing behavioral beyond that, such as size or whether statuses are workspace-wide. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Two tight sentences with zero filler. The return content is front-loaded, and the pointer to list_projects comes second, so the reader gets the core purpose immediately.

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

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

There is no output schema, so the description carries the burden of explaining return values—and it does, naming statuses and custom field definitions. Combined with full annotation and parameter coverage, an agent has everything needed to call this 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 coverage is 100%, and the single parameter is already documented as a 'Project UUID, from list_projects.' The description repeats the list_projects provenance, adding no new semantic detail. Baseline 3 applies when the schema fully documents the parameter.

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

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

States a specific verb and resource ('Get one project's details') and enumerates exactly what is returned: statuses and custom field definitions. It distinguishes itself from the sibling list_projects by noting that list_projects is where you find the project_id.

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?

Implicitly routes the agent: use list_projects to obtain the id, then get_project for details. It also clarifies that the returned status slugs are what move_task and create_task consume, which helps decide downstream calls. No explicit exclusions are given, but the usage context is clear.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds behavior the annotations don't: the two-tier return structure (workspace + project), that only the workspace tier is paged and narrowed, and that the tool returns 'permanent' rather than recency-ordered content.

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 core purpose and the routing guidance. The parenthetical on paging is dense but every clause carries information; minor cost is readability of the nested filter detail.

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 read-only retrieval tool with full schema coverage and no output schema; the description covers scope, tiering, filtering, and alternatives. It stops short of describing the shape of a returned memory (fields, ordering), which would be the remaining gap for an agent planning a call.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the key semantic that limit/offset/min_importance/tags_any apply only to the workspace tier, implying project-tier memories are returned in full and unfiltered—a distinction the per-parameter descriptions state individually but not as a whole-tool rule.

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

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

States a specific verb and resource ('Get the PERMANENT KNOWLEDGE of a project') plus the content types it covers (decisions, conventions, accumulated context) and the two-tier scope (workspace-level + project-level). An agent can distinguish this from get_context, recall, and get_canonical without opening any schema.

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

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

Explicitly names the three nearest alternatives and the condition that selects each: get_context for recent activity, recall for one specific fact, get_canonical for owner-curated decisions on a topic. It also states the positive selector ('standing picture of ONE project'), leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so safety needs no restating. The description adds real context beyond them by clarifying this is an unfiltered audit view spanning both workspace and project scope, which explains why the result set may be large. It stops short of describing return shape or ordering, keeping it just under 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?

Two sentences, zero padding. The scope-defining clause comes first and the disambiguation guidance follows, which is the right order for an agent deciding whether to call this or a sibling.

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

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

A single-parameter read tool with full annotation coverage and a fully documented schema needs little more. The description supplies the scope semantics and sibling routing that structured fields cannot express; only output shape is unaddressed, and there is no output schema to lean on, which is a minor gap for an audit-style listing.

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

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

Schema coverage is 100% and the project_id description already names its source ('from list_projects'). The tool description adds no further meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get every rule configured for a project'), plus the exact scope ('workspace + project scope, whoever it targets'). The phrase 'an audit view of the whole rule set' makes the exhaustive nature unmistakable and distinguishes it from the filtered siblings named immediately after.

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

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

Explicitly routes the agent: use get_my_rules for rules binding the caller, get_assignment_rules for who gets new work, get_workflow_rules for allowed status transitions. Each alternative comes with the condition that selects it, leaving nothing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior annotations don't carry: result ordering (newest first) and the default single-report return, which materially affects how the agent interprets an empty vs. populated response.

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 filler, with the resource definition and ordering front-loaded before the redundancy note. Every clause carries actionable 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 read-only fetch with a fully documented three-parameter schema and no output schema, the definition covers what's needed to invoke it correctly. It could go slightly further by hinting at what a report entry contains, but the ordering and default-return details close the main gap.

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 limit, since, and project_id are already fully documented with defaults, max, and RFC3339 format. The description's 'newest first' adds a little semantic framing for how limit/since combine, but not enough to exceed the baseline.

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

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

States a specific verb (Read) and resource (a project's Updates feed) and disambiguates the jargon by glossing it as 'the lead's daily status reports.' The ordering guarantee ('newest first') further pins down what the agent gets back, distinguishing it from generic project reads like get_project.

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

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

Explicitly notes the default behavior (latest report only) and, importantly, warns that the latest report is already surfaced by get_project and get_task_context — which tells the agent when this call is redundant. It stops short of stating a full when-to-use/when-not-to-use rule (e.g., use this when you need history beyond the latest report).

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description adds value beyond that by describing the shape of each returned entry (what was accomplished, issues found, artifacts produced), which matters since there is no output schema. It omits ordering guarantees and behavior when no prior instances exist.

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

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

Two sentences, front-loaded with the core action, and the second sentence earns its place by describing entry contents. The closing clause about giving context for the current instance is somewhat repetitive of the opening framing.

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

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

For a read-only two-parameter tool with full schema coverage, the description covers purpose and return content adequately. However, with no output schema present, it should say more about result ordering, empty-history behavior, or volume, which an agent consuming history would want to know.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema, including the limit default and the source of the schedule UUID. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource — returns instance history for a recurring task schedule — and the second sentence spells out what each entry contains (accomplishments, issues, artifacts). That clearly separates it from list_recurring_schedules (which enumerates schedules) or get_task, though it never names an alternative explicitly.

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

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

The phrase 'gives context for the current instance of a recurring task' implies when to call it, but the guidance is only implied. There is no explicit 'use this before doing X' or 'for the current instance use get_task_context instead' routing against the many neighboring context tools.

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

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

Annotations already establish read-only/idempotent safety, and the description adds substantial behavioral detail: comments are newest-first, pagination markers are included, timestamps are UTC, automation comments are summarized, full=true restores REST fields, and status lookup failures preserve status_id with status_lookup_error. These are meaningful operational traits beyond the annotations.

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

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

The description is dense but front-loaded with the core purpose, then layers return-shape and caching/pagination caveats. Most sentences carry useful information, though the single-paragraph packing makes it less scannable than it could be.

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

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

For a nine-parameter read tool with no output schema, the description covers the key return modes, comment behavior, pagination limits, since-based skipping, and status lookup fallback. Combined with the fully described schema and read-only annotations, an agent has enough context 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 description coverage is 100%, so all nine parameters are already documented in the input schema. The description reinforces some semantics such as full, include_auto, comments_limit, and since, but adds little beyond what the schema already states; baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Get task details,' then immediately narrows to compact decision fields, human_gate, and status slug. It is clear what the tool returns, though it does not explicitly contrast itself with sibling tools such as get_task_context or list_comments.

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 embedded guidance for several parameters, such as using since to skip unchanged tasks and include_auto to restore automation bodies. However, it does not explicitly say when to use this tool versus siblings like get_task_context, list_comments, or update_task, so usage is mostly 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?

While annotations cover safety (readOnlyHint=true), the description adds crucial behavioral context by enumerating exactly what data streams are integrated (details, comments, artifacts, dependencies, activity). This helps the agent understand the scope of the returned data packet.

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 highly efficient, using two sentences. The first sentence is a powerful summary, and the second provides the technical justification (combining results) without unnecessary 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?

Given the complexity of aggregating multiple data sources, the description is perfectly complete. It defines the scope of the output contents and the mechanism of the call (single response), which is more valuable than detailing the output structure.

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

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

The schema coverage is 100%, meaning the schema already defines the parameter fully. The description provides no new semantic meaning to 'task_id' beyond the context of a single task ID.

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

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

The purpose is stated clearly using a specific verb ('Get') applied to a resource ('ONE TASK'). It immediately distinguishes itself by explaining that it provides a comprehensive overview ('EVERYTHING') that combines data from multiple underlying 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 tool provides explicit guidance on its usage pattern: it should be used when the user needs a holistic view of a task, as it explicitly 'Combines the results of get_task, list_comments and list_artifacts' into a single call, implying efficiency over multiple separate calls.

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

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

Annotations already declare it read-only, idempotent, closed-world and non-destructive, and the description adds substantial extra context: the default compact row-array shape, its exact columns, the 60-char project truncation rule, that status is computed_status, and that full exposes capabilities/heartbeat/escalation_to/timestamps.

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

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

Compact two-sentence structure, front-loaded with the primary behavior and the default/full trade-off emphasized via the dash. The long parenthetical is dense but each clause carries new 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?

With no output schema, the description carries the burden of describing returns and does so concretely (columns, truncation, full-profile fields), so an agent knows exactly what it gets in either mode.

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

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

Schema coverage is 100% and the single param is documented, so baseline is 3; the description goes further by enumerating what 'full' actually returns (capabilities, heartbeat, escalation_to, timestamps, full zone text), which the schema's terse boolean description 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?

States a specific verb+resource ('Get the workspace team directory') and scopes it precisely ('listing all agents and human members'), which distinguishes it from narrow siblings like list_sub_agents and get_my_rules.

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?

Clearly routes the caller: default returns the compact table, 'pass full=true for the complete dump'. That is explicit conditional guidance for the one mode choice, though it never names alternatives or says when a directory lookup is preferable to other discovery tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description's 'Read-only' is largely redundant. It still adds useful behavioral context by stating that results include permissions for the calling agent and that this should be checked before a potentially restricted move_task.

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 wasted text. Purpose and contents are front-loaded, followed by the pre-move usage check and sibling differentiation.

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

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

For a one-parameter read-only getter with no output schema, the description is complete enough: it states what is returned, when to consult it, and how it differs from nearby tools. Annotations already cover the safety profile, so little else is needed.

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

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

Schema coverage is 100%, and the sole parameter project_id is already documented as coming from list_projects. The description adds no additional syntax or format details beyond what the schema provides, so the baseline 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 states a specific verb and resource - get workflow rules for a project - and names the concrete contents: allowed transitions, policies, and permissions for the calling agent. It also distinguishes itself from siblings by explicitly saying get_assignment_rules covers routing and get_my_rules covers everything that binds you.

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 condition: check this before a move_task that may be restricted. It also names the relevant alternative tools and their scopes, so an agent can choose between this, get_assignment_rules, and get_my_rules without guessing.

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

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

Annotations already establish that this is a non-destructive, idempotent mutation, so the description does not need to repeat safety hints. It adds useful behavioral context: heartbeat affects the team directory, changes no task, and returns no queue. It could say more about the response payload or rate expectations, but the key side effects 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 tight sentences, with the core purpose front-loaded followed by usage timing and a sibling-tool clarification. Every sentence adds distinct value without 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 six-parameter optional heartbeat tool with full schema coverage and no output schema, the description covers purpose, timing, side effects, and the main alternative. It does not describe what, if anything, the call returns or how metadata/model fields interact with directory display, leaving a minor completeness gap.

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 each parameter is already well described in the schema. The description reinforces that status and current task are shown in the team directory, but it does not add parameter-level syntax or edge-case guidance beyond the schema. Baseline 3 is appropriate when the schema carries 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 states a specific action and resource: reporting liveness and current work so the team directory reflects online/busy status and current task. It also distinguishes this from task-queue tools by explicitly saying it changes no task and returns no queue, pointing to get_my_tasks for assignments.

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

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

It gives explicit timing guidance: call at session start and every few minutes during long work. It also clarifies the alternative for reading assignments via get_my_tasks, so the agent knows not to use heartbeat for task retrieval.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false; the description adds real value on top by disclosing blast radius (the entire workspace, not per-project) and the one recovery path (a prior export). It does not say whether existing configuration is replaced or merged, nor what happens on partial failure.

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, no filler, with the action and effect front-loaded and the safety-critical rollback note given last for emphasis. Every sentence carries operational weight.

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

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

For a destructive, non-idempotent, single-parameter tool with no output schema, the definition covers scope, input format, and recovery. The remaining gap is replace-versus-merge semantics and partial-failure behavior, which matter for a whole-workspace destructive import.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the round-trip contract (export, edit, import) and warns that the server rejects unparseable YAML. That meaning goes beyond the parameter's own schema text.

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

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

States a specific verb and resource (import workspace configuration from YAML) plus the exact effect: applies rules, statuses, and project templates to the calling agent's whole workspace. The pairing with the sibling export_workspace_config is named explicitly, so an agent can distinguish the two without inspecting schemas.

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

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

Gives an explicit prerequisite sequence: run export_workspace_config first and retain its output as the only rollback. That is actionable when-to-use guidance. It stops short of stating when not to use it (e.g., single-project or partial-scope edits) or any permission preconditions.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description goes well beyond them: exact auth header acceptance on step 1 (only X-Agent-Key; X-API-Key and Bearer yield 401), the header-free requirement on step 2 (extra headers, especially Authorization, break the presigned signature with 400), and the human-only nature of browser_only_url that returns 401 by design. These are precisely the failure modes an agent would otherwise hit blind.

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

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

Purpose is front-loaded in the first sentence, then a numbered two-step recipe and a compact pitfalls sentence. Every sentence carries actionable detail, but the download procedure is arguably out of scope for a list tool and inflates length relative to the one-param surface.

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

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

With no output schema, the description must explain what comes back, and it does: each item has download_path plus an optional browser_only_url. It also supplies the full follow-on download protocol and its error semantics, leaving no ambiguity about how to actually retrieve the bytes.

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% for the single task_id parameter, so the baseline is 3 even though the description adds nothing about it. The description's real semantic contribution is to the response fields (download_path, browser_only_url), which is helpful but not input-parameter guidance.

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

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

Opens with a specific verb+resource+scope: "List artifacts attached to a task." This is clearly distinct from the singular sibling get_artifact, though it never names that sibling explicitly to reinforce the boundary. The rest of the description pivots to download mechanics rather than listing, which slightly dilutes the stated purpose.

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

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

It gives concrete operational context: list for a task, then use download_path for the two-GET download flow, and ignore browser_only_url for agent use. There is no explicit statement of when to prefer this over get_artifact or of any exclusion, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: automation prefixes are collapsed to one-line summaries unless include_auto=true, full=true restores non-capability REST fields, after is exclusive, and unknown IDs / invalid order values are refused rather than silently coerced. Missing: nothing about include_internal's default-on behavior or what the paginated response envelope contains.

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

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

Front-loaded with the core behavior and each clause covers a distinct mode or edge case, so there is little waste. The semicolon-chained, parenthetical style makes it dense and slightly harder to scan than it needs to be.

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

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

For an 8-parameter read tool with no output schema, the description covers the important complexity: compact vs full projection, automation stripping, delta pagination via after, ordering, and refusal behavior on bad input. Gaps are minor – include_internal is never mentioned and the response shape is only gestured at ('with pagination').

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

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

Schema description coverage is 100%, so every parameter is already documented and the baseline is 3. The description reinforces a few points (default limit 10, newest-first, after accepting UUID or RFC3339 and being exclusive, unknown IDs refused) but mostly restates schema content rather than adding new 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?

Opens with a specific verb+resource plus scope: 'List comments newest first (limit default 10), with pagination.' It distinguishes the compact view from the full view and thin automation summaries, so an agent knows exactly what comes back. It never names the sibling it is not (list_doc_comments), so the task-vs-doc distinction is left to the task_id parameter.

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

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

Usage context is implied rather than declared: 'order=asc gives chronological reading' and 'after ... returns only newer comments' tell an agent which mode fits which reading pattern. There is no explicit when-to-use/when-not or routing to alternatives such as list_doc_comments or get_task.

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the bar is lower. The description still adds real behavioral context beyond them: resolved threads are hidden by default, orphaned comments remain visible but point nowhere (orphaned=true), and an ambiguous slug yields a 409. Much of the path/moved_to/409 detail, however, is restated from the doc parameter's own schema description, so net-new disclosure is moderate.

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

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

The opening sentence is well front-loaded and dense with value, but the closing sentence on doc paths, moved_to and 409 is essentially a restatement of the doc parameter description, which inflates the definition without new information. Roughly half the text is redundant with structured data.

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

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

There is no output schema, so the description carries the return-shape burden — and it does: thread nesting, replies under top-level comments, quoted anchor, author, the orphaned flag, and the moved_to field on replies. Combined with the annotations covering the safety profile and full schema coverage of parameters, an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema at length. The description's discussion of old paths, bare slugs, moved_to and the 409 duplicates that text rather than adding syntax or defaults the schema lacks. 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?

Specific verb+resource: 'Read the comments on a document as threads', and it goes further by describing the returned structure (nested replies, anchor, author). However, it never distinguishes itself from the sibling list_comments (which presumably lists comments across documents) or from comment_doc, so an agent must infer the boundary. Clear purpose, but no sibling differentiation.

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

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

Usage is implied by 'on a document' and the explanation of include_resolved, but there is no explicit when-to-use / when-not guidance and no naming of an alternative tool. The agent can infer it is the per-document reader, but the description never confirms that against list_comments.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds real value by disclosing that no document bodies are transferred and how the result is paged (total_count, has_more, offset for the remainder). It omits nothing dangerous, though it doesn't state the default exclusion of archived docs, which matters for interpreting the map.

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: scope first, cost/no-bodies benefit second, pagination mechanics last. No repetition of the schema and every clause carries information.

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

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

With no output schema, the description carries the burden of return-shape explanation and does so fully: listed fields, path/has_children for tree navigation, and paging metadata. An agent can call it and interpret the response correctly without further assumptions.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the offset/has_more interplay as a continuation protocol rather than a bare numeric field. It adds nothing on include_archived, which stays purely schema-documented.

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

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

States a specific verb and resource ('List a project's documents') and enumerates what each entry carries (id, title, slug path, version, last editor). It also names the sibling it replaces for single-item reads ('get_doc returns one page'), so an agent can route without opening the schema.

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

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

Explicitly frames the use case ('cheap on a whole project, serves as a map of it') and contrasts with get_doc for single-page reads. It does not mention search_docs or the include_archived toggle as an alternative, so the exclusion set is partial but usable.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely non-obvious behavioral fact not present in the annotations: archived projects are silently filtered out unless include_archived=true, which is exactly the kind of default-result skew an agent could misread.

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: what it returns, when to call it, and a default-behavior caveat. The most actionable guidance (call it first) is front and center and nothing is padded.

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

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

With no output schema, the description usefully enumerates the returned fields and covers the archived-filtering default, which is enough for an agent to call it correctly. It leaves result volume and ordering unpinned, a minor gap for a two-parameter listing tool.

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

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

Schema coverage is 100% and both parameters are fully described in the schema, including the defaults and the workspace-access caveat. The description's mention of include_archived restates the schema's default rather than adding syntax, format, or interaction detail, so the baseline of 3 applies.

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

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

States a specific verb and resource and names the payload the caller gets back ('ids, names and slugs'), which is more than a restatement of the name. It implicitly separates itself from the single-project sibling (get_project) by framing itself as the enumeration step, but never names that 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?

"Call it first to find the project_id that most other tools require" gives a concrete ordering rule that tells the agent when to reach for this tool before others. It stops short of an exclusion rule (e.g., skip this and call get_project when you already have a slug or name).

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it tells the agent the return payload's key purpose (the ids consumed by four specific sibling tools), which is the main thing an agent needs to know before calling it.

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

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

A single tight sentence that front-loads the action and resource and then names the consumers of the returned ids. No filler or restated title.

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

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

For a 2-parameter read with full schema coverage and rich annotations but no output schema, the description covers the essential gap—what the returned ids are for. It could say a bit more about returned fields or ordering, but the critical information for correct invocation is present.

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

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

Schema description coverage is 100%, with both project_id (UUID, from list_projects) and active_only (default true, false includes paused) fully documented. The description adds no parameter-specific detail beyond the schema, which is the expected baseline when the schema already does the work.

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

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

States a specific verb (lists) and resource (recurring task schedules of a project), and explicitly names the downstream consumers (get_recurring_history, trigger_recurring_now, update/delete_recurring_schedule). This clearly distinguishes it from siblings like create_recurring_task and get_recurring_history.

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 workflow—call this first to obtain ids that the four named siblings require—which is clear contextual guidance. It stops short of explicit 'when not to use' or a named alternative for listing schedules, but for a straightforward list tool the routing signal is strong.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered; the description adds genuine scope behavior beyond that (children only vs. full subtree, plus the parent-agent default when agent_id is omitted). It stops short of describing result shape or any depth-limit behavior in the description itself, so it is not exhaustive.

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 dense sentences, zero filler, with the core behavior and both sibling disambiguations front-loaded before any edge case.

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 no-output-schema list tool with zero required parameters, the definition covers purpose, scope, recursion behavior and alternatives. The only mild gap is that it does not hint at what a returned entry contains (id, name, status), which would help an agent decide whether to recurse.

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

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

Schema coverage is 100%, so both parameters are already fully documented, including the 10-level depth cap and the 'omit for calling agent' default. The description reinforces the direct-children vs. recursive distinction but adds no syntax or format detail the schema does not already carry, so the baseline 3 applies.

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

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

States a specific verb and resource (list sub-agents registered under an agent) and immediately disambiguates from two siblings by name: register_sub_agent for creation and get_team_directory for workspace-wide membership. An agent can distinguish all three without opening a schema.

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

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

Explicit routing: use this for direct children by default, set recursive=true for the whole subtree, and use get_team_directory instead when you want every member of the workspace. Both the when-to-use and the when-to-use-something-else conditions are stated.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context: strict parameter validation, the API page budget, compact vs. full=true payload differences, and exactly which fields compact items carry including runtime_state and routing fields. It stops short of describing pagination or rate behavior in depth, but the payload contract is well 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?

Front-loaded with purpose and scope rules, then payload shape, then alternatives — a sensible ordering with no filler sentences. It is a single dense block that would read better split into scope/payload/alternatives lines, but every clause carries information.

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

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

With 16 optional parameters and no output schema, the description compensates by documenting the compact item field set, the workspace-only project_id field, and the full=true alternative — precisely what an agent needs to choose a mode and interpret results. Given the complexity, nothing essential is missing.

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

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

Schema coverage is 100% and the schema descriptions are themselves unusually detailed (e.g., list_revision, order, limit clamping), so the schema does the heavy lifting. The description adds the key project_id vs. workspace_id+search pairing and the full=true semantics, but does not enrich most of the 16 parameters beyond what is already structured. Baseline 3 is appropriate.

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

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

States a specific verb and resource ("List tasks") and immediately disambiguates the two scope modes: project listing via project_id vs. cross-project search via workspace_id plus search. It also names get_task and get_my_tasks as the tools for full details and personal queues, so it is distinguishable from siblings without opening any schema.

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

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

Gives explicit routing rules: project_id for a project listing, workspace_id+search for cross-project search, get_task when full details are needed, get_my_tasks for your own queue. It also names failure conditions (unknown parameters and invalid categories are errors), which is when-not guidance an agent can act on.

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

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

Goes well beyond the annotations by disclosing a cross-entity side effect (releasing dependents waiting on a `deployed` dependency edge of this card), which the agent could not infer from destructiveHint=false. It also refines idempotentHint=true with concrete semantics: the same sha+env pair is safe to report and the first deployed_at stands.

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 action, and every clause carries information — the field list, the side effect, the idempotency rule, and the precondition. Dense but no filler; slight density cost from the parenthetical id-location hint.

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

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

For a 4-required-param mutation with no output schema, it covers the important unknowns: preconditions, idempotent behavior, and downstream effects. It stops short of describing failure behavior (e.g. what happens if the link is not a pr link) or required permissions, which a mutating tool ideally would state.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds real value on top: the relational constraint that link_id must be a pr link belonging to task_id, plus where to find that id. It leaves format details (40-hex sha, env charset) to the schema, which 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?

Opens with a specific verb+resource: 'Record that the change behind a PR/MR link is deployed', then names exactly the fields mutated (deployed_sha, deployed_env, deployed_at) and the side effect on dependency edges. This is clearly distinguishable from add_vcs_link (creates links) and get_task (reads link ids), so an agent can pick it without opening any schema.

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

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

Gives an explicit precondition — the link must be a pr link of task_id — and routes the agent to the right sibling tools for obtaining the id ('link ids are in get_task vcs_links and in the add_vcs_link result'). It does not state when not to call it or what to do for non-PR links, but the usage context is unambiguous.

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

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

Goes well beyond the annotations by disclosing the auto-reassign-to-creator behavior on 'review', the exact return shape ({task, new_status}), which lean fields come back, and why the post-move assignee is always included. This is exactly the mutation behavior an agent needs before calling.

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

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

Dense but front-loaded: the primary action and slug constraint come first, then the review auto-reassign caveat, then the return-shape details. No sentence is wasted, though the return-shape sentence is somewhat long.

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

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

With no output schema, the description fully compensates by describing exactly what is returned in both lean and full modes, and it covers the significant hidden side effect of auto-reassignment. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: status must be a slug not a UUID, assignee_id overrides auto-reassign, and full=true returns the whole reloaded task. These clarify cross-parameter interactions the schema does not capture.

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

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

States a specific verb+resource: 'Change task status' with a concrete example transition (todo → in_progress → done). It does not explicitly differentiate itself from close siblings like update_task or assign_task, so it falls short of a 5.

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

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

Usage is implied through the status-transition framing and the conditional 'unless assignee_id is provided' note, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as assign_task for reassignment-only operations.

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

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

Beyond the readOnly/idempotent annotations, it discloses the blocking wait, the termination conditions (task assigned or timeout expiry), what the response contains, and the lean-vs-full payload difference including missing envelope fields. That is unusually rich operational context.

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

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

Purpose is front-loaded in the first clause, and every sentence carries distinct information (blocking semantics, return shape, payload mode, migration note). Slightly dense as a single run of semicolon-joined clauses rather than cleanly separated statements.

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

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

There is no output schema, yet the description still explains what comes back (assigned tasks plus a change indicator) and how the payload varies with full. For a two-optional-parameter, annotation-covered tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value the schema lacks: it characterizes the lean view as "first-line descriptions, no envelope fields," which tells the agent why to set full=true. Timeout bounds are restated rather than extended, so it stops short of a 5.

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

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

Names a specific verb and resource ("Long-poll for new task assignments") and immediately distinguishes it from the sibling get_my_tasks by calling that one "the non-blocking equivalent." An agent can pick between the two 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?

"use it only in a loop that waits for work" is an explicit when-to-use rule, and the closing sentence names the alternative (get_my_tasks) plus the condition that selects it (non-blocking reads). Backward-compatibility status is also disclosed.

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