Kosmodrom

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Creates nothing.' It adds genuinely new context beyond annotations: the domain invariant that a task has one live branch, and that suggestedName is either the live branch or the server-convention name for a new one.

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, front-loaded sentences that lead with the read operation and its returned fields, then param behavior. The parenthetical asides are informative rather than filler, though the second sentence packs several clauses.

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 in the definition, the description carries the return-value burden and does so by enumerating the fields returned plus the conditional suggestedName. Nothing essential to a correct call 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 real meaning: it explains that suggestedName only appears alongside taskID and what that value represents. This goes beyond the schema's one-line parameter descriptions.

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

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

States a specific verb (Lists) and resource (repository branches) and names the concrete fields returned: sha, default/protected flags, and taskKey. No sibling tool covers branch enumeration, so the agent can identify this 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?

It gives clear conditional guidance: use search to filter by name substring, and pass taskID to scope to a single task's live branches. It does not name an explicit alternative or exclusion case, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so safety is covered 'schema-only'. The description adds real value beyond that: the bug is created as a draft and only published on request, bugs always have a testing stage, and stage assignees accept uuid/'any'/null. It also discloses the return contents (key, link, status, allowed transitions), which matters since there is no output schema.

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

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

Front-loaded with the core create/draft behavior, then the placement and assignee nuances. It is dense but every clause carries information an agent needs for a 26-parameter tool; a slightly more structured list of the placement options would help, but there is little waste.

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

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

For a 26-parameter creation tool with no output schema, the description covers the important missing pieces: draft lifecycle, placement rules, assignee semantics, and the returned key/link/status/transitions. Remaining gaps (auth needs, validation errors) are minor given the very detailed schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-field interpretation the schema alone leaves implicit: type is criticality, not the nature of the defect (bugType), and placement is a choice among feature/version/product backlog. These distinctions reduce mis-set parameters, though most per-field detail still lives in the schema.

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

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

States a specific verb and resource ('Creates a bug') and immediately qualifies it with the draft lifecycle ('as a draft... published separately'), which distinguishes it from a publish operation like task_publish. It also enumerates the placement options and clarifies the type/bugType split, so an agent can tell what the tool does without opening the schema.

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

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

Gives clear trigger context ('when the user asks to log a defect') and priority guidance for placement: feature is the 'preferred' option, version is 'when no feature fits', and product backlog is the 'last resort'. It does not name sibling tools to avoid, but the placement ordering and draft-vs-publish wording cover the main selection decisions.

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 destructiveHint=true annotation by disclosing irreversibility and precise authorization rules: token owners can delete their own message within 60 minutes, while chat administrators and the product lead can delete any message. This time window and permission model is exactly the context an agent needs before invoking a destructive tool.

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

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

Two tight sentences: the action first, then the safety/permission context and the intended-use condition. Zero filler and every clause earns its place.

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

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

For a destructive single-parameter tool with annotations covering the safety profile and no output schema, the description supplies the missing pieces: irreversibility, permission tiers, and the triggering user intent. Nothing essential to correct invocation is absent.

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

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

There is a single parameter with 100% schema description coverage, so the schema already carries the semantics of messageID. The description adds no format, scope, or ID-source detail beyond what the schema provides, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Deletes a chat message'), which cleanly separates it from chat_message_update and chat_read. It stops short of explicitly naming the sibling it is not, so it is clear but not maximally differentiated.

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 condition for use ('an explicit user request to remove an unneeded message') with concrete examples (duplicate, wrong chat). No named alternative such as chat_message_update is offered for the edit-vs-delete decision, so it lacks exclusions.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses the 60-minute window, the ownership requirement, that mentions are recalculated from mention tokens, that attachments are wholly replaced (and [] clears them), and that an 'edited' mark appears. This is rich behavioral context an agent needs before invoking a mutation.

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

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

Two dense sentences, front-loaded with the action and its hard constraint; every clause (timing, ownership, mentions, attachments, edited mark, late-correction routing) carries distinct 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?

