Kosmodrom

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description usefully adds that each branch name is parsed for a task key and that taskID restricts to 'live' branches, but says nothing about pagination or result size, leaving moderate behavioral gaps.

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

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

A single compact sentence that front-loads the core action (listing branches) and then the two filter behaviors. No wasted words, though the parenthetical taskKey note is slightly crammed in.

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

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

For a simple read-only list tool with no output schema and full parameter coverage, the description conveys enough to call it correctly. A brief note on result limits or ordering would make it fully complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters; the baseline is 3. The description adds mild clarifying detail (taskKey extraction, substring matching) but no syntax or format 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 (Lists) and resource (repository branches), plus what each entry carries (taskKey). It does not explicitly differentiate itself from the nearby repo_branches sibling, which keeps it just short of a 5.

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

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

The description explains how taskID and search behave but gives no guidance on when to reach for branch_list versus repo_branches or other branch-oriented siblings. Usage is only implied from the filter semantics.

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, so the description adds value by explicitly reinforcing that it 'Creates nothing' and explaining the conditional return of the live branch (only if one exists). It doesn't cover rate limits or auth needs, but for a simple read this is sufficient.

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?

Highly concise: two sentences that front-load the core purpose and the key behavioral constraint. The parenthetical and trailing phrase feel slightly awkward but do not waste space.

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

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

For a 2-parameter read-only tool with no output schema, the description covers purpose and key behavior. It could specify the return type or format, but with annotations and full schema support, nothing critical 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 both taskID and repositoryID are fully documented in the schema. The description mentions neither parameter, so it adds no semantic value beyond the structured fields – baseline 3 is correct.

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

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

States a specific verb and resource: returns the branch name for a task. It distinguishes the two outputs (server-convention name and live branch) and explicitly clarifies that this is a lookup, not a creation.

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

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

Implicitly indicates when to use: when you need the convention branch name or the task's live branch. However, no alternatives are named and no exclusions or prerequisites are given, so usage 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?

Goes well beyond the readOnlyHint=false / destructiveHint=false annotations by disclosing that the object is created as an unpublished draft requiring owner review, that bugs always have a testing stage, and that the response returns key, link, status and allowed transitions. These are meaningful lifecycle facts an agent cannot infer from annotations.

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

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

Front-loaded with the action, trigger and draft lifecycle, then placement, the `type` caveat and return values — every clause carries information. It is dense and would read better with light structuring, but there is no filler.

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

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

For a 19-parameter write tool with no output schema, the description covers the creation workflow, placement choices, criticality semantics and even the return payload, while the 100%-covered schema carries individual field detail. Complete enough to call correctly, though the review/approval stage behavior is left entirely to field descriptions.

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 semantic value by disambiguating `type` (criticality) from the separate `bugType` (nature of the defect) and by framing the placement parameters as a preference order. It stops short of explaining the remaining timing/assignee parameters, which the schema handles.

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 scopes it as a draft that a token owner later publishes, which clearly separates it from sibling write tools like task_create. The distinct 'bug' resource plus the draft/review workflow makes the tool's identity unambiguous.

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

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

Gives an explicit trigger ("when the user asks to log a defect") and lays out the placement options (feature, version, product backlog). It stops short of naming an alternative tool or stating when not to use this one, 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?

Goes well beyond annotations by disclosing irreversibility, the permission model (token owner within 60 minutes; chat administrators and product lead any message), and the operational scope. Annotations only flag destructiveHint=true; the description provides actionable constraints.

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

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

Two sentences, front-loaded with the action and irreversibility warning, then permissions and intended use. No filler or repetition; every clause adds useful information.

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

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

For a single-parameter destructive tool with annotations covering safety hints and no output schema requirement, the description supplies irreversibility, permission boundaries, timing, and intended use. Nothing essential 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% for the single messageID parameter, including format and description. The description adds no parameter-specific syntax or constraints, so the baseline of 3 applies for high schema coverage.

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

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

States a specific verb ('Deletes') and resource ('chat message'), clearly distinguishing it from sibling operations like chat_message_update and chat_send. 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?

Explicitly states the intended context: an explicit user request to remove an unneeded message, with examples ('duplicate, wrong chat'). This implies when not to use it (unsolicited/autonomous deletion), though it does not name an alternative 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?

Adds substantial behavior beyond annotations: text fully replaces the old content, mentions are recalculated from mention tokens, attachments are wholesale replaced ([] clears all), an 'edited' mark appears, and only one edit is permitted. These replacement semantics and the edit-window limit are exactly the facts an agent needs before committing.

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 sentence that front-loads the edit constraint and then enumerates replacement behavior with no filler. Every clause carries operational meaning.

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

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

With annotations covering the safety profile, a 100%-covered schema, and no output schema expected to be explained, the description supplies the remaining gaps: ownership, time window, replacement semantics, and irreversibility. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds the '[] removes all' convention for attachments and clarifies that mentions are derived from tokens rather than passed explicitly. The full-replacement semantics for text and attachments also give context the schema only implies.

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) with an explicit scope restriction that separates it from chat_send and chat_message_delete. An agent can identify the operation and its boundary 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 use conditions: only the owner's own message, only within 60 minutes of sending, and later edits being impossible tells the agent this is a one-shot operation. It does not name alternative sibling tools for the 'too late' or 'not my message' cases, so it stops short of 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, so safety is covered. The description adds real behavioral context beyond that: results are age-independent ('regardless of age'), and it discloses the returned payload shape (chat/link, why addressed, related item, message with attachments). Pagination continuation via nextCursor/hasMore is also stated.

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

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

It is one dense run-on sentence, but it is front-loaded with purpose, then usage intent, then paging behavior. Every clause earns its place, though the parenthetical enumeration makes it heavy.

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

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

There is no output schema, yet the description explicitly describes what a returned item contains (chat and link, why it is addressed, related item, the message with attachments), compensating for the missing schema. Combined with the paging behavior and the read-only annotation, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so limit and cursor are already documented, and the baseline is 3. The description's pagination note refers mostly to the response fields (nextCursor/hasMore) rather than adding syntax or constraints to the parameters themselves, so it does not clearly exceed baseline.

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

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

States a specific verb (Returns) and resource (messages addressed to the token owner still unanswered), and enumerates the trigger types — direct chat, mention, reply — that qualify. An agent can distinguish this from chat_read and chat_send 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 a clear triggering condition: 'Useful when the user asks what awaits their reply.' This maps the tool to an intent. However, it names no alternative (e.g., chat_read) and gives no exclusions, so it stops short of full when/when-not guidance.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, leaving the real behavior to the description. It adds substantial rules beyond them: no duplicate reaction, system messages take no reactions, reactions are keyed by the reacting user, and only Kosmodrom web reactions are supported.

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 add/remove purpose and then packs the constraints efficiently. It is a single long compound sentence rather than cleanly separated, but every clause earns its place and none 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 and full annotation coverage of only the safety flags, the description supplies the edge cases (duplicate suppression, system-message exclusion, keying by user) an agent needs. It could go slightly further on remove-specific behavior, but is largely complete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the full reaction enum meanings that the description merely points to ('meanings in reaction'). The description adds little parameter-level detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb (adds/removes), resource (the token owner's reaction), and target (a chat message). It clearly distinguishes itself from chat_send/chat_message_update by being the textless-reaction tool.

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

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

Explains the appropriate context for a reaction (a textless reply when the meaning is unambiguous) with concrete examples. It stops short of naming alternative siblings (e.g. chat_send) or giving explicit when-not-to-use conditions, so it is strong but not exhaustive.

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

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

Annotations only supply readOnlyHint=true, so the description carries real additional weight: it discloses ordering (oldest to newest), pagination direction semantics, and the meaning of the hasMore response field. It adds no rate-limit, auth, or size caveats, keeping it short of 5.

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

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

Two compact sentences, front-loaded with the primary behavior and then the hasMore semantics; nothing is padded. The semicolon-heavy phrasing is slightly dense 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 covers the key return signal (hasMore) and pagination behavior, which is what an agent needs to iterate. It does not describe the message object shape, so it is not fully complete, but the essential pagination contract is there.

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 by explaining that after returns newer messages in the requested direction and how the boundaries relate to ordering. This clarifies the cursor parameters beyond their terse schema descriptions.

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

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

The description opens with a specific verb+resource ('Returns chat messages') and qualifies it by cursor direction, so an agent can immediately tell it apart from write-side siblings like chat_send or chat_message_update. It stops short of naming any sibling explicitly, so it does not reach the top of the scale.

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: no cursor returns the latest messages, an after cursor walks forward to newer ones (e.g. replies), implying before for older. It never states when NOT to use it or points to an alternative tool, so it lacks the exclusions a 5 would require.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is covered. The description adds genuinely new behavior: it returns chatID, the message and an after cursor, and the message is editable/deletable within a 60-minute window. It omits rate limits or failure modes, 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?

A single dense sentence front-loads the action, then the targeting variants, then the negative guidance and return contract. No sentence is wasted, though the packed clauses around replies and returning cursors make it slightly heavy to parse in one pass.

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, 100% schema coverage and no output schema, the description supplies the missing return shape (chatID, message, after cursor) and the 60-minute edit window. Nothing an agent needs to select or invoke this tool correctly 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%, so every parameter including the idempotencyKey retry semantics is already documented in the schema. The description's notes that chatID equals a task ID and that userID is the DM alternative restate what the schema already says, rather than adding syntax or format meaning.

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 (sends a message on behalf of the token owner) and immediately distinguishes the three targeting modes: chatID, userID direct message, and replyMessageID. An agent can tell this apart from siblings like chat_read, chat_reaction, or chat_message_update without opening a schema.

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

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

Gives explicit when-to-use ('blocking questions, replies to messages addressed to the token owner, and messages the user asks for') and explicit when-not ('not for status updates, summaries or links to created items'). This is precisely the routing guidance an agent needs among ~70 siblings.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is covered. The description adds a meaningful behavioral constraint beyond the annotations: it must only be invoked at the user's request or with consent, because the product structure belongs to the team. It does not cover validation errors, permissions, or what happens to existing structure, but it adds real context the annotations do not.

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

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

Two short sentences, front-loaded with the core action and followed by the consent constraint. No wasted words and nothing important buried.

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

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

For a simple three-parameter create tool with full schema coverage and no output schema, the description is largely sufficient, and the consent rule fills the main behavioral gap. It does not mention required fields, the language/workspace convention for title, or what a successful call returns, but nothing critical 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% – title, desc, productID each carry their own description in the schema. The description adds no parameter-level syntax, format, or constraint information, so the baseline of 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 and resource ('Creates a product component'), and the sibling set contains both component_update and module/feature create tools, so the resource is clearly distinguished. An agent can immediately tell this is a creation tool for the component entity.

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

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

Gives an explicit precondition: 'Only at the user's request or with their consent,' which is real guidance about when to invoke it, not just what it does. It does not name a sibling alternative (e.g., component_update) or state when not to use it, so it falls 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.

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

Adds genuine behavioral context beyond annotations: partial-update semantics (omitted fields stay unchanged) and that module membership is unaffected. However, the description says the tool can remove the component's main Figma frame while annotations declare destructiveHint=false, a tension that is not reconciled; no permission or reversibility detail is given.

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

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

Front-loaded with the primary operation and the effects on omitted fields; only two clauses before the consent caveat. Tight, though the second sentence about product-structure ownership is slightly editorial rather than operational.

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

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

For a mutation tool with no output schema, the description covers scope (what changes, what does not) and the consent requirement, which is enough for correct invocation. It falls short only on permission prerequisites and on clarifying the destructiveHint tension around frame removal.

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 every field is documented, including the design=null removal semantics, so the schema does the heavy lifting. The description adds only the general 'omitted fields unchanged' rule, not per-parameter meaning. 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 (updates) plus resource (component) and enumerates exactly what is mutable: name, description, or removal of the main Figma frame. It also clarifies what is NOT touched (module membership), which cleanly separates it from module_update and component_create.

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

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

Provides one explicit usage condition – only act at the user's request or with their consent – which is real guidance, but never names alternatives or says when a sibling (component_create, module_update) should be chosen instead. Implied rather than complete 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?

readOnlyHint=true already declares this is a safe read, so the safety burden is lifted. The description adds the useful detail of exactly what is returned (content + rulesRevision) and the task/work-type dependency, but omits any format, failure mode, or authorization context.

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

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

Two tightly packed sentences that lead with the return payload and follow with the conditional task rule. No filler, though the phrasing is dense enough to read slightly awkwardly.

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 names the returned fields (content, rulesRevision) and the work-type conditional. For a 2-param read tool this is close to sufficient; a pointer to the consuming create tools would make it 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% and both enums are self-documenting, so the schema carries the load. The description's note that the task template depends on work type adds marginal motivation for taskType but no syntax beyond what the schema already 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?

The description clearly states it returns workspace conventions, a description template, and a rulesRevision for feature/task/bug creation, which is a specific verb+resource. This notably clarifies a misleading tool name ('create_rules' implies a write). However, it names no sibling to distinguish itself from, e.g., evaluation_rules or the *_create tools.

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

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

The description implies this is fetched before creating a feature/task/bug ('templates that creation requests carry'), giving usable context. But it never explicitly says when to call it versus the create tools, nor any exclusions or prerequisites.

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

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

Annotations only carry readOnlyHint=true, but the description adds the rate source (Bank of Russia), holiday/weekend fallback behavior, cross-rate routing via RUB, and an explicit error condition (future dates rejected). That is rich behavioral disclosure well 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?

Core purpose is front-loaded in the first clause, edge-case rules follow, and the return contract is stated last. No filler; every clause conveys a distinct rule or behavior.

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

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

There is no output schema, so the description compensates by documenting the return shape (rate and result, with result rounded to 2 decimals). Combined with the date and error rules, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it defines rate as 'units of to per 1 from', removing ambiguity about rate direction, and reinforces the date fallback rule that the schema only alludes to. The 'from'/'to' enums are already 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 (converts) and resource (an amount between RUB, USD, EUR, CNY) with the exact rate source. It is instantly distinguishable from every sibling tool, none of which touch currency.

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 operating context: which currency set is supported, that non-business days fall back to the last business day, that cross rates route via RUB, and that dates after tomorrow are rejected. No sibling overlaps so no alternative needs naming, but it stops short of an explicit 'use this when...' framing.

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 write (readOnlyHint=false) and non-destructive; the description adds real behavioral context beyond them: the reply is visible to everyone with file access and the server appends an 'employee and agent' signature. It does not cover failure/error behavior 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?

Front-loaded with the action and its side effect, then usage guidance, in three dense clauses. Information is efficient, though the semicolon-packed phrasing is slightly cramped.

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

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

For a write tool with no output schema, it covers visibility, the server-added signature, source options, and usage conditions. Missing only edge-case handling such as invalid commentID or file-access failures.

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 four parameters. The description reinforces the url-or-designID source choice and that commentID may be a thread or a reply, but adds no syntax or format detail the schema lacks, 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 (replies) and resource (Figma comment thread) plus the integration context. It is clearly distinguishable from sibling read tools like design_comments without opening a schema.

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

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

Explicitly scopes when to use it ('when a remark is fixed or the answer is unambiguous') and when not to ('disputed points are left to the user'). It stops short of naming the alternative surface (e.g., design_comments for reading), so it falls just below 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?

With readOnlyHint=true already covering safety, the description adds genuinely non-obvious context: author.isIntegration flags replies sent through Kosmodrom, a later reply can cancel a remark, and the Figma API cannot mark threads resolved. These are operational caveats an agent could not derive from annotations, though return format/pagination is untouched.

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 purpose and result shape, then source semantics and caveats. No filler; the telegraphic 'Source: ...' clause is terse but 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?

No output schema exists, so the description compensates by listing the fields of each returned thread and by documenting the integration caveats. The one gap is that with zero required parameters, it does not explicitly state that url or designID must be 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 baseline is 3, but the description adds real semantics: for url it explains that a frame or page returns only threads inside it while a file returns all, and for designID it indicates an imported design identifier. Only the status enum default is left entirely to the schema.

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

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

States a specific verb and resource ('Returns Figma design comments') and enumerates the returned structure (threads with author, date, text, replies, pinned node). It also implicitly separates this read tool from the design_comment_reply sibling by framing the returned data rather than any write action.

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 reader can infer 'read comments' vs 'reply to comments' from sibling names, but the description never states when to use this versus design_comment_reply or design_import. It does clarify the source-selection rule (url vs designID), which is useful but is parameter guidance rather than when-to-use guidance.

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

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

Annotations only flag readOnlyHint=false and destructiveHint=false. The description adds substantial context beyond that: partial-failure semantics ('a failed frame does not stop the others'), the full per-frame status set, the designToken as the only design link, and re-import refresh behavior that preserves markers. This is rich, non-obvious behavioral disclosure.

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

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

The core action is front-loaded, but the description is a single dense compound sentence with semicolon chains that is hard to scan. Most clauses earn their place, yet the structure could be broken into clearer segments.

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

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

No output schema exists, and the description compensates by documenting per-frame return values (status enum values, designID, designToken, error/action). For a 7-parameter tool it covers targets and behavior well, though it omits prerequisites such as whether the target entity must already exist.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: moduleID/componentID set the module's or component's main frame and are constrained to one frame with no marker. That explains the otherwise opaque parameters beyond their schema descriptions.

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

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

States a specific verb (Imports) and resource (Figma frames) plus the target entity types (task, bug or feature), with an analogy to pasting a design in the web app. An agent can distinguish this from sibling design_comment_reply and design_comments without opening the schema.

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

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

The description gives context ('into a task, bug or feature through the company's Figma integration') which implies when the tool applies, but never names alternatives or states when NOT to use it. Usage is inferable 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, so safety is covered; the description then adds a genuinely useful non-obvious behavior: 'the server picks the variant', telling the agent the caller cannot select which rule set comes back. It also notes rulesRevision is returned, though it says nothing about error cases when no rules exist for a type/stage.

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

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

Two sentences, no filler, with the return payload front-loaded before the usage example. The second sentence is slightly dense but every clause carries information.

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

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

There is no output schema, so the description correctly enumerates the return contents (procedure, rating scale, comment requirements, rulesRevision). Combined with 100% schema coverage and readOnlyHint, an agent has what it needs, though the missing-rule case is 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 description coverage is 100% with both parameters enum-documented, so the baseline is 3. The description only restates the two axes (task type, stage) already fully described in the schema and adds no format or edge-case semantics beyond 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 (Returns) and resource (work evaluation rules) plus the key discriminator (task type + stage) and names the returned contents. It is clear what the tool does, though it never explicitly contrasts itself with close siblings such as task_evaluate 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?

Gives concrete trigger conditions with user-phrase examples ('evaluate #12345', 'evaluate the review of #12345'), which is clear usage context. It stops short of naming alternatives or when NOT to use it, so it falls short of the 5 bar.

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, so the safe-read profile is covered. The description adds genuine value by disclosing the returned payload categories (tasks, repos, live branches, commits), but says nothing about auth needs, result size, or how the two identifiers are resolved. With annotations carrying safety, 3 is appropriate.

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

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

Two tight sentences with the capability front-loaded and the use case appended; nothing is wasted or redundant.

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

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

With no output schema, the description usefully sketches the return contents, and the read-only safety profile comes from annotations. It is complete enough to call correctly, though a note on how key vs featureID resolve to one feature would close the 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 description coverage is 100%, so both parameters (key and featureID, plus their mutual exclusivity and accepted key formats) are already fully documented. The description adds no parameter-level meaning, which is the expected baseline 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 (returns) and resource (a feature's code) and enumerates the contents: tasks, repositories, live branches, and commits by task keys. Assuming 'code' here does not literally mean source, it is distinguishable from plain feature_context. It does not explicitly contrast itself with the very similar task_code_context sibling, so it stops short of 5.

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

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

The sentence 'Useful for checking a feature's spec against the implementation' gives an implied usage scenario, but there is no explicit when-to-use guidance, no exclusions, and no routing among near-neighbors like feature_context, task_code_context, or repo_context.

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

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

readOnlyHint=true already declares this a safe read, so the description's job is to add context — and it does: it discloses the exact field set returned and explains that specRevision is the revision needed to edit the spec, an implicit concurrency hint for a subsequent write. It does not describe failure behavior when neither key nor featureID is supplied, which is the remaining gap.

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 but well-structured sentence that is front-loaded with the core action and then enumerates return fields in priority order. No filler, though the inline parenthetical aliases (workAssigneeID, attaches, ord) make the single sentence 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?

With no output schema, the description carries full responsibility for return values and discharges it thoroughly. The only unaddressed case is that both parameters are optional with no stated default or error behavior when neither is provided.

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 self-documenting ('not with featureID' / 'not with key'), so the schema already carries the semantics. The description repeats the #F12 key convention but adds no new parameter guidance, making the baseline 3 correct.

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

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

States a specific verb and resource ('Returns a feature by ID or key') and then enumerates the exact payload: spec, gist, plan tasks ordered by ord, bugs, employees, designs/attachments with file IDs, and specRevision. This level of return-content detail makes it distinguishable from siblings like feature_list or feature_search even though those names are not cited.

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 about a feature, its plan or who works on it'), which tells the agent when this is the right call. It stops short of naming an alternative (feature_list vs feature_search vs feature_context) or stating exclusions, 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 establish the write/non-destructive profile, and the description adds real behavioral context: the feature is immediately team-visible, has no approval step, and spawns no tasks. It also discloses the return shape (link, product, version, ord, specRevision), compensating for the absent output schema. It does not cover permissions, idempotency, or the spec/rulesRevision relationship, keeping it below a 5.

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

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

A single sentence with the action front-loaded and no filler. It is slightly run-on, packing side-effect disclosure and return values into one semicolon-joined clause, but every element 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 an 8-param mutation tool with no output schema, the description covers side effects and return values well. It is slightly short on the required-parameter relationship (title/gist/rulesRevision/productID) and how spec relates to rulesRevision, leaving minor gaps.

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

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

Schema description coverage is 100%, so all 8 parameters (including defaults for ord and versionID) are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides; baseline 3 applies 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 with scope: 'Creates a feature in a product version.' This is unambiguous against siblings like feature_update, feature_delete, feature_list, and even the differently-scoped task_create. An agent can select this 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?

'When the user asks to add one' gives a clear triggering context for use. However, no alternatives or exclusions are named (e.g., when to use feature_update or branch/task creation instead), so it stops short of the explicit when/when-not routing a 5 requires.

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

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

Annotations only flag destructiveHint=true; the description adds the far more important specifics: this is a soft cascading deletion affecting child tasks and bugs, it is irreversible with no restore, and it returns a deletedTasks count. The soft-delete-plus-no-restore nuance is exactly the kind of detail annotations cannot carry.

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

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

Three short sentences, each earning its place: cascade scope first, then the irreversibility/usage constraint, then the return value. No filler or repetition of the schema.

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

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

For a single-parameter destructive tool with no output schema, the description covers cascade semantics, irreversibility, usage constraint, and even the return value. Nothing an agent needs in order to call it safely is missing.

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

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

Only one parameter (featureID) and schema description coverage is 100%, so the schema already documents it fully. The description adds nothing about the parameter beyond the schema, which is the baseline 3 case.

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 (a feature) plus the cascade scope (with all its tasks and bugs), which cleanly separates it from siblings like task_delete, bug_delete, or feature_update. An agent can distinguish 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?

"only at the user's explicit request" gives a clear activation condition and warns against autonomous use. It does not, however, name an alternative (e.g., feature_update or deactivating/archiving) for cases where deletion is too strong, so the routing guidance stops short of explicit alternatives.

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 assert readOnlyHint=true, but the description adds real behavioral context: results are `ord`-ascending, spec/specRevision only appear with includeSpec which yields a 'much larger response', completed features are gated by allowDone, and pagination requires reusing the same parameters with nextCursor. It does not spell out the returned shape, but that is beyond a read-only list tool's usual burden.

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 sentence front-loads the core action and ordering before covering the optional flags and pagination. No filler, though cramming purpose, options, and paging into one sentence makes it slightly dense 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 no output schema, the description still covers ordering, filtering, payload-size implications, and the paging loop needed to use the tool correctly. For a read-only list endpoint it is essentially complete, missing only a note on default result size or explicit non-use cases.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds meaning the schema does not: it discloses the response-size tradeoff of includeSpec, that allowDone filters to completed-only, and crucially that the next page must be fetched with nextCursor using the same parameters. That pagination contract is genuine added value over the field definitions.

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 the features of a product or one version') plus ordering ('`ord` ascending'), which lets an agent distinguish a bulk-listing operation from the sibling `feature_search`. It stops short of explicitly naming the search sibling as the alternative, so it is clear but not fully disambiguated.

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 intended browse/overview use case, and it notes when to add includeSpec or allowDone. However, it never states when NOT to use this tool or names feature_search/feature_context as the alternative for targeted lookups, so routing guidance remains 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?

With readOnlyHint=true already covering the safety profile, the description adds meaningful behavioral detail: search is semantic across multiple fields, returns short entries with excerpt and score, and pagination reuses the last item's cursor with the same query and filters. It does not cover auth needs or rate limits, but adds solid context beyond annotations.

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

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

The description is two dense sentences that front-load the core purpose and then cover usage, return format, and pagination. Every clause contributes useful information without fat.

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 search tool with no output schema, the description supplies the essential missing return context: short entries, excerpt, score, and pagination via cursor. It omits minor details such as default limit behavior or score interpretation, but is otherwise 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 clearly. The description reinforces pagination behavior around cursor and filters but adds no syntax or format detail beyond what the schema states, 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?

The description states a specific verb and resource: it searches a product's features by meaning across title, gist, and spec. It also implies differentiation from a plain list by describing semantic matching, word forms, aliases, and typo tolerance. However, it does not explicitly name a sibling tool to contrast with, 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?

It gives concrete usage context: when the user asks to find a feature or determine where new work belongs. This is clear guidance, but it offers no when-not-to-use conditions or explicit alternatives such as feature_list or task_search.

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 the description reinforces it with 'writes nothing' while enumerating exactly what is returned (specs, task results, workspace guidelines). It adds useful return-shape context beyond the safety hint, though it doesn't discuss pagination or limits on the batch size.

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

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

Front-loaded with the primary purpose, then details of return content and mode behavior in a compact block. Slightly dense and partially redundant with the mode enum in the schema, 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?

With no output schema, the description usefully spells out the returned payload (feature.spec, tasks[].spec, tasks[].result, instructions) and the analyze/apply distinction, which is essential for a 7-parameter tool. Minor gaps remain around defaults for basis and chatLimit that live only in the schema.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description largely restates mode semantics and the includeTaskIDs behavior ('full contexts with chats of tasks with discrepancies') with little added meaning beyond the schema text, 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 concrete verb and resource: returns the context (feature.spec, tasks[].spec, tasks[].result, guidelines) needed to update a feature's spec. The feature-level scope clearly separates it from the sibling task_spec_sync, so an agent can pick between them 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 explicit mode-based usage: 'mode=analyze - differences and a full new version without saving' versus 'mode=apply - when the user asks to apply the update.' That is a clear when-to-use rule, though it does not name an alternative tool or state 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 only say it is a non-read-only, non-destructive write; the description adds that it mutates shared team data and that partial updates are the norm, plus that closure is out of scope. It does not mention the design-deletion side effect of designUnlink, which is only visible in the schema, but it goes beyond the annotations on the mutation model.

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 field list and the partial-update rule, and every sentence earns its place. The single long opening sentence is dense, which slightly hurts scanability, 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 9-parameter mutation with no output schema, the description covers the mutable fields, the partial-update semantics, the closure exclusion, and even the return payload (link, product, version, ord, specRevision, changed fields). Selection and invocation are fully supported; only the design-unlink side effect remains outside the description.

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 contributes the partial-update contract ('only passed fields change') and the semantic framing of version as a move and ord as a position, which the schema does not state as plainly. That is real added meaning on top of the already thorough 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 (Updates) and resource (a feature) and enumerates the mutable fields including the non-obvious moves (versionID) and ordering (ord). An agent can separate this from feature_create, feature_delete, and feature_list without opening any schema.

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

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

Gives explicit scope ('only passed fields change') and an explicit exclusion ('closing a feature is a human decision, not available here'), which is exactly the kind of when-not guidance that helps selection. It stops short of naming an alternative tool for the excluded operation, so it is not a full 5.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that — the four-list priority ordering, the next-item-first convention, and that includePool entries are matched to the person's role and level. It doesn't cover pagination or result-size limits, but it materially extends what the annotations 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?

One dense paragraph, front-loaded with what is returned, then scoping rules, then the usage cue. Every sentence carries information, though the packing of list names and pool names into a single block is slightly heavy.

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

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

No output schema exists, and the description compensates well by spelling out the four list names and their ordering plus the optional pool lists. It omits the shape of individual queue items and any size/limit behavior, so it is close to but not fully complete for a tool with no output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema lacks: includePool pulls a shared 'any' pool (poolBugs/poolTasks) filtered by the person's role and level, and the priority/ordering meaning of the returned lists. userID's default-to-token-owner is already 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?

Names a specific verb+resource and goes further by enumerating the exact return contents (urgentBugs, urgentTasks, bugs, tasks) and the exclusion of review/testing/approval items. An agent can distinguish this from task_search or task_context without opening a schema.

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

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

Explicitly states the trigger context: 'Useful when the user asks what to work on next.' The exclusion note also implicitly routes agents away from this tool for review/testing/approval work. No alternative tool is named by name, 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 establish readOnlyHint=true, but the description adds real behavioral context: the 5242880-byte inline cap, which content types are inlined, and the edge case where an attach token has no attaches entry (deleted attachment or copied text). The last sentence is terse but discloses a failure mode the schema does not.

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 with the core behavior (what comes back and the size/type limit) front-loaded, followed by the edge case. No filler.

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

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

With no output schema, the description correctly spends its budget describing the return shape (image as image, text as text, size cap, non-inline types) and one failure mode. It still leaves unclear what the caller actually receives for a non-inline file, which is the main 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% and the fid description already explains the 'attach:<fid>' relationship, so the schema carries the parameter burden. The description adds no format or constraint detail for the optional entity object 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 ('Returns a file's content by fid') and immediately scopes it with return-format rules, which separates it in spirit from file_info and file_url. It never names those siblings, so the differentiation is inferable rather than 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?

Gives a clear when-not condition: larger files, video, archives and other binaries are not returned inline, so an agent knows this tool won't work for those cases. It does not route the agent to an alternative (file_url, file_info) for the non-inline cases.

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

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating read. The description's one added behavior detail is the set of fields returned, which matters because there is no output schema; it says nothing about permissions, rate limits, or behavior when the fid is unknown.

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

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

It is a single front-loaded sentence with no filler and the purpose leads. The trailing clause about attaches is dense and jargon-heavy but still earns its place as routing 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, listing the returned fields compensates well, and the read-only annotation covers the safety profile. Both parameters are fully documented in the schema, so an agent has what it needs, though return format details (e.g. null when unknown) are 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%, including the nested entity object, so the structured data already carries parameter meaning. The description only echoes 'by fid' and adds no format, constraint, or entity-scoping nuance beyond the schema, 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?

The description states a specific verb and resource (returns file metadata by fid) and enumerates the returned fields (name, MIME type, kind, size, upload date, uploader). It does not explicitly differentiate itself from the close siblings file_get, file_url, or file_upload, so an agent must still infer which file tool to pick.

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

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

It gives a clear use condition ('for a fid without known metadata') and an exclusion ('task and feature attachments already carry it in attaches'), which is real routing guidance. It stops short of naming the alternative tools an agent would otherwise consider, e.g. file_get or file_url.

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 mark it non-read-only and non-destructive; the description adds material behavior: max upload sizes, two-phase URL upload, attachment multiplicity, and a hard limitation that files cannot be deleted through MCP. No contradiction with 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 purpose and dense but purposeful sentences; every clause (token destinations, size limits, upload modes, deletion limitation) carries operational weight.

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

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

For a two-mode upload tool with no output schema, the description supplies the key attachment identifiers and uploadURL flow. It falls short by not naming file_upload_complete as the completion step and by not fully specifying the return shape.

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

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

Schema coverage is 100% for both parameters, and the schema already states the base64 size limit and the URL-upload alternative. The description reinforces the workflow but adds little parameter-level meaning beyond the schema.

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

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

States a specific verb and resource, then immediately distinguishes the two attachment identifiers (attachToken vs fid) and the two upload modes. An agent can tell this is the upload primitive rather than file_upload_complete or file_get, though the sibling is not named.

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

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

Explains the dataBase64 path for small files and the uploadURL PUT path for larger files, including size limits. However it does not explicitly name file_upload_complete as the final step or provide conditions for choosing among sibling file tools.

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

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

Annotations declare a non-read, non-destructive write, but the description adds real behavior: it verifies stored size and is idempotent on repeat. Those traits beyond the annotations (verification step, safe re-invocation) are exactly the value-add expected here.

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 sentence with the trigger condition front-loaded and the return/idempotency facts trailing. No wasted filler, though the return-value clause is packed tightly enough to require a careful read.

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

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

With no output schema, the description usefully enumerates the return values (file and attachToken for spec/result, fid for chat attachments) plus idempotency, which compensates for the missing output contract. Coverage is good for a one-param completion 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% and there is a single documented 'fid' parameter, so the schema carries the semantics. The description adds no syntax or format detail for fid, 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 ('Completes an upload via URL') and pins its place in a multi-step flow ('after a successful PUT to uploadURL'). An agent can distinguish it from the upload-initiating sibling (file_upload) via the flow role, though no sibling is named explicitly.

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

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

Clear activation condition: call it only after a successful PUT to uploadURL. It also gives idempotency guidance ('Repeating it returns the same response'), reducing retry risk. No explicit when-not or named alternative, so it stops short of a 5.

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

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

Annotations only declare readOnlyHint=true, while the description adds that the URL is signed and time-limited and returns metadata. It does not state expiration duration or permission requirements, but it adds meaningful behavioral context beyond the annotation.

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 efficient sentence with purpose front-loaded and no filler. Every element, including return type, file scope, and exclusion case, 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 read-only URL-retrieval tool with no output schema, the description covers the return object (signed URL and metadata) and the use case. The optional entity parameter's effect is left to the schema, but nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description says 'by fid' but adds no syntax or meaning beyond the schema, and it does not discuss the optional entity parameter.

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

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

States a specific verb 'Returns' and resource 'signed, time-limited download URL and metadata for a file by fid', and scopes it to video, archives, and other non-inline files. This distinguishes it from sibling tools like file_get and file_info by explaining that it serves files not returned inline.

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 clear context: use for video, archives, and other files not returned inline. It implies file_get or file_info are alternatives for inline-accessible files, but does not explicitly name when not to use 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, so the safety profile is covered. The description adds one useful behavioral detail, the 'today by default' fallback, but says nothing about format of the returned key or any failure conditions.

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

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

A single efficient sentence with the core action front-loaded. The trailing colon clause is slightly dense but every element carries meaning; 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 zero-required-parameter, read-only lookup with no output schema, the description covers what it returns and the default date behavior. Nothing critical is missing, though naming the return format would round it out.

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

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

Schema coverage is 100% and the single parameter already documents 'ISO date; defaults to today'. The description only restates the default, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Returns the iteration key for a date') and explains what the value is (workIterationKey). The scope is concrete enough that an agent can distinguish it from unrelated siblings, though there is no explicit sibling differentiation.

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

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

The clause 'for planning a task or bug outside the current iteration' implies the usage context, giving the agent a scenario. However, it never states when not to use it or names an alternative, leaving usage 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 readOnlyHint=false and destructiveHint=false. The description adds real behavioral context beyond that: the record starts personal and unverified, immediately applies to the token owner's agents, and a moderator can later make it shared. Auth/rate-limit details are absent, but the lifecycle disclosure is genuinely useful.

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

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

Two sentences, front-loaded with the core action before the visibility and `level` details. Dense but every clause (trigger, secret caveat, visibility lifecycle, level semantics) earns its place; only minor cost is that the level list is inline rather than 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?

For a 7-parameter creation tool without an output schema, the description covers the trigger, the safety caveat, the visibility lifecycle, and the one ambiguous required parameter's semantics, while the schema already documents the remaining fields. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 86% (above the 80% baseline of 3), but the description goes further by spelling out the four `level` values with concrete scope examples (company/Git/cloud/CI, user/preferences, project/infrastructure, repository/conventions) — meaning the schema's bare enum does not carry. This is a real addition over structured data.

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." Combined with the trigger condition (user asks to keep knowledge), an agent can distinguish this create tool from the sibling memory_list/read/update/delete tools without inspecting 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 a clear when-to-use ("when the user asks to keep knowledge for future agent work") plus an explicit restriction ("secrets only at the user's direct request"). It does not name sibling alternatives such as memory_update for editing an existing record, so it stops short of full routing guidance.

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

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

Annotations only say destructive/not-read-only; the description adds real behavioral context beyond that: a two-tier permission model (author vs memory:moderate) and a version-based rejection rule that implies optimistic concurrency control. These are the exact traits an agent needs to call a destructive tool safely.

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 sentence with the action front-loaded and no filler. The compressed phrasing ('authors their own, moderators ... any but user-level ones') is efficient but requires a second read, which costs it the top mark.

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, fully documented, destructive operation with no output schema, the description covers authorization and the failure mode well. It stops short of stating whether deletion is permanent/recoverable and what the response returns, which would matter for an irreversible action.

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

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

Schema coverage is 100%, so the baseline is 3, but the description gives the version parameter a functional role beyond the schema's 'Record version the change is based on' — it is a concurrency token whose mismatch causes rejection. That meaningfully upgrades what the agent knows about the parameter.

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

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

States a specific verb (Deletes) and resource (agent memory record) and scopes it to a user-initiated action, which cleanly separates it from memory_update, memory_read, and memory_create. An agent knows exactly what this 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?

Provides the governing authorization context: authors may delete their own records, moderators with memory:moderate may delete any but user-level ones, and the call is rejected under optimistic-concurrency conflict. It does not explicitly route between memory_delete and memory_update (e.g. prefer update over delete-and-recreate), so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: the permission (memory:moderate) changes the visible scope, and it discloses the usage-stat fields returned (deliveredCount, readCount, lastUsedDT). This is meaningful for a list tool with 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 action, then usage and parameter recipes. The second sentence is dense with several clauses, but each clause (moderate scope, moderation queue, cleanup pattern) contributes distinct, actionable information rather than 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 12-parameter list tool with no output schema, the description covers the conceptual model (record visibility), the key returned stats, and the two dominant workflows. It is close to complete; minor gaps are parameters like load/shared/level that neither schema nor description illuminate.

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

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

Schema coverage is 67%, so several parameters are already documented. The description adds interpretation the schema lacks: verified=false identifies the moderation queue, and the sort=usage + unusedDays pairing is explained as a rarely-used-records finder. It leaves some params (load, shared, level) implicit, keeping it below a 5.

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

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

The description states a specific verb and resource ('Lists agent memory records visible to the user') and adds scope via 'with filters and usage statistics'. It is distinguishable from siblings like memory_read (single record by ID) and memory_create/delete, though it doesn't name those siblings explicitly.

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

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

It gives concrete when-to-use context: 'reviewing, moderating and cleaning up memory', with the moderator pattern (memory:moderate scope, verified=false = moderation queue) and the cleanup pattern (sort=usage with unusedDays). It stops short of naming the alternative sibling (memory_read) for single-record retrieval.

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

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

readOnlyHint already declares the safe-read profile, but the description adds genuinely useful behavior beyond annotations: unavailable IDs surface in the `notFound` field rather than erroring, and rule lookups use slugs while records use UUIDs. That is real operational context not available in structured fields.

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

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

Two tight sentences, front-loaded with what is returned and how it is keyed, followed by when it is useful. No filler; the notFound detail 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 single-parameter read tool with no output schema, the description covers input formats, scoping, and the partial-failure behavior (notFound). Return shape beyond that is unspecified, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% and the single `IDs` parameter is already documented, so baseline is 3. The description adds meaning above the schema by explaining the two ID formats (rule slugs vs. memory-record UUIDs) and the example `git`, clarifying what values are actually valid.

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 (agent memory records and MCP rules) with the key differentiator: full retrieval by ID, contrasted with the `memory` index used for discovery. An agent can distinguish this from memory_list without opening schemas.

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

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

Gives clear context ('Useful when a record from the `memory` index is relevant to the user's task'), which implicitly positions this as the follow-up to index/search tools. It does not explicitly name an alternative or state when not to use it, so it falls just short of 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?

With annotations covering only readOnlyHint=false and destructiveHint=false, the description carries the real behavioral load: partial-update semantics, level changes relocating the record, permission tiers (author vs memory:moderate), the side effect that content edits reset the record to personal and unverified, the human-moderator gate on verified/shared, and optimistic-concurrency rejection on stale version. This is materially more than the annotations convey.

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

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

It is a single dense semicolon-chained block, but the purpose is front-loaded and nearly every clause carries distinct information (semantics, permissions, side effects, concurrency). It could be broken into shorter sentences for scanability, but there is little filler to cut.

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 tool with no output schema, it covers permissions, side effects, partial-update semantics, and concurrency adequately. The main omission is what the call returns (e.g., the new version for subsequent updates), which matters for a version-guarded write.

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 every field, setting the baseline at 3. The description still adds cross-parameter meaning the schema does not: that passed fields are replaced (partial update), that level/projectID/repositoryID jointly move the record, and that shared/verified require moderator rights.

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 ('Updates an agent memory record') and immediately scopes the semantics ('passed fields are replaced, and a new level, projectID or repositoryID moves it'). It is unambiguous against memory_read/list/delete/create by name and content, though it never explicitly names a sibling to distinguish 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 clear operating context: the update is performed 'at the user's request', authors may edit their own records, moderators (memory:moderate) may edit any but user-level ones, and the call is rejected on version conflict. It stops short of explicitly naming alternatives (e.g., memory_create for new records), so it is clear context without full when/when-not routing.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is covered. The description adds genuinely non-structured behavior: a consent/authorization precondition tied to shared team ownership, which the agent could not infer 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?

Two short sentences, zero redundancy, and the core action is front-loaded before the consent caveat. Nothing could be trimmed without losing meaning.

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

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

For a simple 4-parameter create tool with full schema coverage and no output schema, the description covers purpose and the consent gate adequately. It leaves minor gaps such as the post-create result and whether a parent module must already exist.

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%: title, desc, parentID and productID are each documented, including that omitting parentID yields a root module. The description adds nothing about parameter format or defaults 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 ('Creates a product module'), which clearly distinguishes it from module_update and product_modules. It never names a sibling explicitly, so it stops just short of the 5 bar.

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 condition: only at the user's request or with their consent, framing the product structure as team-owned. It gives clear context but names no alternative tool or exclusion (e.g., when to prefer module_update), so it is clear-but-incomplete rather than exhaustive.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false. The description adds real context beyond that: patch semantics ('omitted fields stay unchanged'), the consent requirement, and the fact that the main Figma frame can be removed. It does not clarify whether frame removal is reversible or what happens to components on the removed branch.

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

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

Two compact clauses with the functional scope front-loaded and the governance caveat second, no wasted words. The policy sentence is slightly tangential to the mechanical behavior but is short and justified by the safety framing.

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

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

Seven parameters, no output schema, and a mutation surface spanning rename, reparent, component add/remove, and frame removal. The description covers the scope and merge semantics adequately; the only unfilled gap is interaction between addComponentIDs and removeComponentIDs, which the schema also leaves unstated.

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

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

Schema description coverage is 100%, so the baseline is 3. The description earns above baseline by stating the merge/patch contract ('omitted fields stay unchanged'), which is semantic information the per-field schema does not convey and which materially changes how an agent builds the call.

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 (Updates) and resource (module) and enumerates the exact fields it can touch: name, description, parent, components, and removal of the main Figma frame. This is clearly distinguishable from module_create and product_modules in the sibling list 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?

Provides an explicit usage gate: only act at the user's request or with their consent, with the rationale that the product structure belongs to the team. It stops short of naming alternative tools or enumerating when-not cases, but the consent condition is a concrete, actionable constraint.

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 supply readOnlyHint=true; the description goes further by disclosing conditional behavior — passing 'job' additionally returns workspace conventions, team notes (memoryInstructions) and the memory index — and by distinguishing specExcerpt from the full spec under includeSpec. It stops short of describing the shape/format of the returned context or any 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 dense sentences that lead with what is returned and then layer the conditional job behavior. Every clause carries information, though the parenthetical-heavy second sentence is slightly packed for a single breath.

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

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

With no output schema, the description carries the burden of describing returns, and it does so well for the default case plus the job-augmented case. Missing only guidance on when this tool is the right one versus the other *_context siblings.

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 includeSpec toggles between excerpt and full spec, that job triggers extra return sections, and it labels defaultVersionID as the default for new work. It does not mention the localRepositories parameter.

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

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

States a specific verb and resource ('Returns a product's working context') and enumerates the concrete contents (project, spec excerpt, analyst/lead, unfinished versions, repositories, design files). It is clearly a retrieval tool, but it never distinguishes itself from siblings in the same family such as feature_context, task_context, or repo_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?

Usage is only implied: an agent can infer you call this to orient on a product before doing work. There is no explicit when-to-use, when-not-to-use, or comparison against the sibling context tools, and no stated prerequisites.

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

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

Annotations only declare readOnlyHint=true. The description adds real behavioral context beyond that: archived products are excluded, and the default return is a project's first active product. This helps the agent predict output shape without contradicting the safe-read annotation.

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 compound sentence that leads with what is listed and then qualifies scope and defaults. Efficient, though the semicolon-joined clauses are slightly dense.

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, single-parameter list tool with no output schema, the description covers the essentials: what is returned, what is filtered out, and the default selection. Sufficient for correct invocation.

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

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

Schema coverage is 100%, so projectID is already fully documented as an optional filter. The description restates that it 'narrows the list to one project' but adds no extra syntax or format meaning, 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 ('Lists projects with their active products') and adds scoping detail (archived products excluded). It does not explicitly differentiate itself from nearby siblings like product_context or product_modules, so it falls short of a 5.

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

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

'Useful for choosing the product to work in' provides an implied use case, giving some context for when the tool applies. However there are no explicit conditions, exclusions, or named alternatives (e.g., when to prefer product_context), leaving usage largely 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?

readOnlyHint=true already covers the safety profile, so the description's value is in the extra rules it discloses: desc and design are returned only for items listed in IDs, a module does not imply its components, and query is a case-insensitive name substring in the workspace language. These are non-obvious behavioral constraints that the annotations do not carry. It omits list-size/pagination behavior beyond the schema's maxItems hint.

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

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

Single dense block, front-loaded with the return contents, which is good. However it runs on with parenthetical field mappings ('snapshotFID - snapshot, contextFID - layers') that read like raw schema notes rather than agent-facing prose, hurting scanability.

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

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

With no output schema, the description does carry the return-shape burden and describes modules, components, desc, and design, plus the IDs-conditioned inclusion rule. It leaves the pagination/limit story (maxItems 50 on IDs, any cap on returned modules) and the snapshotFID/contextFID meanings somewhat 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 the baseline is 3, but the description adds genuine semantics: IDs gates whether desc/design payloads are populated, and query filters by name case-insensitively in the workspace data language. That is meaningfully more than the schema's terse field text, though the cryptic 'snapshotFID - snapshot, contextFID - layers' shorthand is hard to parse.

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

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

Opens with a specific verb and resource: 'Returns the product structure for tagging tasks and bugs: modules ... and components.' That clearly separates it from siblings like product_context, module_create, or component_create. It stops short of naming alternatives explicitly, but the resource scope is unambiguous.

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

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

The phrase 'for tagging tasks and bugs' implies the use context, and the IDs/query clauses hint at retrieval patterns, but there is no explicit when-to-use, when-not-to-use, or alternative tool named (e.g., product_context or component_update). Usage must be inferred.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the burden of what actually happens. It discloses that only passed fields change and that isArchived pulls versions, features and tasks out of work selection. Archiving is described as reversible (restore), so this does not contradict destructiveHint=false.

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

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

Purpose and the partial-update qualifier are front-loaded, and every clause (field scope, return context, archive side-effects, consent rule) adds information. It is a dense run-on sentence with semicolons rather than cleanly separated sentences, which slightly hurts scanability.

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 mutation with a nested design object, 100% schema coverage, and no output schema, the description covers the essentials: partial semantics, the returned context, the archive side-effect, and the consent constraint. It omits nothing an agent would need to call it correctly, though naming the read-only sibling would complete the picture.

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 already documents per-field replacement semantics, so the baseline would be 3. The description earns the extra point by explaining the cross-system consequence of the isArchived parameter (versions/features/tasks leave work selection), which 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+resource ('Changes a product') and qualifies the mutation as partial ('only the passed fields'), which is meaningful precision for an agent. It does not name or differentiate against siblings such as product_context or product_list, 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?

Gives an explicit permission condition for the risky path: 'Changes shared product structure; only at the user's request or with their consent.' That is real when-to-use guidance. It names no alternatives (e.g., read-only product_context) and states no exclusions, so it is not a 5.

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

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

Annotations only declare readOnlyHint, and the description meaningfully extends that: it discloses the output shape (ranges attributed to a commit sha plus commit metadata), a 204800-byte cap with the startLine/endLine workaround, and the 'renames are not tracked' limitation. Missing pagination/error behavior, but the added operational constraints are substantive.

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 with the core purpose front-loaded and no filler. The output-format clause is packed tightly, which slightly strains readability 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 burden of explaining returns and does so (ranges, commits with title/message/author/dates), plus byte limits and rename behavior. Auth/prerequisite context is absent but not critical for a read-only query.

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

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

Schema coverage is 100%, so each parameter is already documented at baseline 3. The description adds value by explaining the purpose of startLine/endLine (range reads for large files) beyond the schema's mechanical definition, slightly clarifying their role.

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 even outlines the return structure (ranges and commits). It is easy to distinguish from generic list/search tools, though it never names the closest sibling (repo_line_history) to draw a hard boundary.

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

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

Offers one concrete usage scenario ('blame at the parent of a fix commit shows the lines as they were before the fix'), which implies when the tool is useful, but gives no explicit when-to-use/when-not guidance or routing against sibling tools like repo_line_history or repo_history.

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, so the safety profile is covered. Beyond that, the description discloses return content (sha, default/protected flags) which is the only source of return information since no output schema exists, adding real behavioral value.

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

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

Two tight sentences, front-loaded with what the tool returns, followed by the filter semantics. Every clause earns its place with no filler.

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

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

For a two-parameter read-only listing tool with full schema coverage, the description covers purpose, filter semantics, and return fields. The one gap is that it never routes the agent away from the closely named branch_list/branch_name siblings.

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 meaning beyond the schema's terse 'Branch name substring' by showing that a task ID like '#26388' resolves to that task's live branch — a non-obvious matching semantic the schema 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?

States a specific verb and resource ('Lists repository branches') plus the attributes returned (sha, default/protected flags). However, it never distinguishes itself from the sibling tools branch_list and branch_name, leaving the agent to guess which branch-listing tool to pick.

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

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

Usage is only implied: the search example ('#26388' finds the live branch of that task) hints at when to use the filter, but there is no explicit when-to-use statement, no exclusions, and no mention of the alternative branch_list sibling.

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

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

Beyond the readOnlyHint annotation, the description discloses critical runtime behavior: no truncation, pages capped at ~153600 bytes, the pagination contract (offset = nextOffset until null), that patch lines carry new-version line numbers, and that an oversized file yields an error together with baseSha and toSha. This is exactly the operational detail an agent cannot get from annotations or 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?

One dense sentence front-loads the core purpose, then layers pagination and error semantics in the order an agent needs them. Every clause carries information, though the run-on structure makes it heavier to parse than a split would be.

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

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

With no output schema, the description carries the burden of explaining return shape, and it does so for pagination, line numbering and the oversized-file error case. Edge cases such as binary-content handling or a maximum page count are not covered, so it is strong but not exhaustive.

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

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

Schema description coverage is already 100%, so 3 is the floor, but the description adds meaning the schema does not: how from/to interact (merge base vs straight), what lineNumbers controls in the output, and how offset is driven by nextOffset. The path, context and extensions parameters get no extra prose, which keeps it short of a 5.

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

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

States a specific verb and resource ('Returns the diff between two refs'), immediately distinguishing it from read-oriented siblings such as repo_history, repo_blame or repo_search. The scope is further pinned down by naming the default comparison basis (merge base of from and to, as in an MR).

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 guidance on when to flip the straight flag: 'as in an MR' for the merge-base default versus 'a previous review's sha' for direct comparison. It does not name alternative sibling tools or state exclusions, but the usage context for the key mode switch 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 only supply readOnlyHint=true, so the description carries the rest of the burden and does so credibly: it discloses the README is truncated to 16384 bytes and that the technical passport is stale and may be outdated. That freshness/truncation context is exactly what an agent needs to interpret results, though nothing is said about behavior for missing repositories or access-denied cases.

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 but front-loaded sentence with no filler; the payload contents come first and the use-case cue last. Slightly list-heavy, but every enumerated field earns its place in telling the agent what will come back.

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

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

There is no output schema, so the description must describe the return payload and it does so comprehensively, including the staleness caveat. It falls short only on error/edge-case behavior, which is a minor gap for a read-only overview 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% with a single parameter, so the schema already documents repositoryID fully. The description adds no format, constraint, or scoping detail for the parameter, making 3 the correct baseline.

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

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

States a specific verb ('Returns an overview') plus the exact contents of that overview: provider, URL, default branch and sha, linked projects, agent access level, README head, technical passport. This clearly separates it from granular siblings like repo_file, repo_tree, and branch_list, which return raw repository contents rather than a summary.

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 closing clause 'Useful for an unfamiliar repository' implies when to reach for it, but no alternative is named (e.g. repo_file/repo_tree for targeted lookups) and there are no exclusions or prerequisites. Usage is hinted rather than guided.

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 readOnlyHint=true by disclosing the 204800-byte response cap, the resulting need to paginate large files via startLine/endLine, that totalLines is returned, that symbol lookup is heuristic, and that a failed part carries its own error without affecting siblings. These are precisely the behavioral traits an agent needs and that annotations cannot convey.

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

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

A single dense sentence, but front-loaded with the core capability and the mode choice before drilling into limits and error handling. Every clause carries information; only the nested parenthetical about 'symbol' is slightly heavy.

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 covers returns (totalLines) and partial-failure behavior, and it addresses the byte cap that governs pagination. It stops short of describing the response shape (e.g. how content and errors are structured per part), which is the main remaining gap for an 8-parameter read tool.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantic value: it explains the path-vs-files duality (one file vs up to 20 parts), clarifies that symbol means a declaration 'with its leading comment' found heuristically, and ties startLine/endLine to the byte-limit workaround. That exceeds what the schema's terse field descriptions 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?

States a specific verb and resource ('Reads files at a ref') and immediately enumerates the two modes (single 'path' vs up to 20 'files' parts) and the three part types (whole file, line range, declaration). This distinguishes it clearly from siblings like repo_search, repo_blame, and repo_history.

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

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

The description implies when each mode applies (single file vs batched parts; ranges when files are large), but never explicitly says when to prefer this over file_get, repo_context, or repo_search. Usage is inferable from the mechanics rather than stated as guidance or 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, so safety is covered, yet the description adds real behavioral context the annotations lack: pagination behavior, the hasMore next-page marker, and the set of returned fields including taskKeys and linked tasks. This is genuinely additive for a read 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?

A single sentence front-loads the purpose and then appends the return/pagination details with no filler. It is dense (the parenthetical field list) 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 compensates by enumerating the returned fields and the pagination flag, and annotations cover the safety profile. Parameters are fully covered by the schema, leaving little an agent must guess to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents ref, path, page, perPage and repositoryID in detail. The description only echoes 'ref, file or directory' and adds no syntax or format guidance beyond the schema, so the baseline 3 is correct.

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

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

States a specific verb and resource ('Returns the commit history of a ref, file or directory') and reinforces it with the 'like git log' analogy, which cleanly separates it from line-level siblings such as repo_line_history and repo_blame. It stops short of naming a sibling it is not, so it sits at 4 rather than 5.

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

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

The 'like git log' framing implies the usage context, but no explicit when-to-use/when-not or alternative routing is given (e.g., vs repo_line_history, repo_compare, or task_commits). Usage is reasonably inferable but not stated.

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

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

With readOnlyHint=true already covering the safety profile, the description goes well beyond it: it discloses truncation ('up to 100 (truncated beyond)'), ordering ('newest first'), the candidate/approximate nature of results due to line shifting, and the semantics of linkType (message vs branch) and match=path. This is exactly the behavioral context an agent needs before trusting the output.

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 opening clause, followed by scoping constraints, then caveats about result reliability. It is a single dense sentence with stacked parentheticals, which costs a little readability, but there is essentially no filler text.

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

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

No output schema exists, so the description must characterize returns — it does so reasonably (who, which task, newest first, cap of 100). It stops short of describing the returned fields or pagination/limit interplay with the default of 30, which is a minor remaining gap for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning the schema lacks — the linkType explanation (message = task key in message, branch = commit on task branch) and the match=path behavior where line ranges are ignored for that commit. The startLine-endLine relationship to range filtering is also clarified beyond the raw schema strings.

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

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

The description names a specific verb+resource (show who changed lines startLine-endLine of a file and in which task) and pins down the data source and ordering (commits synced to Kosmodrom, all branches, newest first). This distinguishes it from the nearest sibling, repo_blame, by tying results to task-linked commits rather than raw attribution.

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

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

Usage context is implied through hard scoping rules — 'only task-linked commits are included' and 'results are candidates' — so an agent can infer this is for task-linked annotation, not exhaustive blame. However, no sibling alternative is named (e.g. repo_blame for non-task attribution), leaving selection 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 readOnlyHint=true, so safety is covered. The description adds real behavioral context beyond that: hard caps of 200 lines and 50 files per query, truncation beyond those, case-insensitivity defaulting, and empty-result meaning. It does not describe error conditions or ref-resolution failures.

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 and front-loaded with purpose first, then parameter modes, then limits. It is effectively one very long sentence with heavy parenthetical nesting, which slightly hurts scanability, but nearly every clause carries information an agent needs.

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 tool with no output schema, the description covers the return format, per-query caps, and the query/regex interplay. It leaves unaddressed multi-repo or auth scoping and error behavior, but nothing critical for 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 baseline is 3, but the description genuinely adds semantics the schema does not: regex 'filters query matches or, without query, scans the files under path' — a two-mode interaction no parameter description conveys, plus the query/queries relationship and the caseSensitive override. Useful added value over structured fields.

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 with scope ('searches code at a ref (task branch, tag or sha)'), anchors it to a familiar mental model ('like git grep'), and describes the exact output shape ('path:line: text' lines). This is enough to distinguish it from siblings like repo_file, repo_blame, and repo_history 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?

Usage is implied rather than stated: 'query' vs 'queries' vs 'regex' establish when each mode applies, and 'an empty result means no match at that ref' clarifies outcome semantics. But no sibling is named (e.g. feature_search, repo_blame) and there are no explicit when-not-to-use conditions, so an agent must infer routing.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does it well: it discloses the 500-entry cap, the 1-4 level depth window, that results are truncated when cut off, and that a resolved sha is returned. These are genuine behavioral traits beyond the annotation, though nothing is said about pagination or error/auth behavior.

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

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

Two dense sentences, front-loaded with the operation and followed by the operational limits. Every clause carries information (entry cap, depth, truncation, returned sha) and there is no filler.

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

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

With no output schema, the description responsibly mentions the returned resolved sha, plus the truncation and depth constraints an agent needs to interpret results. It is close to complete for a read-only listing tool, missing only pagination and any hint about error conditions.

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, path, depth, and repositoryID. The description restates the ref and depth semantics ('at a ref', '1-4 levels below path') without adding syntax or format details the schema lacks, which is the baseline-3 case.

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 (a repository directory at a ref), which is enough to tell it apart from repo_file, repo_blame, or repo_history by resource type. It does not explicitly name any sibling, so it stops short of a 5.

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

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

There is no when-to-use, when-not-to-use, or alternative routing guidance. With siblings like repo_search, repo_file, and repo_context available, an agent gets no help deciding when a directory listing is the right call versus those tools.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful semantics beyond the annotation, such as expiresAt being null when there is no expiry and the memory index being reference material. It omits any note on auth requirements or caching, but for a read-only tool the burden is low.

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 sentence front-loads the core identity/auth fields before the memory-related clauses. Every clause maps to a returned field, though the trailing 'as reference material' phrasing is slightly 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, the description carries the burden of explaining return values, and it enumerates the key fields (owner, company, language, scopes, allows, expiresAt) plus the memory index. It is reasonably complete, though it could clarify the relationship between memoryInstructions and the memory records.

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

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

The tool takes zero parameters, so the baseline is 4. The schema requires nothing and the description correctly implies there is no input to negotiate.

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?

Clear verb+resource: it returns the session/token context including owner, company, language, scopes, privileges, and expiry. This is a distinct resource from siblings like user_context and product_context. However, it never explicitly distinguishes itself from user_context, which likely overlaps on the owner information.

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 is given. It does not say to call it at session start, to establish identity/permissions before other tools, or how it relates to the memory_list/memory_read siblings it indexes. The agent must infer the trigger condition entirely.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes far beyond by spelling out the state machine (done routes to review, deployment, testing, or close), the reopen restriction to the token owner in the current iteration, that result is not written here, and that done returns feature.plan. This is exactly the extra behavioral context annotations cannot carry.

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

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

Front-loaded with the core action and dense with useful detail, and no sentence is pure filler. However it is delivered as one long run-on chain, which makes the transition list harder to scan than a shortened enumerated form would be.

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

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

For a 4-parameter mutation tool with no output schema, it covers the key preconditions (allowedTransitions), the required comment, and the post-transition outcomes, and even hints at the done response. It stops short of describing the general response shape, which is the remaining gap given no output schema exists.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains what each transition value does and states that comment is required for decline and reject, plus ID being preferred over key. This goes beyond the bare enum and 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?

Names a specific verb (moves) and resource (a task or bug) scoped to lifecycle transitions in shared team data, which clearly separates it from siblings like task_update, task_create, and task_delete. An agent can tell what it 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?

Enumerates each accepted transition (work, pause, wait, publish, accept/decline, reject, done, reopen) with its meaning, giving strong per-case guidance. It also states the precondition that only the task's allowedTransitions are accepted, but never names alternative tools (e.g., task_update) or when-not-to-use this 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?

The readOnlyHint annotation already tells the agent this is a safe read, so the bar is lower; the description still adds real scope boundaries beyond the annotation — MRs are returned as links with review threads deliberately left at the git provider, repositories are ordered main-first, and "reading hints" are included. It does not mention pagination, result limits, or behavior when the task has no code, which keeps it below 5.

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

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

Two sentences, front-loaded with the returned artifacts and closed with the use case; no filler or repetition. The first sentence is dense with parenthetical asides, which slightly taxes readability 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 compensates well by enumerating the return contents (repos, branches, commits, MRs, hints) so the agent knows what to expect. Combined with the readOnly annotation and fully documented parameters, the definition is nearly self-sufficient; only pagination/empty-state behavior is 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 description coverage is 100% and both parameters (ID, key) are documented in the schema, including the "key if the ID is unknown" fallback. The description says only "a task's code" and adds no syntax, format, or ID-vs-key guidance, so the baseline of 3 for schema-carried parameters is correct.

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

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

States a specific verb and resource ("Returns a task's code") and then enumerates the payload precisely: product repositories in main-first order, live branches carrying the task key, commits with stats and paths, the task's MRs, and reading hints. This scope enumeration implicitly separates it from siblings like task_commits or repo_context. It stops short of naming any alternative tool, so it lands at 4 rather than 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 when the user asks how a task is implemented or wants it reviewed" gives a clear positive trigger for invocation. There are no exclusions and no routing against the many adjacent tools (task_commits, task_context, feature_code_context), so it is clear context without the when-not guidance a 5 would require.

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 readOnlyHint=true already covering the safety profile, the description adds genuinely non-structured context: commits come specifically from synced repositories, and it defines the linkType classification ('message' = '#<key>' in the commit message; 'branch' = commit on the task branch without the key). That linkType semantics is real behavioral/domain information absent from annotations and 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?

Two sentences, front-loaded with the core purpose and return shape before the linkType detail. The linkType notation is terse to the point of being slightly cryptic, but there is 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 read-only, output-schema-less tool, the description supplies the returned fields and the linkType semantics an agent needs to interpret results. The remaining gap is that it never states both parameters are optional or what happens if neither ID nor key is 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 description coverage is 100% (both ID and key are documented, including the 'without #' nuance), so the schema carries the parameter burden and a 3 baseline applies. The description adds no parameter meaning of its own beyond the mention of '<key>' inside the linkType explanation.

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

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

States a specific verb and resource ('Returns a task's commits') and scopes the source ('from the product's synced repositories'), enumerating the returned fields. This clearly distinguishes it from generic repo tools, though it never names the closest siblings (repo_history, task_code_context) that an agent might confuse it with.

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

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

There is no when-to-use or when-not-to-use guidance. Nothing tells the agent how this differs from repo_history, repo_compare, or task_code_context, and the schema (not the description) is the only place that notes key is a fallback when ID is unknown, so the selection logic is left implicit.

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