For a destructive mutation with annotations already flagging the safety profile, the description covers eligibility, timing, replacement semantics, and visible side effects. No output schema is needed for an edit confirmation, so nothing material 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 real meaning: text fully replaces the prior text, mentions are recomputed, and attachments replace rather than append, with [] as the explicit clear-all value. That clarifies the replace-vs-append semantics the schema alone leaves ambiguous.

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 (Edits) and resource (the token owner's own regular message), and the qualifiers 'own' and 'regular' distinguish it from chat_send, chat_message_delete, and other chat siblings. 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?

Gives concrete conditions for use: the message must be the token owner's own, and edits are only valid within 60 minutes of sending. It also implicitly routes late corrections to a reply. It does not name sibling tools as alternatives, but the when/when-not constraints are 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/openWorld=false and non-destructive, so safety is covered. The description goes further by disclosing the selection rule ('still without their answer, regardless of age') and the pagination contract ('pages continue with nextCursor while hasMore'), which the 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 behavior and kept to two sentences with no filler. The enumeration of returned fields is slightly dense, but every clause carries information rather than restating the 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?

With no output schema, the description responsibly enumerates the return payload (chat and link, why it is addressed, related item, message with attachments) and the pagination contract. For a read-only, two-parameter list tool this covers what an agent needs, missing only explicit 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 both parameters are already documented and the baseline is 3. The description adds genuine meaning by stating that pages continue via nextCursor while hasMore, tying the cursor/limit pair to a concrete continuation condition the schema does not state.

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 messages addressed to the token owner that are still unanswered, with the addressing reason (direct chat, mention, reply). It is clearly distinguishable from chat_read or chat_send, though it never names a sibling to sharpen the contrast.

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 trigger condition: 'Useful when the user asks what awaits their reply.' That is clear usage context, but there is no when-not guidance and no named alternative (e.g. chat_read) for unanswered vs. all messages.

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 provide readOnlyHint=false, destructiveHint=false, and openWorldHint=false, which already tells the agent this is a non-destructive write. The description adds important behavioral context: only Kosmodrom web reactions are available, existing reactions are not duplicated, system messages take no reactions, and reactions are keyed by user. However, it doesn't disclose any auth/permission requirements or rate limits.

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

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

The description is a single, well-structured sentence that front-loads the core action and then adds constraints. It is appropriately sized and every clause adds value, though it could be slightly more organized with separators.

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

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

For a mutation tool with annotations covering safety and a 100%-covered schema, the description covers key behaviors like idempotency (existing reaction not added twice) and system message exclusion. However, it omits auth requirements, permission scope, and any side effects beyond the keying mechanism, leaving some contextual gaps.

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

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

Schema description coverage is 100% and the schema fully documents the 'reaction' enum with meanings and the 'remove' boolean. The description adds only that 'meanings in reaction', which is redundant with the schema. Since the schema already does the heavy lifting, 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 clear verb+resource: 'Adds or removes the token owner's reaction to a chat message - a textless reply.' This distinguishes it from siblings like chat_send or chat_read, though it doesn't explicitly name alternatives.

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

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

Usage is implied by 'Adds or removes' and the mention of system messages taking no reactions, but there is no explicit guidance on when to use this versus other chat tools like chat_send or chat_read.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral detail beyond that: hasMore signals direction of remaining messages, an empty page is the valid result for a task chat with no messages, and attachments carry an attachToken that can be reused in a spec/result.

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

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

A single dense paragraph, front-loaded with the core behavior and direction semantics, with no filler sentences. It is slightly run-on, packing pagination, empty-page, and attachToken facts into one block, but every clause earns its place.

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

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

With no output schema, the description usefully previews return semantics (hasMore, empty page, attachToken) for a cursor-paginated read tool. Given the read-only annotations and full schema coverage, an agent has everything needed to call it correctly; only the exact response shape is unspecified.

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

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

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds meaning by explaining that cursors come from a previous response and encode direction (after = newer, before = older). The limit and chatID parameters are left entirely to the schema, so it does not fully compensate beyond 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?

The description states a specific verb and resource ('Returns chat messages') and defines the scope precisely via cursor semantics (oldest-to-newest with a cursor, latest without). It is clearly distinguishable from the mutation siblings (chat_send, chat_message_delete, chat_message_update) by its read behavior, 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?

It gives concrete conditions for each mode: no cursor returns the latest messages, an after cursor returns newer messages (e.g. replies to a sent one), and a before cursor returns older messages. That is clear usage context for pagination, but it offers no when-not-to-use or sibling 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 readOnly=false and destructive=false. The description goes beyond them by disclosing the return payload (chatID, message, after cursor) and that the sent message can be edited or deleted within 60 minutes, plus the duplicate-risk caveat around the after cursor. It does not state permission requirements or rate limits, 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?

Five dense sentences with zero filler: addressing modes first, then when-to-use and when-not, then the dedup caveat, then the return value and edit window. Front-loaded and each sentence carries distinct 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 supplies the return shape itself. Combined with addressing semantics, usage boundaries, dedup guidance and the edit/delete window, an agent has everything needed to invoke this correctly against siblings like chat_read or chat_message_update.

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 text formatting rules, attachment limits and idempotencyKey is already documented. The description restates chatID/userID/replyMessageID semantics, which largely duplicates the schema rather than adding new 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 (sends) and resource (message) and immediately distinguishes the three addressing modes: chatID for a chat (task chat ID = task ID), userID for a DM, replyMessageID for a reply. An agent can tell exactly what this does and how it differs from chat_read, chat_reaction and chat_message_update.

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 intended cases (blocking questions, replies to messages addressed to the token owner, messages the user asks for) and the excluded cases (status updates, summaries, links to created items). It also warns that messages newer than the last read may already contain the same question or answer, which steers the agent to check chat_read before sending.

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 structurally. The description adds real value on top: omitted fields stay unchanged (PATCH semantics), module membership is unaffected, and it names what gets destroyed (the main Figma frame). It does not discuss reversibility or response shape, so not a 5.

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

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

Dense but front-loaded: the create/update/remove branching comes first, then the invariants, then the consent caveat. Each clause carries information. Slightly heavy as a single sentence but nothing is wasted.

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

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

For a multi-mode mutation tool with no output schema, the description covers the branching logic, side effects (frame removal, unchanged omitted fields, module membership), and the consent guardrail. What it omits is authorization mechanics and whether the frame removal is reversible, which would be the last gaps.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema by explaining parameter interaction: omitting componentID creates a new component requiring productID and title, while supplying it triggers an update. This conditional logic is not obvious from the flat schema alone.

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

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

The description states a specific verb+resource ('Creates a product component', 'updates a component's name and description', 'removes its main Figma frame') and spells out the branching condition that selects each mode. An agent can distinguish this from sibling module_update or product_update purely from the text.

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 precondition for use ('Only at the user's request or with their consent: the product structure belongs to the team'), which is strong when-to-use guidance. It does not name alternative tools or state when-not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, matching the 'Returns' verb, so the safety profile is covered. The description adds that the response carries both 'content' and 'rulesRevision', which is genuinely useful given there is no output schema. It stops short of noting auth needs or any other behavioral trait, so it lands at a solid-but-not-rich 3.

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?

Effectively two sentences, front-loaded with the core verb and resource, with no filler or marketing prose. The parentheticals ('(content)', '(rulesRevision)') are dense but each carries information. Slightly run-on syntax keeps it from a 5.

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

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

With no output schema, the description correctly compensates by naming the returned fields (content, rulesRevision). Both parameters are fully documented in the schema, and the task/work-type dependency is captured. What remains missing is explicit routing to the create tools this precedes, but the essentials for correct invocation are present.

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

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

Schema description coverage is already 100%, which sets the baseline at 3, but the description goes further by stating the conditional relationship: 'For a task, the template depends on its work type.' This explains why taskType matters and why it is required only when entity is 'task', adding rationale beyond the schema's bare 'required when entity is task' note.

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

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

The description uses a specific verb ('Returns') and names the concrete resources: the workspace's conventions and description template plus its revision (rulesRevision). It is distinguishable from siblings like feature_create/task_create because the description makes clear this fetches the rules rather than creating anything. The nested phrasing ('for a new feature, task or bug (content)...') is slightly hard to parse, and the tool name 'create_rules' implies a mutation, which the description must and does correct.

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

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

Usage is only implied: the phrase 'that creation requests carry' hints this is called before a create call, but the description never explicitly states when to use it versus siblings or names the alternative tool. No exclusions or prerequisites are given. An agent can infer the context but must do so itself.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description goes well beyond that with the rate source, the non-business-day fallback, the RUB-based cross-rate path, and an explicit rejection rule for future dates. It also discloses the return payload (rate and result rounded to 2 decimals), which is exactly the kind of behavioral detail 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?

Two sentences, front-loaded with the action and rate source, then a compact second sentence handling edge cases and the return shape. Every clause carries information — the fallback, cross-rate path, rejection rule, and rounding all matter to a caller.

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 takes on the burden of describing the return values (rate as units of to per 1 from, result rounded to 2 decimals), and it covers the tricky behavioral edges an agent would otherwise have to discover by trial. Nothing needed to call or interpret this tool is missing.

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

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

Schema description coverage is 100% and documents all four parameters, including the date default ('defaults to today in the company's time zone'), so the baseline is 3. The description clarifies the direction convention ('units of to per 1 from'), which helps interpret amount/from/to, but adds no syntax, format, or validation detail for the parameters themselves.

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 precise verb+resource ('Converts an amount between RUB, USD, EUR and CNY') and immediately pins down the scope: the Bank of Russia rate, the supported currency set, and the date basis. No sibling tool in the list does currency conversion, so there is no ambiguity to resolve and the purpose is fully self-contained.

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 supplies concrete usage conditions rather than leaving them to inference: non-business days fall back to the last business day's rate, cross rates route through RUB, and dates beyond tomorrow are rejected. It does not name alternatives or a 'when not to use', but no plausible alternative tool exists in this toolset, so the omission is minor.

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

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

Annotations only declare the generic profile (readOnly=false, destructive=false, openWorld=false), so the description usefully adds that the reply is "visible to everyone with access to the file" and that the server appends an "employee and agent" signature. These are non-obvious side effects that shape whether an agent should post. It does not say what the call returns or how failures surface.

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

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

Three compact clauses, front-loaded with the action and visibility, then sourcing, then the suitability rule. Every sentence carries information, though the sourcing clause reads as telegraphic shorthand.

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

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

For a mutation tool with no output schema, it covers visibility, the signature side effect, language/length expectations and when to refrain. The main gap is return behavior (e.g., the new reply's ID) and error handling, which an agent posting into a shared thread might 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 coverage is 100%, so the baseline is 3, but the description adds real semantics: "Source: url or designID" clarifies these two are alternative locators for the same thing, and commentID may be "the thread or a reply in it". That resolves ambiguity the schema alone leaves open.

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

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

The description opens with a specific verb and resource ("Replies in a Figma comment thread") and scopes the channel ("through the company's integration"). It is clear what the tool does, but it never names or contrasts with the obvious sibling design_comments, so an agent must infer the read-vs-write split 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?

It gives an explicit positive condition ("Suitable when a remark is fixed or the answer is unambiguous") and a negative one ("disputed points are left to the user"), which is real routing guidance. It stops short of naming an alternative tool to use for the disputed case, so it is clear context rather than a full when/when-not/alternative map.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, lowering the bar, and the description still adds real behavior: author.isIntegration flags already-sent replies, a later reply may cancel a remark, and the Figma API cannot mark threads resolved. The last point is a genuinely useful capability limitation. It does not describe pagination or response shape, so it is good but not exceptional.

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 dense sentences, front-loaded with purpose then source semantics then behavioral caveats. No filler. The middle clauses are slightly compressed but every sentence carries information.

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

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

For a read-only list tool with no output schema, the description covers purpose, source options, integration markers, and a key API limitation. It omits return ordering/pagination and does not explicitly route to design_comment_reply, so it is complete-ish but not fully self-sufficient.

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

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

Schema coverage is 100%, so all three parameters (url, status, designID) are already documented in the schema. The description adds scoping semantics (frame/page returns threads inside it, file returns all; designs key or design:<uuid> form), which is a modest value-add over the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource: 'Returns Figma design comments', enumerated as threads with author, date, text, replies, pinned node. Clear what it does. It does not explicitly name or contrast with its closest sibling design_comment_reply or design_import, so it stops short of full sibling differentiation.

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

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

Usage is implied by the source semantics (url vs designID) but the description never says when to use this versus design_comment_reply or design_import. An agent must infer that this is the read tool and design_comment_reply the write tool.

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

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

Goes well beyond the annotations (which only declare non-read-only, non-destructive, open-world). It discloses timeout-and-continue-server-side behavior, partial failure semantics ('a failed frame does not stop the others'), the 1-2 minute delay before designs appear, re-import refresh behavior, and the marker/designToken linkage side effect.

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 core purpose is front-loaded, but the body is a single dense, semicolon-chained block with nested parentheticals that is hard to scan. Every claim is substantive, yet it would benefit from structuring into distinct clauses or a short list.

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?

Despite having no output schema, the description documents the return contract per frame (status values, designID, designToken marker, error with an action for fixing). Paired with complete parameter coverage, an agent has everything needed to call and interpret the 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 the baseline is 3, but the description genuinely adds meaning: nodeID format with ':' (e.g. 12:34), moduleID/componentID setting a main frame with one frame and no marker, and the rule that a designToken in one entity links another entity on save.

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 ('Imports Figma frames') plus the target entities (task, bug, feature) and the integration it goes through. No sibling tool does this, and the agent can distinguish it immediately even without opening the schema.

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

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

Gives clear operational context: 'like pasting a design in the web app', batching guidance (up to 10 links; 2-3 large frames to stay within client timeouts), and the moduleID/componentID single-frame special case. It stops short of naming when NOT to use it or pointing to an alternative sibling, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds that the result spans live branches and commits by task keys, which hints at an aggregation over live repo state, but says nothing about auth scope, freshness, or cost of the cross-repo lookup.

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 what is returned, no filler. Slightly awkward phrasing ('a feature's code') but every clause carries content.

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

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

For a read-only tool with no output schema and fully documented parameters, the description covers what comes back well enough to invoke it. The remaining gap is disambiguation from the neighboring feature/task code-context tools, which is a routing concern rather than a call-correctness one.

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 both parameters are documented there, including the mutual exclusivity ('not with featureID' / 'not with key'). The description contributes nothing about key format or the alternation, so 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+resource ('Returns a feature's code') and enumerates the payload (tasks, repositories, branches, commits), so the agent knows it is an aggregate code-context fetch. However it never distinguishes itself from the very similar siblings feature_context and task_code_context, leaving a real ambiguity.

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

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

'Useful for checking a feature's spec against the implementation' gives one implied scenario but no explicit when-to-use rule, no exclusions, and no alternative named. With feature_context, task_code_context and repo_context all in the sibling list, the agent gets no routing help.

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

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

Annotations already declare the safe read-only, non-destructive, closed-world profile, so the bar is lower. The description adds real behavioral value beyond that: it explains that tasks/bugs come back as compact lines ordered by ord, that attachments carry file IDs, and that specRevision is 'the spec revision needed to edit the spec' – a non-obvious editing prerequisite.

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 purpose and then the return payload, with no filler. The enumeration is dense but every item earns its place by compensating for the absent output schema.

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

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

With no output schema, the description fully carries the burden of describing the return shape and does so exhaustively, while also noting the specRevision prerequisite for editing. Nothing an agent needs to call or interpret this tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (key and featureID) are already documented including the '#F12' format and the mutual exclusivity. The description restates 'by ID or key (#F12)' but adds no syntax or selection guidance beyond the schema, 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 ('Returns a feature by ID or key') and enumerates exactly what is returned: spec, gist, plan tasks, bugs, employees, designs, attachments, and specRevision. This clearly distinguishes it from sibling read tools like feature_list, feature_search, and feature_code_context.

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

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

Provides a concrete usage trigger: 'Useful when the user asks about a feature, its plan or who works on it (workAssigneeID).' However, it never names alternatives (e.g., feature_search or feature_list) or states when this tool should not be chosen, leaving sibling selection 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 only declare non-readonly/non-destructive. The description adds real behavioral context beyond them: the feature is visible to the team immediately, has no approval step, and no tasks are created by the server (design task only when modules need design, others on request). It also names the return values, which is meaningful given there is no output schema.

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

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

Three dense but front-loaded sentences covering purpose, side effects, and return values. Each sentence carries information, though the task-creation clause is a little compact and could be split for readability.

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

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

With no output schema, the description handily compensates by enumerating the returned fields (link, product, version, ord, specRevision). Combined with the side-effect disclosure and full schema coverage, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters including gist, ord, spec and rulesRevision. The description adds only indirect context via 'the feature creation template', so the 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+resource ('Creates a feature in a product version') and immediately distinguishes itself from sibling mutations like feature_update, feature_delete and feature_list. The agent can tell exactly what this does without opening the schema.

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

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

Gives a clear usage trigger ('when the user asks to add one'), which implies the when-not (not for modifying existing features). It does not explicitly name feature_update or other alternatives, so the guidance is clear but not fully 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 flag destructiveHint=true, but the description goes further: it discloses that deletion cascades to tasks and bugs, that it is a soft delete with no restore path, and that the response reports deletedTasks. This is exactly the behavioral context an agent needs before firing an irreversible operation.

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 clauses, each doing work — action, irreversibility precondition, return value — with the destructive scope front-loaded. 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 one-parameter destructive tool with no output schema, the description covers cascade scope, irreversibility, the calling precondition, and the return field. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100% and there is a single parameter (featureID) whose type is documented as a UUID, so the schema carries the burden. The description adds no format or semantic detail about the identifier, making the baseline 3 appropriate.

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

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

States a specific verb (deletes) and resource (feature) plus the cascade scope (all its tasks and bugs), which singles it out from siblings like feature_update, task_delete and task_relation_delete. An agent can distinguish 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 gating condition — 'only at the user's explicit request' — which is real usage guidance for a destructive tool. It does not name an alternative (e.g., feature_update for non-destructive changes), 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 cover the safety profile (readOnly, non-destructive, closed-world), so the bar is lower; the description still adds real behavioral context: results are in `ord` ascending, includeSpec yields a much larger response, allowDone gates completed features, and paging reuses nextCursor with the same parameters. That is meaningful disclosure 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?

Two dense sentences that lead with what the tool returns, then layer the optional parameters and paging. No filler; slightly clause-heavy but every clause carries information.

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

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

For a read-only paginated list with full schema coverage and annotations handling safety, the description covers ordering, filtering flags, response-size tradeoff, and pagination. Only the sibling-routing question (vs feature_search) remains open.

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 cross-parameter semantics the schema lacks: the coupling of includeSpec to spec/specRevision with a size warning, the allowDone filter effect, and the requirement that the next page use nextCursor *with the same parameters*.

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

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

States a specific verb (Lists) and resource (features of a product or one version), plus the web-order sorting (`ord` ascending), which immediately tells an agent what this returns. It does not name the closest sibling (feature_search) as the alternative, so an agent must infer the split between a paginated overview and a search.

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

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

"for an overview of what a product contains" implies the browse/overview use case, and the includeSpec/allowDone notes hint at when responses balloon. But there is no explicit when-to-use vs feature_search, no prerequisites, and no stated exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: how matching works (word forms, AI aliases, typo tolerance), what is returned (short entries with excerpt and score), and how pagination behaves (reuse the last item's cursor with the same query and filters).

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

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

Two dense sentences that front-load purpose and capability, with usage and return/pagination detail following. No filler, though the em-dash clause packs several distinct facts that could be split for scannability.

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

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

With no output schema, the description correctly compensates by summarizing the return shape (short entries with excerpt and score) and the pagination mechanism. Combined with the 100%-covered input schema and safety annotations, an agent has everything needed to call and page through 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 description coverage is 100%, so the baseline is 3 and the schema carries the parameter burden. The description adds genuine semantic value by explaining that the cursor must be paired with the same query and filters, which clarifies the pagination contract beyond the raw schema field descriptions.

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

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

States a specific verb ('Searches') and resource ('a product's features') and immediately specifies the matching strategy (by meaning in title, gist and spec) plus its capabilities (word forms, AI aliases, typo tolerance). This distinguishes it from sibling list-style tools such as feature_list or feature_context, which an agent can tell apart without opening a schema.

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

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

Gives a concrete usage context ('when the user asks to find a feature or where new work belongs'), which tells the agent the intent this tool serves. It stops short of naming an explicit alternative (e.g. feature_list) or stating when not to use it, so it is clear context without exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'writes nothing' — important because an 'apply' mode would otherwise read as a mutation. It also discloses that includeTaskIDs pulls full contexts with chats and that older chat messages are read via a cursor, which annotations do not cover.

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

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

The purpose is front-loaded in the first clause and the text is information-dense with no filler. It is a single run-on block of semicolon-separated clauses, which costs some readability, but almost every clause carries distinct content.

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

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

With 7 parameters at full schema coverage, a read-only profile already defined by annotations, and no output schema, the description supplies what is missing: return contents, the no-write guarantee, and mode semantics. Only the sibling-vs-sibling routing (task_spec_sync) is left implicit.

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 largely restates the schema's own wording for mode and includeTaskIDs ('full contexts with chats of tasks with discrepancies') rather than adding new format or interaction detail; basis and chatLimit get no description-side elaboration.

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 and resource: it 'Returns the context for updating a feature's spec from its tasks' and enumerates exactly what comes back (feature.spec, tasks[].spec, tasks[].result, guidelines). The phrase 'writes nothing' pins down the operation type and separates it from task_spec_sync and feature_update.

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?

Mode selection is spelled out: 'mode=analyze - differences and a full new version without saving; mode=apply - when the user asks to apply the update.' This gives a clear trigger for each mode, though it never names the obvious alternative (task_spec_sync) or states when not to reach for this tool.

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

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

It goes beyond the structured data to provide critical behavioral constraints, such as stating that it 'Changes shared team data' and explicitly detailing the 'only passed fields change' operational behavior.

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

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

Although slightly long, the description is highly efficient, front-loading the list of updates and immediately clarifying operational boundaries to prevent misinvocation.

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 (11 parameters, partial update logic, movement, and spec patching), the description is complete. It covers the 'what' and the 'how' of the update process.

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?

While schema coverage is 100%, the description provides highly specific domain knowledge for complex parameters like 'ord' (position logic) and 'spec' (Markdown replacement rules), adding significant value that cannot be inferred from the JSON schema alone.

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

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

The description provides an exhaustive list of all supported updateable attributes (title, spec, gist, version, analyst, position), making the tool's scope perfectly clear.

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

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

It clearly defines the 'only passed fields change' partial update behavior, distinguishing it from a full replacement. It also explicitly states a limitation: feature status transitions are not handled by this tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral detail beyond that: the group ordering rules (in-progress first, then urgent bugs/tasks, then bugs/tasks) and the non-obvious pool semantics for the token owner's own queue. It does not cover pagination or result caps.

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 return shape and grouping before the pool caveat, and every clause carries information. The includePool sentence is a long run-on that packs several conditions together, costing some readability.

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

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

No output schema exists, but the description explains the grouping, ordering and pool composition, which is essentially what the agent needs to interpret results. A read-only list tool with annotations covering safety is adequately specified; only pagination/size limits are unaddressed.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description genuinely enriches it: includePool is explained as the shared "any" pool matched to role and level, and that in the token owner's own queue it lists only tasks they can take — meaning not present in the schema text. statuses and userID are only lightly reinforced.

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

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

States a specific verb and resource (returns a person's queue in a product) plus scope (token owner's or userID's) and the grouping model. It is clearly distinguishable from siblings like task_search or worklog_list because it describes the assignee-stage grouped view and pool inclusion.

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 trigger: "Useful when the user asks what to work on next," which tells the agent the intent-level scenario. It does not name alternatives or exclusions (e.g. vs. task_search or worklog_list), 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?

With annotations already declaring readOnlyHint=true, openWorldHint=false and destructiveHint=false, the description still adds substantial context not in the structured fields: a concrete 5242880-byte inline ceiling, which content types are and are not returned inline, the access-control model, the stale-design-file-ID replacement behavior, and the deleted-attachment semantics. This is a genuine value-add 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?

Three dense sentences, front-loaded with the primary purpose before the constraints and edge cases. Each sentence carries information, though the last two are run-on enough that they read as a spec dump rather than cleanly parsed guidance.

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 explains what is returned inline and what is not, plus the access and stale-ID edge cases. It is nearly complete, but it does not say whether an oversized or excluded file yields an error, a link, or empty content, and there is no pagination or streaming note.

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

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

Schema coverage is 100% and the schema already enumerates the three fid forms (attaches key, attach:<fid>, design file ID), so the baseline is 3. The description goes further by explaining the failure semantics of those forms — a design file ID that is no longer found was swapped by a re-import, and an attach token missing from attaches indicates deletion — which meaningfully extends the parameter's behavior.

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

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

The description opens with a specific verb+resource: 'Returns a file's content by fid', then narrows the scope by return mode (image as image, text as text) and size ceiling. It is distinct from file_upload and file_url in effect, but it never names or contrasts with the sibling that overlaps most (file_url), so sibling differentiation is left to inference.

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

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

It gives clear operational context: access is governed by the items the file is attached to or the token owner's own upload, and an attach token with no entry in attaches means the attachment is gone. What it lacks is explicit routing against alternatives (e.g. when to use file_url instead), so it stays at clear-context rather than explicit when/when-not.

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

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

Annotations only cover readOnly/destructive/openWorld, so the description carries the real behavioral load and does so well: size cap (2097152 bytes), the two-phase PUT flow with a literal curl example, the need for a follow-up completion call, and the no-delete limitation. It omits permission/auth requirements and what the response contains, but the added behavioral context is substantial.

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

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

Front-loaded with the purpose, then the two flows, then the limitation—a logical order with no filler sentences. It is a single dense paragraph with run-on clauses (multiple semicolons) that hurt scanability slightly.

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 genuinely two-phase upload tool with no output schema, the description explains the mechanics but references three variables (attachToken, uploadURL, maxSize) that appear nowhere in the schema or its own text, so an agent cannot tell how to obtain them. That missing entry point is a real gap despite otherwise rich coverage.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relationship semantics the schema lacks: attachToken routes to task/bug/feature specs while fid routes to chat message attachments, and one fid can be attached in several places. The size and base64 details duplicate the schema rather than extend 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 ("Uploads a file for attachment") and immediately scopes the two attachment destinations, so an agent knows this creates/stores content rather than retrieving it. It does not name the siblings it must be distinguished from (file_get, file_url), so an agent still has to infer the boundary from context.

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 splits the two usage modes: with dataBase64 the file is saved at once, without it any-size uploads go through a PUT to uploadURL followed by a completion call. It also states a hard exclusion ("Files cannot be deleted through MCP"). It never says where attachToken/uploadURL come from or which sibling produces them, leaving the entry condition implicit.

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 and destructiveHint=false, and the description adds real behavioral context beyond that: the URL is signed and time-limited, downloadURL may be null depending on storage, access is inherited from the items the file is attached to, and attachToken can be used as-is in a spec/result. This is a meaningful disclosure layer over the safety annotations, though it doesn't cover URL lifetime values or error behavior.

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

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

Front-loaded with the return payload, then edge cases and the attachToken note. It is dense and mostly earns its clauses, though the long single sentence with semicolons could be split for faster scanning.

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 explain returns, and it does: the metadata fields returned, the signed download URL, and the null-downloadURL case. Combined with the access-model note, 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 coverage is 100% and the single fid parameter is fully documented in the schema (attaches key, fid in attach:<fid>, or design file ID). The description only repeats 'by fid' without adding format or resolution semantics, 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 a file's metadata ... and a signed, time-limited download URL by fid') and scopes the resource set ('video, archives, design assets and other files not returned inline'), which implicitly separates it from the inline-retrieval sibling file_get. An agent can pick this tool without opening either schema.

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

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

Gives clear context for when to use it (files not returned inline: video, archives, design assets) and covers key edge cases (downloadURL null where no signed links exist, design file IDs replaced by re-import). It never names file_get or file_upload explicitly as the alternative, so routing is inferred 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 confirm this is a non-read-only, non-destructive, closed-world write, and the description adds genuinely new lifecycle semantics: the record starts personal and unverified, is immediately visible to the token owner's agents, and a moderator can promote it to shared. It also flags the secrets caution. It stops short of describing authorization requirements or failure modes.

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

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

Two sentences, front-loaded with the action and the trigger, then the scope semantics. Dense but every clause carries information; the second sentence is long yet justified by four distinct scope values.

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

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

For an 8-parameter mutation tool with no output schema, the description covers purpose, trigger, visibility lifecycle and scope semantics, which is most of what an agent needs. Remaining gaps — the conditional level/ID relationships and duplicate-handling behavior — are covered by the schema or left implicit.

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 88%, so the baseline is 3, but the description adds real meaning by spelling out each `level` value (company/user/project/repository with examples) even though the schema leaves `level` undescribed. It does not expand on projectID/productIDs/repositoryID conditionality beyond what the schema states.

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

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

States a specific verb and resource — 'Saves a confirmed fact, rule or recipe as an agent memory record' — and scopes it to persistent knowledge for future agent work. This clearly separates it from memory_read/memory_list/memory_update among the siblings.

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

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

Gives a clear trigger condition ('when the user asks to keep knowledge for future agent work') plus an important restriction ('secrets only at the user's direct request'). It does not name alternatives such as memory_update or create_rules, so the agent must infer when updating an existing record is preferable to creating one.

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

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

Annotations already declare destructiveHint=true, so irreversibility is covered. The description goes further by disclosing two behaviors annotations cannot express: the per-role authorization model and optimistic concurrency ('Rejected if the record changed since the given version').

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

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

One dense sentence with the core action front-loaded, then permissions, then the failure condition. Effectively sized, though the colon-list construction takes a beat to parse.

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

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

With only two parameters, no output schema, and annotations carrying the safety profile, the description covers purpose, authorization and failure mode. Only a note on the success return (e.g. empty body) is absent, which is a minor 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 the baseline is 3; the description earns a bump by explaining why 'version' exists (stale-write rejection), which the schema's terse 'Record version the change is based on' does not convey.

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

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

Names a specific verb (Deletes) and resource (an agent memory record), and is immediately distinguishable from siblings memory_create/read/update/list. An agent knows exactly what this does without opening the schema.

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

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

Supplies the operative conditions for a legitimate call: authors may delete their own records, moderators (memory:moderate) may delete any but user-level records. No alternative tool is named, but for a delete operation the alternative space is self-evident.

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/destructiveHint=false, and the description adds real context beyond them: the return statistics (deliveredCount, readCount, lastUsedDT) and the permission-dependent scope where memory:moderate expands coverage to all company records except personal ones.

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

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

Front-loads the core action, then statistics, then use cases. It is dense and semicolon-heavy in the second half but every clause carries information; 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 12 params and no output schema, the description usefully names the returned statistics and explains the permission-scoped coverage, which compensates for the missing output schema. Remaining filter semantics are left to the schema, which is acceptable.

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

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

Schema coverage is 67%, and much of what the description says about verified, sort, and unusedDays restates the schema. Its incremental value is combining them ('sort = usage with unusedDays') and implying level scope, but many of the 12 parameters (IDs, jobs, load, query, shared, authorUID, projectID, repositoryID) get no semantic help.

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 ('Lists agent memory records visible to the user') plus the scope of visibility, and it clearly differentiates from siblings like memory_read, memory_create, and memory_update by framing it as a filtered list with usage statistics.

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

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

Gives concrete use cases (finding duplicates before saving, reviewing, moderating, cleaning up) and conditional semantics (verified = false is the moderation queue; sort = usage with unusedDays finds rarely used records). It does not explicitly name an alternative tool to use instead, which keeps it 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 read-only, non-destructive, closed-world semantics, so the safety profile is covered. The description adds real behavioral value beyond that: records come back 'in full' and 'unavailable IDs come in notFound', telling the agent how partial or missing input is handled.

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

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

Two tight sentences with zero waste. The core action and ID semantics are front-loaded, and the usage hint plus notFound behavior follow without padding.

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

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

For a single-parameter read tool with full schema coverage and annotations carrying the safety profile, the definition is essentially complete: it explains identifiers, completeness of results, and missing-ID handling. Without an output schema it could say a touch more about the return shape, but nothing needed for correct invocation is missing.

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

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

Schema coverage is 100% and the schema description already states 'Rule slugs or memory record UUIDs'. The description largely repeats this, only adding the concrete slug example `git`, so it sits at the baseline for a fully documented schema.

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

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

States a specific verb ('Returns') and its two resources (agent memory records and MCP rules), and clarifies the input shape ('in full by ID'). It is clearly distinguishable from sibling memory_list, which enumerates rather than resolves by 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?

Gives an implied usage condition ('when a record from the `memory` index is relevant to the user's task') but no explicit when-not guidance and no named alternative (e.g. memory_list for browsing). Enough to orient the agent, but routing between memory_* siblings 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?

Goes well beyond the annotations (destructiveHint/readOnlyHint) by disclosing replacement semantics, optimistic concurrency ('rejected if the record changed since the given version'), permission rules, and the side effects of an author edit (record becomes personal and unverified again) versus a moderator edit (flags retained). These are exactly the mutation consequences an agent needs before invoking a destructive 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-loaded with the core action before branching into permission and flag-retention details, and every clause carries meaning. It is dense and semicolon-heavy, but not padded given the tool's complexity.

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 destructive mutation with no output schema, it covers permissions, concurrency, and flag behavior well. It omits only minor operational guidance, such as how the caller should obtain the current version or what a rejection looks like.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds update semantics the schema does not express: which fields are replaced wholesale and that setting level/projectID/repositoryID relocates the record. It still does not explain interplay such as what happens when productIDs is omitted.

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 ('Updates an agent memory record') and immediately clarifies the update mode ('passed fields are replaced; a new level, projectID or repositoryID moves it'). This is clearly distinguishable from siblings memory_create, memory_delete, and memory_read.

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 strong context for when and by whom the tool may be used, including the author-vs-moderator permission split and the memory:moderate requirement. It does not, however, explicitly route the agent to alternatives such as memory_read for fetching the current version before calling this tool.

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

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

Annotations already flag destructiveHint=true, but the description adds substantive behavior: partial-update semantics ('omitted fields stay unchanged'), the destructive effects (removing components, removing the main Figma frame), and a consent/permission precondition not present in annotations. It stops short of describing reversibility or what happens to child modules.

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 packed sentences with the create/update distinction and required-field rule front-loaded. The consent clause is a short, high-value second sentence, though the field enumeration after 'or updates a module's' is dense enough to read as a list dump.

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

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

For a destructive mutation tool with no output schema and a fully documented input schema, the description covers the create-vs-update branch, patch semantics, side effects, and the consent precondition. It omits permission/auth specifics and the fate of existing children, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely new information: productID and title are required for creation (the schema reports zero required params), and it ties moduleID omission to the create path. The remaining parameter notes (design=null, parentID=null) largely restate the schema.

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

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

States two specific verbs (create/update) on a specific resource (product module) and enumerates updatable fields: name, description, parent, components, and Figma frame removal. It clearly distinguishes itself from siblings like product_update and component_update by naming the 'prime module' resource.

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

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

Provides a real usage constraint — 'Only at the user's request or with their consent' — which tells the agent when it must not act unilaterally. However, it never routes between create vs. update against alternatives such as product_update or product_modules, and it does not state the condition that selects the create branch beyond 'without moduleID'.

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 confirm this is a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), yet the description layers on rich disclosure: the 44k character truncation rule and how a non-fitting note is surfaced, that memoryOtherJobs holds counts for other kinds of work, that QA devices are full with 'qa' and brief with 'dev'/'analysis', and that variables resolve by level precedence (most specific wins). These are non-obvious behaviors an agent must know and are not derivable from the schema or 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?

Content is front-loaded with the core return shape and almost every clause carries information (no filler), which is appropriate for a tool with this many conditional branches. However it is delivered as one dense run-on paragraph with nested parentheticals and semicolon-chained conditionals, making it hard to parse and forcing the agent to re-read to extract the mode-specific rules.

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

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

There is no output schema and this is a complex five-parameter tool with conditional return shapes, so the description must carry the full burden of explaining what comes back — and it does, covering spec, memory/notes, qaDevices, repositories and variables including truncation and precedence rules. An agent has enough to call it and interpret the response 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 already 100%, so the baseline is 3, but the description adds meaning tied to parameters: that 'job' controls which conventions/notes are returned and the detail level of qaDevices, that 'runKey' prevents memory being repeated at take and pulls in task conventions in full, and that 'localRepositories' affects repository notes specifically for dev/review/devops while having no effect on analysis/qa/design.

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

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

The description opens with a specific verb and resource: 'Returns a product's working context', then enumerates exactly what that context contains (project, spec excerpt, analyst/lead, versions, repositories, design files). It is far more specific than a tautology, but it never names a sibling (feature_context, task_context, repo_context, product_list) to help an agent disambiguate among the many *_context and *_list 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 extensively explains how behavior changes conditioned on 'job', 'runKey', 'includeSpec' and 'localRepositories', which implies when each mode is appropriate (e.g. dev vs qa vs design for memory and qaDevices detail). However, it never states when to call product_context instead of another context tool, nor any exclusions or prerequisites beyond the runKey note.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds a genuine behavioral fact beyond the annotations: archived products are filtered out of the result, which materially affects what the agent sees. It does not describe result shape or ordering, keeping it out of 5 territory.

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

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

Two short sentences, roughly 25 words, with the core behavior and exclusion rule front-loaded ahead of the usage hint. Every clause carries information and nothing is repeated from the schema.

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

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

For a single-optional-parameter read tool with no output schema, the description covers what is returned at a high level (projects with their active products) and the narrowing filter, which is sufficient to call it correctly. It omits any indication of the returned field shape or pagination, a minor gap rather than a blocking one.

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 projectID field is already documented as 'Optional: return only this project's products.' The description's 'projectID narrows the list to one project' restates that in prose rather than adding format, defaulting, or edge-case 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 ('lists projects with their active products') plus an explicit scope rule (archived products excluded), so the agent knows exactly what set comes back. The closing clause 'useful for choosing the product to work in' implicitly separates it from deeper siblings like product_context and product_modules, which fetch details for an already-chosen product.

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?

'Useful for choosing the product to work in' gives a clear selection/discovery context for when to reach for this tool, which is the natural entry point before product_context or product_modules. It stops short of naming those alternatives or stating any when-not conditions, so it does not reach a 5.

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

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

Annotations already declare readOnlyHint=true and non-destructive, so the safety profile is covered. The description adds real behavioral semantics beyond that: desc and design are returned ONLY for items listed in IDs, and 'a module does not imply its components' is a non-obvious structural caveat an agent would otherwise get wrong.

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?

Information-dense and front-loaded with the main return, but the single run-on sentence mixes return contents, structural caveats, and filter behavior with heavy abbreviation (snapshotFID, contextFID), which is not optimally scannable.

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

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

With no output schema, the description carries the burden of describing return shape and does so reasonably (modules vs components, desc/design gated on IDs). Combined with annotations covering the read-only nature, it is largely complete, though the design/Figma fields remain opaque.

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. The description largely restates this (IDs controls desc/design return, query filters by name) rather than adding new format or syntax detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns the product structure ... modules ... and components'), which clearly distinguishes it from siblings like product_list and product_context. The parenthetical jargon (componentIDs, snapshotFID/contextFID) muddies the read a little, but an agent can tell what this tool fetches.

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 it is useful ('for tagging tasks and bugs') and explains how IDs and query filter output, but never names or contrasts an alternative (product_context, product_list, module_update). Usage is inferred 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 and destructiveHint=true, so the safety profile is covered; the description goes further by disclosing the archive cascade ('moves it to the archive with its versions, features and tasks, taking them out of work selection') and the partial-update behavior. It stops short of permissions, reversibility, or rate-limit detail, so it is strong but 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?

Front-loaded with the core action, then the partial-update rule, then the archive side effect; no filler sentences. The archive sentence is dense but every 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?

For a 10-parameter destructive mutation with a fully documented schema but no output schema, the description covers scope, consent, and the most dangerous side effect. The return value is only gestured at ('returns its updated context'), which is the one remaining 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, but the description adds a meaningful global rule the schema does not state per-field: only explicitly passed fields are changed. That materially affects how an agent treats the nine optional parameters.

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

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

States a specific verb and resource ('Changes a product') and adds the partial-update scope ('only the passed fields') plus the return ('its updated context'). It is clearly distinguishable from read-only siblings like product_context or product_list, though it does not name any 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?

Provides an explicit precondition: 'only at the user's request or with their consent,' which tells the agent when this mutation is permitted. It does not, however, point to alternatives (e.g., product_context for reads) or state when not to use it beyond the consent rule.

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/destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: a 204800-byte cap, the startLine/endLine escape hatch for large files, and the caveat that renames are not tracked.

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 operation front-loaded and no filler. Dense but every clause carries information; only minor compression could improve it.

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 return content, and it does so (ranges attributed to a sha; commits with title, message with task keys, author, dates). The size limit and rename caveat round out what an agent needs before calling.

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 slightly beyond by explaining that startLine/endLine exist to page through large files and implying ref selection semantics via the fix-commit-parent example, adding intent the schema text 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 and resource: 'Returns line-by-line blame of a file at a ref', and enumerates the two output groupings (ranges and commits). This is clearly distinct from repo_history/repo_search in intent, though the near-sibling repo_line_history is never named or contrasted.

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 implied usage scenario ('Blame at the parent of a fix commit shows the lines as they were before the fix'), which helps the agent reason about ref selection. It does not state when to prefer this over repo_line_history or repo_history, so the routing guidance is only implied.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), yet the description adds substantial operational detail: page size of 153600 bytes, next-page offset semantics terminating at null, new-version line numbering, and the error-plus-baseSha/toSha shape for oversized files. This is well beyond what the structured fields provide.

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

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

Front-loaded with the core purpose, then layered with progressively finer detail (mode, line numbering, pagination, errors). It is dense, but each clause carries distinct operational information and little 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?

With no output schema and nine parameters, the description does the heavy lifting for return values — patch lines, line numbering, pagination termination, and error shape are all covered. It is slightly thin on how path/extensions filtering affects returned content, but otherwise complete for calling the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully extends several parameters: it clarifies from/to as refs with merge-base defaulting, explains straight's effect on the comparison base, describes the offset chaining to nextOffset, and states that line numbers are new-version. That is real added meaning over the schema text.

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

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

States a concrete verb and resource ('Returns the diff between two refs') with the important nuance of merge-base vs straight comparison. It doesn't explicitly name which siblings it is not, but 'diff between two refs' is a unique resource among the repo_* siblings, so an agent can still distinguish it.

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

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

It implies usage by contrasting default merge-base behavior ('as in an MR') with the straight mode ('e.g. a previous review's sha'), which hints at when each applies. However, it never says when to choose this tool over repo_history, repo_file, or repo_search, so guidance remains 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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds real behavioral context beyond them: README is truncated to 16384 bytes, the technical passport is explicitly flagged as stale/possibly outdated, and reads at a sha are served from cache. It does not cover failure behavior (e.g. invalid or inaccessible repositoryID), which keeps it from a 5.

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

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

One sentence with a colon-delimited payload list, front-loaded with the core purpose before the field enumeration. Dense but every clause carries information; it could have been split for readability but nothing is wasted.

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

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

For a single-parameter read tool with no output schema, the description substitutes well for one by enumerating the returned fields, and it flags truncation, staleness and caching. Missing only error/edge-case behavior and whether any permissions are required to read the repository.

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

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

The schema has a single parameter at 100% description coverage ('Repository ID.'), so the schema already carries the semantics and the baseline is 3. The description adds nothing about the parameter itself (format is only implied by the uuid type in schema), so no credit above baseline.

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

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

The description states a specific verb and resource ('Returns an overview of a product repository') and then enumerates exactly what that overview contains: git provider, URL, default branch and sha, linked projects, access level, README head, technical passport. That enumeration effectively separates it from sibling read tools such as repo_file, repo_tree or repo_search, but no sibling is named explicitly, so it stops short of a 5.

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

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

'Useful for an unfamiliar repository' gives one clear usage context, which is more than nothing, but there is no explicit when-not guidance and no alternative tool is named (e.g. repo_tree or repo_file for targeted reads). Usage is implied rather than routed.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the 204800-byte response cap, the totalLines return so large files can be paged with startLine/endLine, and per-part error isolation in a multi-part read. It does not cover auth or permission expectations, but adds substantial value over the annotations.

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

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

Front-loaded with the core purpose and packed with useful detail in one dense block, with no filler sentences. It is somewhat run-on, bundling limits, heuristics, and error behavior into a single breath, 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 no output schema, the description carries the return-value burden, and it does so by naming totalLines and the per-part error behavior. Combined with the byte cap and mode enumeration, an agent has enough to invoke it correctly; only auth/permission expectations and content formatting 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 the baseline is 3, but the description earns above it by explaining semantics the schema does not: symbol resolves a function/class/method/type declaration including its leading comment and is 'found heuristically', startLine/endLine enable range reads because of the byte cap, and files is capped at 20 parts. These add genuine meaning beyond the field descriptions.

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

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

States a precise verb (Reads) and resource (files at a ref), and immediately enumerates the two operating modes: single file via path, or up to 20 parts via files, each being whole-file, line range, or declaration. This distinguishes it cleanly from siblings like file_get, repo_search, or repo_blame.

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 mode descriptions (single file vs multi-part, ranges for large files), but there is no explicit when-to-use-this vs an alternative sibling, and no statement of when not to use it. The agent can infer intent but must reason about it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value on top by disclosing the pagination mechanic ('hasMore marks a next page') and the shape of returned fields. It omits auth/rate-limit details, hence not a 5.

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

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

A single front-loaded sentence naming the core action first, then the returned fields and pagination flag. It is dense but waste-free; the field enumeration is slightly list-like but each item is informative.

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

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

With no output schema, the description carries the return-shape burden and does so well, enumerating returned fields (message, author, dates, parents, taskKeys, tasks) plus the hasMore pagination signal. Missing only ordering guarantees and error behavior, so it is nearly complete for a read-only history 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 ref, page, perPage, path and repositoryID. The description restates the target as 'ref, file or directory' but adds no syntax or semantics (e.g. ordering, sha format) beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('returns the commit history of a ref, file or directory') and grounds it with the 'like git log' analogy, which is immediately legible. It scopes the target (ref vs file vs directory) clearly, though it never names the closest siblings (repo_line_history, repo_blame) to disambiguate at the line level.

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 git log analogy implies when this is the right tool and the schema defaults (ref defaults to default branch, path defaults to whole ref) are surfaced, giving implicit usage context. However there is no explicit when-to-use/when-not guidance and no routing to alternatives like repo_line_history or repo_blame.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description adds value by disclosing linkType semantics (message vs branch), the match=path case with no line ranges, the caveat that lines shift so results are candidates, and the 100-commit truncation. It stops short of explaining the return structure or pagination beyond truncation.

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

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

The action is front-loaded and every clause carries information (scope, ordering, linkType, caveat, cap). It is a single dense sentence with stacked parentheticals, which slightly hurts parseability, but there is little waste.

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

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

With no output schema, the description carries the burden and does so well: it describes what is returned (who, task, commits), ordering (newest first), filtering (task-linked only), and truncation behavior. The main gap is the absence of explicit tiering against sibling tools, but for a leaf-level query tool it is close to 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 five parameters including startLine/endLine, limit, path, and repositoryID. The description references startLine-endLine but adds no syntax or default detail beyond what the schema provides, so the 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 ('Shows who changed lines startLine-endLine of a file and in which task') with scope qualifiers (across all branches, task-linked commits only). This is clearly distinguished from siblings like repo_blame (line attribution) and repo_history (commit log) by the explicit line-range + task-attribution framing. An agent can select it without opening the schema.

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

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

It implies when the tool applies (querying task-attributed changes on a specific line range) and states real limits ('only task-linked commits are included, up to 100'). However, it never names an alternative such as repo_blame or repo_history, nor states when-not to use it, so routing guidance is only implied.

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

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

Annotations already carry the safety profile (readOnly, non-destructive, closed-world), and the description layers on real behavior: result format, a hard cap of 200 lines and 50 files per query that silently truncates, empty-result-means-no-match semantics, and default case-insensitivity. It does not cover authorization, rate limits, or whether truncation is signalled in the 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?

Purpose is front-loaded in the first clause, followed by a compact colon-list of parameter semantics and the limits clause. The result is one dense sentence that reads as slightly run-on, but for an 11-parameter tool with no output schema nearly 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 compensates by specifying the return line format and the truncation ceiling, and annotations cover the safety profile. Remaining gaps are minor: no pagination/continuation story beyond truncation and no note on what happens when both query and queries are supplied.

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 interaction semantics the schema cannot express: regex filters query matches when query is present yet scans files under path when it is absent, and queries accepts up to 10 strings. It also restates query as literal and case-insensitive by default, which corroborates rather than merely repeats the schema.

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

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

States a specific verb (Searches) and resource (code at a ref) and anchors it with the 'like git grep' analogy plus the concrete `path:line: text` output shape, which lets an agent separate it from repo_file or repo_tree. It never names a sibling tool or states what it is not, so it falls short of the explicit sibling differentiation a 5 requires.

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

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

Usage is only implied: the query/regex/queries clauses tell an agent how to combine parameters, and the truncation note hints at scope, but there is no 'use this instead of repo_context when...' routing guidance. With ~60 sibling tools including several repo_* readers, that omission leaves selection to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior: a 500-entry cap, permissible depth of 1-4 levels, truncation when cut off, and that the response carries the resolved sha. That is real operational 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?

A single front-loaded sentence with no filler; every clause carries information (entry cap, depth range, truncation, resolved sha). It is dense rather than strictly minimal, but nothing is wasted.

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

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

With no output schema, the description usefully notes the response includes the resolved sha and discloses the 500-entry cap and truncation behavior. Combined with 100% schema coverage, an agent has enough to call it correctly, though ordering/pagination semantics of the returned tree remain implicit.

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 four parameters are already documented in the schema, which sets the baseline at 3. The description restates depth (1-4) and the ref/path scoping but adds no format or syntax detail beyond what the schema already provides.

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

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

States a specific verb and resource ('Lists a repository directory at a ref'), and the scope is concrete enough that an agent can immediately tell this is a tree/listing operation. It does not explicitly contrast itself with near siblings like repo_file or repo_search, so it stops short of a 5.

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

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

No when-to-use guidance and no alternatives named. The agent gets no signal about when to choose repo_tree over repo_file, repo_context, or repo_search, even though these siblings overlap heavily in the repository-exploration space.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real behavioral context: expiresAt can be null (no expiry), and only 'short non-secret environment variables' have their values exposed, which is a meaningful disclosure about what is and is not returned. It stops short of describing freshness, caching, or cost.

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

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

The content is dense and mostly earns its place, but it is delivered as long run-on sentences that stack clause after clause ('Also... Also...') with no structure. Front-loading is adequate — the primary return set leads — but a bulleted breakdown of the three return groups would be far more scannable.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly, covering identity, scopes, privileges, expiry, memory index, and variables. What it omits is routing context relative to the many sibling context tools, which an agent in this dense tool namespace would need.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter noise and instead spends its words on return content.

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

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

The description states a specific resource (session/token context) and enumerates the exact fields returned: token owner, company, language, scopes, privileges, expiry, memory index, and variables. An agent knows precisely what this tool yields. It never distinguishes itself from sibling context tools such as product_context, task_context, or repo_context, so it stops short of a 5.

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

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

There is no statement of when to call this versus the many sibling context tools (product_context, task_context, repo_context, memory_list). The trailing sentence 'In work on a task, the variables of the product context apply' gestures at context layering but does not tell the agent when this tool is the right choice or what prerequisites exist.

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 and destructiveHint=false, so safety is covered. The description adds real behavioral value beyond that: it discloses the response composition and a caveat that review threads stay at the git provider. It stops short of noting pagination, auth, or size limits.

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

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

Two tightly packed sentences: verb+resource and the content list are front-loaded, followed by the call-for-action. Despite enumerating many items, no sentence is wasted.

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

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

With no output schema, the description carries the return-value burden and does so thoroughly, listing repositories, branches, commits, MRs, and hints. Nothing an agent needs to call this read-only tool correctly is missing.

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

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

Schema description coverage is 100%, so both ID and key are already documented in the schema. The description adds nothing about identifier selection or syntax, so the baseline 3 for schema-fully-covered parameters 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 ('Returns') and resource ('a task's code') and then enumerates the exact contents: product repositories, live branches, commits with stats/paths, MRs, and reading hints. This clearly distinguishes it from siblings like task_context and feature_code_context.

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 an explicit usage scenario: 'when the user asks how a task is implemented or wants it reviewed.' Clear context for selecting the tool, but it names no alternatives or exclusions (e.g., task_context vs feature_code_context vs repo_context), so the routing is left partly 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/destructive=false, so safety is covered; the description goes further by disclosing the shape of the return (gist staleness, relations semantics, allowedActions, specRevision) and an edge case ("raw design links without a designs entry are not imported"). It omits auth and rate-limit behavior, so not a 5.

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

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

Purpose is front-loaded in the first clause, but the body is a dense run-on enumerating return fields in one sprawling sentence. Given there is no output schema, the length is somewhat justified, but it is hard to scan.

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

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

With no output schema, the description must carry return documentation, and it does so thoroughly, covering spec, gist, relations, designs, and attachments for a tool with nested objects. Minor gap on chat pagination/ordering behavior beyond what the schema states.

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

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

Schema coverage is 100%, so the schema already documents all six parameters. The description adds only marginal linkage, tying includeFeatureSpec to feature.spec and "ID or number" to the ID/key pair; it says nothing about the chatAfter/chatBefore/chatLimit pagination object semantics.

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

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

States a specific verb+resource ("Returns a task or bug") with a precise scope ("by ID or number (unique within the company)") and enumerates the returned domain fields. An agent can distinguish it from a write like task_update, but no sibling tool is named to sharpen the boundary against task_search or task_evaluation_context.

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?

"Useful when the user mentions a task number or asks about a task" gives an implied trigger but no when-not or alternative routing. With siblings such as task_search and task_evaluation_context present, the description never tells the agent which to pick.

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

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

Annotations only declare the safety profile (not read-only, not destructive, closed-world); the description adds substantive behavior: creation yields an unpublished draft, the draft is published separately on request, a stale rulesRevision is rejected, and spec must conform to the template for the type. It also notes the return payload, which no output schema covers.

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

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

A single dense paragraph that front-loads purpose and then walks placement, assignees, and returns in a logical order. Every clause carries information, though the long compound sentences are heavier than ideal.

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 20-parameter mutation tool with no output schema, the description covers the critical unknowns: draft/publish lifecycle, template revision validity, placement selection, assignee semantics, and the returned link/status/transitions. Coverage is solid, though optional fields like ord, labels, or time plan rely on the schema alone.

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 meaningfully enriches it: it explains what rulesRevision represents, that spec is validated against the type's template, how to choose among the four placement params, and that stage assignees accept an employee uuid, "any", or null. That is real meaning beyond the raw 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?

Opens with a specific verb+resource ("Creates a task") and immediately disambiguates from the obvious sibling with "(not a bug)". It also states the draft-only creation model, which distinguishes it from task_publish and task_update.

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

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

Gives a clear decision rule for placement (featureID/featureKey preferred, versionID when no feature fits, productID as backstop) and implies the follow-up publish step via task_publish. It lacks an explicit named alternative (e.g. bug_create / task_publish) but the context is unambiguous.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds the crucial nuance that deletion is soft but unrecoverable ('no way to restore the task'), which materially informs an agent beyond the binary destructive flag.

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 earning its place: what it deletes, the irreversibility constraint, and the usage boundary. Front-loaded with the action and no redundant filler.

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

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

For a two-parameter delete tool with full schema coverage and annotations, the description supplies the key missing behavioral detail (soft delete with no restore). No output schema exists, and nothing an agent needs to call it safely is absent.

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 ID and key fully documented in the schema (ID preferred over key). The description adds no parameter-level detail, which is acceptable given the schema already carries that information.

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 ('Deletes a task or bug') plus scope ('shared team data'). The closing line explicitly distinguishes deletion from finishing work, separating it from the sibling task_done without requiring schema inspection.

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 conditions use on the user's direct request and warns that finishing work is not deletion, giving clear when-to-use and when-not-to-use guidance. It stops short of naming the alternative tool (task_done) that should be used instead.

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

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

Annotations already declare destructiveHint=true, so the mutation is known. The description goes beyond them by disclosing server-side effects: it makes the transition, closes the worklog, and calculates cost from the start/end snapshots, plus that 'done' returns the feature plan. Missing only notes on reversibility/failure modes.

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

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

The core action is front-loaded in the first clause, followed by the outcome list and server behavior. Dense but each sentence carries information; the long outcome enumeration is justified by the four-way branch the agent must pick.

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 11-parameter mutation with nested objects and no output schema, the description covers purpose, outcome branching, and server-side effects adequately, and the schema fully documents parameters. It leaves the prerequisite (task must already be taken) and any error/rollback behavior to inference.

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

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

Schema coverage is 100%, so the baseline is 3. The description earns a bump by giving the meaning of each outcome enum (done/return/wait/close) and the side effect tied to 'done', which the bare enum listing does not convey; it does not otherwise add syntax beyond the schema.

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

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

States a specific verb and resource ('Finishes the work on a taken task') and prefaces it with the scope ('shared team data'). The phrase 'a taken task' implicitly routes the agent away from task_take/task_create/task_update, so the tool's role in the flow is clear 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?

Enumerates the four outcome variants with the condition that selects each (done = accepted and task moves on; return = sent back with a required message; wait = part done, waits in queue; close). That is strong in-tool selection guidance, but it never names a sibling alternative or states a prerequisite (e.g. task_take must run first) explicitly.

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

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

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false); the description adds real behavior: one evaluation per stage, replacement of prior evaluation, server-side final-vs-interim labeling driven by task closure, and that the factor is advisory and does not alter tracked time. It also discloses visibility ('visible to all who see the task'), which no annotation conveys.

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

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

Front-loaded with the action and trigger, and every clause carries information (replacement rule, final/interim, advisory factor). It is dense to the point of one long semicolon-chained sentence, which costs a little readability.

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

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

No output schema exists, but the description covers the essentials an agent needs: what gets persisted, the one-per-stage replacement rule, how the server classifies the evaluation, and that the factor is non-binding. It is only slightly short on things like permission requirements or the source of rulesRevision beyond the schema note.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks for two key params: 'factor' is a recommendation that does not change tracked time, and 'comment' is visible to everyone who sees the task. The replacement/one-per-stage rule also constrains how a call is composed.

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 precise verb+resource ('Saves a task stage evaluation') along with the payload it carries (bonus factor, comment) and the trigger. An agent can tell this is the write counterpart to the read-side sibling task_evaluation_context without opening either schema.

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

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

Gives an explicit activation condition ('when the user asks to evaluate work'), which is more than most tools offer. It does not, however, name the read-side alternative (task_evaluation_context) or state any exclusions/preconditions, so a 5 is not earned.

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 readOnly/non-destructive behavior, and the description adds real value on top: money fields require the task:costs permission else null, null salary and bonus are hidden, and rates/amounts are scoped to the assessment rather than the comment. These are concrete masking/permission behaviors not derivable from annotations.

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

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

The information is valuable but delivered as one dense run-on sentence with a heavy parenthetical list of returned fields. It is not front-loaded into scannable units, though nothing is outright wasted.

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

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

With no output schema, the description carries the return-shape burden and largely does so by enumerating spec/result, assignee, rates, plan-by-status, bugs, commits and prior evaluation. Permission-driven nulling is also covered, leaving only pagination/size behavior unaddressed.

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

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

Schema coverage is 100% and all three parameters (ID, key, stage) are documented in the schema with the ID-vs-key preference and the stage enum. The description adds no syntax or format detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb ('Returns') and resource ('the data for evaluating a task stage' plus workspace evaluation rules), and enumerates the returned fields. An agent can tell this is a read-context helper, distinct from the write-oriented sibling task_evaluate, though the description never names that sibling to make the contrast explicit.

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 an implied trigger ('when the user asks for a work evaluation'), which is genuine but thin. There are no exclusions, no prerequisites, and no pointer to task_evaluate as the alternative for actually submitting an evaluation, so the routing decision 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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds real behavioral context: the draft routes to approval when an approver is assigned and to the assignee otherwise, and it is restricted to the caller's own data. It does not describe failure modes (e.g., no approver and no assignee) or any state side effects on related records.

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

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

Front-loads the core action and the key behavioral distinction (not taking the draft into work) in the first clause. Three dense sentences, all carrying information, though the mid-sentence analogy and nested routing clause make it slightly run-on.

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

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

For a mutation tool with no output schema, the description compensates by naming the return payload (link, status, available transitions) and the routing outcome of publishing. Prerequisites (own draft, user-initiated) are covered; only edge-case behavior when no approver/assignee exists is left unspecified.

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

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

Schema description coverage is 100% and both parameters (ID, key) are documented in-schema, including the ID-preferred-over-key preference. The description adds nothing about parameter selection, 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 (Publishes) and resource (own task or bug draft) with a clear scope constraint: it only touches the token owner's shared-team draft and explicitly does NOT take it into work. The web-button analogy plus the approval/assignee routing makes it instantly distinguishable from siblings like task_take and task_update.

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-to-use gate: "Only at the user's request: the draft is their review of the spec." It also implicitly contrasts with task_take by stating the tool does not pull the draft into work. It never names a sibling alternative by name, so it stops short of the top score.

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