Orbit

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds the null return behavior, which is a useful behavioral detail beyond what annotations provide. 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?

A single concise sentence that is front-loaded with the action and resource. No wasted words.

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

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

For a zero-parameter getter with annotations covering safety, the description is fully complete. It specifies what is returned and the null case, and there is no missing information an agent would need to invoke it correctly.

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

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

There are zero parameters, so the description has nothing to explain. The baseline for 0 params is 4, and the description correctly omits any parameter discussion.

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 ('return') and resource ('sprint'), and clarifies it refers to the currently running sprint, distinguishing it from sibling tools like list_cycles. It also mentions the null case, which further pins down the behavior.

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

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

The use case is clear from the purpose: if you need the current sprint, use this. However, it does not explicitly mention alternatives or exclusion conditions, such as 'for all sprints use list_cycles'.

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 indicate this is a mutating, non-idempotent, non-destructive action Themes. The description adds that the body is markdown and that replyTo makes it a reply, but it does not disclose any additional behavioral traits such as permissions, duplicate-creation behavior, or side effects beyond the annotations.

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

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

A single sentence with no filler, front-loading the core action and then the optional reply behavior. Every word 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 low-complexity create operation with complete schema coverage, useful annotations, and no output schema, the description covers the essential behavior and optional reply case. No critical operational detail appears to be missing.

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

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

Schema description coverage is 100%, so the schema already documents body, issue, and replyTo. The description restates the markdown nature of the body and the reply behavior, which aligns with the schema but adds little new meaning 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?

The description uses a specific verb ('Post') and resource ('markdown comment on an issue'), and optionally clarifies the reply behavior. This clearly distinguishes it from siblings like comment_on_doc (which targets docs) and edit_comment/delete_comment.

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

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

The description provides clear context for when to use the tool: posting a markdown comment on an issue, optionally as a reply. It does not explicitly name alternatives or exclusions, but the resource distinction from comment_on_doc is evident from the wording and sibling names.

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

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

The description adds behavioral context beyond the annotations by explaining the consequence of the action: the member gains access to the team's issues and sprints. It does not detail error cases or side effects, but the annotation flags already cover mutability, idempotence, and destructiveness.

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

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

The description is a single concise sentence with no filler. The action is stated first and the outcome is appended efficiently.

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

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

For a simple two-parameter mutation tool with fully documented schema parameters, the description is sufficiently complete. It names the operation and its practical effect; only explicit return-value behavior or permission requirements are not addressed.

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 clear descriptions for both 'team' and 'person' including accepted formats. The tool description does not add parameter-level detail beyond what the schema already provides, 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?

The description uses a specific verb and resource: 'Put a workspace member on a team' and explains the intended effect 'so they see its issues and sprints.' This clearly distinguishes the action from sibling tools like remove_team_member or invite_member.

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 makes the usage context clear: the person is already a workspace member and the goal is granting them team-level visibility. It does not explicitly list when-not-to-use it or point to invite_member as the alternative, but the context is unambiguous.

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

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

Annotations mark the operation destructive (destructiveHint=true), and the description adds an important clarification that content is kept, thereby softening the destructive signal and describing the side effect of leaving the sidebar/listings. It doesn't mention reversibility or permissions, but the added context is meaningful.

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

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

Two short sentences with no filler: the action is stated first, followed by the two key effects (removal from UI listings and content retention).

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

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

For a one-parameter tool with a clear schema, the description covers the operation's outcome and non-destructive nature. It doesn't describe the return value or how to undo, but these are not necessary for a correct invocation of this simple tool.

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

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

The schema already documents the single parameter clearly as a document ID or exact title, with 100% coverage. The description adds no additional parameter semantics, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Archive'), names the resource ('a document'), and states observable effects: it leaves the sidebar and default listings while content is kept. This clearly distinguishes archive_doc from delete_doc and aligns with unarchive_doc as the inverse operation.

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

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

It gives clear context for when to use the tool: when the goal is to remove a document from the sidebar and default listings without deleting its content. It stops short of explicitly naming alternatives such as delete_doc or unarchive_doc, but the behavioral cues make the intended use obvious.

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 mark this as destructive, and the description adds useful context about what archiving does to the issue: it leaves the board and default lists. It does not mention reversibility via unarchive_issue, but the core behavioral effect is disclosed.

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

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

The description is two short sentences with no wasted words. The core behavior is stated first, and the alternative tool is mentioned second, making it easy to scan and act on.

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

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

For a one-parameter tool with no output schema, the description fully covers what the agent needs to know: what archiving does, how it differs from deleting, and what input is required. Nothing essential is missing.

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

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

The input schema already provides complete documentation for the single 'issue' parameter with a clear example. Since schema description coverage is 100%, the description does not need to add parameter-level detail, and it does not.

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

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

The description clearly defines the action: 'Archive an issue so it leaves the board and the default lists.' It names a specific verb and resource entity, and immediately differentiates itself from delete_issue, which is the key sibling to distinguish against.

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

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

It explicitly states the effect of archiving and points to delete_issue as the alternative when permanent removal is intended. This gives the agent a direct decision rule for choosing between archive and delete.

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 mark the tool as destructive, and the description adds meaningful context by specifying that issues are kept and the project only leaves active lists. This clarifies the actual scope of the destructive operation beyond the raw 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?

Two short sentences deliver the essential information with no filler. The key behavioral guarantee ('leaves the active lists', 'issues are kept') is front-loaded and immediately actionable.

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

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

For a tool with one simple parameter, no output schema, and adequate annotations, the description covers the essential call-time knowledge: what it does and what it preserves. It does not discuss reversibility or side effects on other project resources, but that is a minor gap given the tool's simplicity.

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

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

The schema already fully documents the single parameter with a clear description ('Project name, slug or id.'). The tool description adds no additional parameter-level detail, so the schema carries the semantic load.

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

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

The description clearly states the action ('Archive a project'), the resource, and the concrete effect: it leaves the active lists while keeping issues. This distinguishes it from delete_project (which would destroy) and from archive_doc/archive_issue, which target different resource types.

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

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

The description implies the use case: when you want the project out of active lists but still want its issues retained. However, it does not explicitly tell the agent when to choose this over delete_project or update_project, nor does it mention 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 already declare readOnlyHint=false (mutation) and destructiveHint=false, so the safety profile is known. The description adds the return URL behavior and its markdown usage, which is a useful behavioral note, but it doesn't disclose permissions, reversibility, or side effects. 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?

The description is one sentence plus a return-format note, front-loaded with the verb and target types. Every word earns its place, with no filler or redundancy. Highly concise and well-structured.

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

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

For a 5-param mutation tool with 100% schema coverage and no output schema, the description provides the essential purpose and return format. It doesn't cover edge cases (e.g., ID restrictions), but those are in the schema. Given annotations, this is adequately complete for an agent 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%, with each parameter having a description. The tool description only reiterates the parent types from the enum and does not add meaning beyond the schema. Baseline 3 is appropriate since the schema carries the parameter semantics.

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

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

The description states a specific verb ('upload and attach') with a clear resource ('file') and target types ('issue, comment, doc or project'). It also specifies the return output (a markdown URL), making its purpose unambiguous and distinct from sibling tools like list_attachments or read_attachment.

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

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

The description implies usage by stating the action, but it does not explicitly contrast with alternatives or provide when-to-use/when-not-to-use guidance. For instance, it doesn't differentiate when to attach vs. list or read attachments. The intent is clear but relies on 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?

The annotations already convey that this is not read-only, not idempotent, and not destructive. The description adds the 'Markdown' detail and makes the mutating nature explicit with 'Add,' which is consistent with the annotations. No deeper behavioral context, such as whether the comment is appended or how the comment is stored, is provided.

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

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

A single, front-loaded sentence conveys the verb, target, and content format with no wasted words. It is appropriately concise for the simplicity of the operation.

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

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

For a simple two-parameter write operation, the description combined with the rich schema and annotations is nearly complete. It tells the agent what to do and the schema fully defines the parameters; the main missing piece is routing guidance among related comment tools, which is captured separately under usage guidelines.

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

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

Input schema documentation coverage is 100%, with both 'doc' and 'body' described. The description adds no parameter-specific meaning beyond what the schema already provides, 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?

The description states a specific verb ('Add'), a resource ('a document'), and the format ('Markdown comment'), making the tool's function clear. It distinguishes itself from sibling tools like add_comment by specifying the target is a document, though it does not explicitly name or contrast alternatives.

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

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

There is no guidance on when to use this tool versus alternatives such as add_comment, edit_comment, or list_doc_comments. The description implies usage for adding a comment to a document but provides no exclusions or decision criteria.

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 signal destructiveHint=true, so the description only needed to add useful context. It does so by disclosing that unfinished work rolls into the next sprint rather than being left behind, which is the key behavioral consequence beyond the annotation. It could mention reversibility or permissions, but the core destructive trait is already covered.

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

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

The description is two sentences with the primary action front-loaded. The second sentence earns its place by explaining what happens to unfinished work. There is no filler or redundant restatement 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 one-parameter destructive close operation, the description plus destructiveHint and the self-explanatory cycleId provide enough to call the tool correctly. The main gap is orienting the agent against related cycle/sprint tools, but that is more of a usage-guidance issue than an invocation blocker.

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

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

Schema description coverage is 0%, and the description never mentions cycleId directly. 'Close a sprint' lets an agent infer that cycleId identifies the sprint, but it adds no explicit parameter meaning, format guidance, or value constraints. Because the schema is bare and the description does not compensate, this is below baseline.

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

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

The description uses a specific verb and resource: 'Close a sprint.' This clearly distinguishes completion/closure from sibling actions such as start_cycle, create_cycle, update_cycle, and delete_sprint. The title 'Complete a sprint' reinforces the lifecycle 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?

The phrase 'Close a sprint' implies this is for ending a sprint, and the second sentence explains the rollover consequence. However, the description does not explicitly say when to prefer this over related tools like update_cycle or start_cycle, and it offers no exclusions or prerequisite 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, destructiveHint=false, and idempotentHint=true, covering safety. The description adds value by specifying the output format and that the name follows Orbit's convention, which is beyond the annotations. It doesn't describe error cases, but for a read-only lookup 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?

A single sentence with zero filler. It front-loads the action and includes the essential output format without redundancy.

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

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

For a simple read-only tool with one parameter and no output schema, the description is complete: it states the purpose, the parameter (via schema), and the output format. Annotations cover safety. Minor gaps like error handling aren't necessary for correct invocation.

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

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

Schema description coverage is 100% – the 'issue' parameter is clearly described as an identifier like 'ENG-42' or an issue id. The description adds no further parameter semantics, 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?

The description states a specific verb ('Return') and resource ('git branch name Orbit uses for an issue'), and gives the exact output format ('handle/eng-42-short-title'). This clearly distinguishes it from any sibling tools, none of which return branch names.

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 purpose is self-evident: use when you need the git branch name for an issue. It doesn't explicitly mention alternatives or when not to use it, but given the unique function, the context is clear enough. No exclusions are needed.

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

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

Annotations provide only basic flags (not read-only, not idempotent), so the description carries the burden. It discloses the key default behavior when no dates are sent, but does not explain what happens when only one date is provided, what the response contains, or any side effects. This is a useful but incomplete disclosure for a mutation tool.

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

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

The description is two sentences with no fluff. The primary action is front-loaded ('Open a new sprint...'), followed by a concise clarification of the default behavior. Every sentence earns its place.

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

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

Given the tool's moderate complexity (4 params, no output schema, minimal annotations), the description covers the core purpose and a critical default behavior. It lacks information about the return value and edge cases, but for a create operation this is reasonably complete for an agent to invoke correctly.

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

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

Schema coverage is 75% with descriptions for team, startsAt, and endsAt, but name has none. The description adds the combined behavior of omitting both dates, which clarifies the relationship between startsAt and endsAt, but it doesn't explain the name parameter or provide additional parameter-level detail beyond the schema.

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

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

The description clearly states the tool opens a new sprint (cycle) for a team over a date range, using a specific verb and resource. However, it doesn't explicitly differentiate from sibling tools like start_cycle or update_cycle, though the verb 'create' in the name and title makes the intent 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 description implies usage for creating a new sprint and provides a specific invocation pattern (sending neither date) that triggers a default one-week sprint appended after the last one. It does not offer exclusions or alternatives, such as when to use start_cycle instead, so guidance is only partially 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?

The description adds a key behavioral constraint not present in the annotations: 'A document lives in a collection or in a project, never both.' It also clarifies the content modality options. It does not cover permissions or side effects, but the annotations already signal this is a mutating, non-destructive operation.

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

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

Three sentences with no filler. The first sentence states the purpose, the second covers placement options, and the third states the key constraint. Every sentence earns its place and the most important information is front-loaded.

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

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

For a 7-parameter create tool, the description plus the fully documented schema covers most agent needs. Minor gaps remain: it does not describe the response/returned document identifier, and it does not clarify behavior when optional fields like kind or content are omitted.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining cross-parameter semantics: the exclusivity of collection vs project, the nesting relationship via parent, and the mapping of kind/content to Markdown or HTML. This goes beyond the field-level schema descriptions.

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

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

The description uses a specific verb and resource ('Create a document') and immediately spells out the two body formats (Markdown or HTML) and the three filing options (collection, project, parent). This clearly distinguishes it from sibling tools like create_doc_collection or update_doc.

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

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

It gives clear context for when to use the tool: creating a document and optionally placing it under a collection, project, or parent doc. It does not explicitly name alternative tools or say when not to use it, so it stops short of a 5, but the usage context is unambiguous.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false) and non-destructive, so the safety profile is covered. However, the description adds no additional behavioral detail such as side effects, required permissions, or implications of creating a collection. It merely restates the operation in simpler terms.

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 no filler or redundant detail. Every word contributes to conveying the purpose, and the analogy to a folder makes it immediately understandable.

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

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

For a simple two-parameter create tool with no output schema, the description is minimally adequate. It conveys the core concept but omits any context about naming conventions, whether collections have hierarchy, or how collections relate to other entities. Given the tool's simplicity, this is acceptable but not comprehensive.

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

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

Schema coverage is 100%, so both parameters (name and icon) are fully documented. The description adds only the conceptual 'folder' metaphor, which adds marginal meaning but does not elaborate on parameter formats, optionality, or constraints 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 uses a specific verb ('Create') and resource ('document collection' described as a folder). The phrase 'documents can be filed under' clearly distinguishes this from creating a document (create_doc) by implying a container role, even 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?

No guidance is given about when to use this tool versus alternatives like create_doc, update_doc_collection, or delete_doc_collection. There are no prerequisites, exclusions, or context about typical use cases, leaving the agent to infer from the description alone.

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

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

The description adds value beyond annotations by explaining that the workflow state defaults to the team's first unstarted state and that the tool returns the new issue with an identifier like 'ENG-42'. Annotations only indicate non-readonly, non-idempotent, non-destructive, leaving these specific behaviors undisclosed; the description fills that 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?

Two sentences, no filler. The core purpose is front-loaded, followed by the most important behavioral nuance (state default) and the return value. Every sentence contributes actionable information.

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

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

Given the 13 optional/required parameters, the schema itself is comprehensive, so the description does not need to repeat them. It covers the key non-obvious behaviors: default state and return identifier. The only minor gap is the lack of explicit guidance on choosing this over related issue tools, but the tool can still be invoked correctly with the information 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 coverage is 100%, so baseline is 3. The description enriches the semantics of the optional 'state' parameter by specifying the default behavior when it is omitted: the team's first unstarted state. It also explains the output identifier, which helps the agent understand what to expect. This goes beyond the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Create an issue on a team.' It clearly identifies the action (create) and the target (an issue), and is easily distinguished from sibling tools like create_doc, create_project, or update_issue. The added scope 'on a team' further clarifies the primary input.

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

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

The description implies usage: you create a new issue when you need a new issue on a team. However, it does not explicitly state when not to use it, nor does it point to alternatives like update_issue for existing issues or archive_issue for closing them. The context is clear but not fully 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 only set readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false. The description adds the team scoping behavior (workspace-wide vs team-specific) which is beyond annotations and useful. However, it does not disclose error handling (e.g., duplicate name) or idempotency, which are common gaps for a create operation. It adds some behavioral value but not extensive.

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 sentences, front-loaded with the core purpose and then the key behavioral nuance. Every sentence earns its place, with no redundancy or filler. It is appropriately sized for the tool's simplicity.

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 create tool with three parameters and no output schema, the description covers the purpose and the critical team scoping behavior. It does not mention duplicate name handling or the response object, but these are not essential given the schema and annotations. Overall, it is sufficiently complete for an agent 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% for all three parameters, so the baseline is 3. The description clarifies the team parameter's effect (restricting to team vs workspace-wide) which slightly adds value beyond the schema's description, but it does not elaborate on name or color semantics. The added value is minimal, so a 3 is appropriate.

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

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

The description clearly states the tool creates a label and explicitly says it can be applied to issues, distinguishing it from other creation tools like create_state or create_team. It is specific about the resource and does not merely restate the name.

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

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

The description gives clear context: it creates a label and explains the team scoping option. It does not explicitly name alternatives like update_label or delete_label, but the create action is self-evident and the team behavior clarifies when to use this tool. There are no exclusions stated, but the context is adequate.

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 convey that this is a non-read-only, non-idempotent, and non-destructive operation. The description adds conceptual context about grouping work toward a date but does not disclose further behavioral details such as duplicate behavior, permissions, or required project existence.

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 and purpose. There is no wasted wording or redundancy, apart from the title, which is fine.

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 create operation with schema-documented parameters and no output schema, the description is largely sufficient. It could be slightly more complete by referencing the targetDate parameter or noting that the named project must already exist, but these are 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 50%, with project and targetDate already documented. The description helps clarify that 'name' is the milestone's name and that the milestone belongs to a project, but it does not add much meaning beyond the schema for the remaining parameters.

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

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

The description states a specific action ('Add') and resource ('a milestone to a project') and explains the purpose ('so work can be grouped towards a date'). This clearly distinguishes it from sibling tools like update_milestone, delete_milestone, and reorder_milestones.

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 usage is implied through the verb 'Add': this tool is for creating a milestone in a project. However, there is no explicit guidance about when not to use it or how it compares with related tools such as update_milestone or reorder_milestones.

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 indicate this is a non-read-only, non-idempotent write operation. The description adds an authorization requirement ('Requires a role that can manage projects') and the optional side effect of attaching teams, which are not captured in 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 with no filler. The core action is front-loaded and the permission caveat is delivered efficiently in the second sentence.

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 selection context, the optional teams behavior, and the permission prerequisite. It does not mention return values or duplicate/conflict behavior, but the schema and annotations cover most invocation details.

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

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

All 9 parameters are fully described in the schema (100% coverage), so the description adds little beyond noting that teams can be attached. The schema carries the descriptive load, meeting the baseline without adding significant extra 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 the specific verb 'Create' with the resource 'project' and adds the optional team-attachment behavior. This clearly distinguishes it from siblings like update_project, archive_project, and list_projects.

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

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

The description implies the obvious use—creating a new project—and provides a prerequisite ('Requires a role that can manage projects'). However, it does not explicitly state when not to use it or name alternatives such as update_project for modifying an existing project.

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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows this is a mutating, non-idempotent operation. The description adds useful behavioral context: the category drives product inference, and the new status lands at the end. This goes beyond the annotations and helps the agent understand consequences.

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

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

Three sentences, each earning its place: what it does, why category matters, and where the new status lands with a pointer to reorder_states. No fluff, front-loaded with the core action.

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 create tool with no output schema, the description covers the key behavioral aspects: category semantics and default placement. It doesn't mention return value or error cases, but those are less critical for a create operation with full schema coverage. The pointer to reorder_states completes the workflow context.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds meaning for 'category' by explaining it drives product inference, which is valuable. However, it doesn't add much for name, team, or color beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Add') and resource ('status to a team board'), and clarifies that it creates a workflow state. It distinguishes itself from siblings like update_state, delete_state, and reorder_states by noting the new status lands at the end and pointing to reorder_states for placement.

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

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

The description gives clear context: it's for adding a status to a team board, and it explicitly says to use reorder_states to place it. It doesn't explicitly mention when not to use it versus update_state or delete_state, but the context is clear enough for an agent to select it correctly.

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 indicate the tool is not read-only, not idempotent, and not destructive. The description adds that the team is created with specific features (issue prefix, workflow states, sprint), which is useful context but does not go beyond what the annotations imply about the creation action. No contradictions found.

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

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

The description is a single sentence with no wasted words, and the core action is front-loaded. It is efficient and easy to parse.

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

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

For a creation tool with three parameters and no output schema, the description is reasonably complete. It informs the agent what the team will include, which is sufficient for a standard create operation. It does not cover potential error cases or side effects, but those are not critical for basic 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 description coverage is 67% (key and name are described; description param is not). The description mentions 'issue prefix' which maps to the key parameter, but the schema already provides that context. The description does not add any parameter-specific detail beyond the schema, so it contributes minimal value here.

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

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

The description uses the verb 'Create' with the resource 'team' and adds specific details (issue prefix, default workflow states, first sprint) that distinguish it from sibling creation tools like create_issue or create_project. It clearly communicates what the tool does.

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 purpose is clear enough that an agent knows to use it for team creation, but there is no explicit guidance on when to use it versus alternatives, or any prerequisites or exclusions. Siblings like update_team and list_teams exist, but the description doesn't address them.

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 annotations, the description discloses strict unknown-key rejection ('A key this list does not name is rejected rather than dropped') and response-checking behavior ('The reply says how many conditions were stored, so check it matches what you sent'). These add real behavioral expectations not present in the annotation booleans.

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, usage, structure, strictness, and verification are all covered in a compact sequence, with the main instruction front-loaded. The fragment 'The saved view state.' is awkward, and some filter details duplicate the schema, but the complexity of the nested object justifies the length.

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

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

Given the nested filter object, lack of output schema, and mutation semantics, the description provides enough structure and caveats to call the tool successfully. It lists allowed keys, warns against unknown keys, and advises verifying the reply count. It does not provide a full example, but the list_views copy workflow compensates.

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

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

The schema already documents filter structure, and the description reinforces it while adding the practical instruction to copy an existing working filter. This helps an agent construct a valid filter. It adds less guidance for name, layout, groupBy, and shared, but the 60% schema coverage plus the copy-from-list_views workflow mitigates that gap.

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

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

The description opens with 'Save a filtered issue view,' a specific verb and resource that clearly identifies the creation action. It is distinguishable from siblings like update_view and delete_view, and the title reinforces the purpose.

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

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

The description gives explicit instructional context: 'Call list_views first and copy the filter of a view that already works.' This is clear practical guidance, though it does not explicitly contrast with update_view for modifying existing views.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the exact output structure (counts, points, changes, burn-up series), giving the agent a clear expectation of what data will be returned without needing an 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?

The description is a single, dense sentence that front-loads the purpose and lists the returned data concisely. It is not overly long or verbose, though it could be broken into a list for readability. Overall, it is efficient and well-structured.

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

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

With no output schema, the description carries the full burden of explaining return values. It does so thoroughly: counts, points totals, added/removed items, and a day-by-day burn-up series. It covers the key aspects an agent needs to know to call and interpret the tool correctly.

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

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

The input schema describes the only parameter 'cycle' with 'Sprint name, number, id, or "active"' (100% coverage). The description adds no additional meaning about the parameter. Per the rubric, with high schema coverage, the baseline score is 3, and the description does not go 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?

The description states a specific verb ('Return') and resource ('sprint progress'), and enumerates the exact data provided: scope, started, completed, cancelled counts, points totals, additions/removals, and a burn-up series. This clearly distinguishes it from sibling tools like project_progress or active_cycle, which have different focuses.

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

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

The description does not explicitly state when to use this tool versus alternatives. It implies usage from the title 'Get sprint progress', but there is no guidance on when this is preferable to project_progress, list_cycles, or get_analytics_overview. No exclusions or alternative conditions are mentioned.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive write. The description adds no additional behavioral context such as irreversibility, permission requirements, or effects on related data. It merely restates the action without enriching the annotation-provided safety profile.

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

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

The description is a single, tightly worded sentence with no filler. It front-loads the core action and scope ('Remove a comment from an issue.') and wastes no words, making it highly concise and 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?

Given the tool's low complexity (one simple parameter, no output schema) and that annotations already cover destructiveness, the description is sufficiently complete for an agent to understand the action. It could mention permanence or failure modes, but the existing annotation and schema fill most gaps, making the description adequate for a simple delete operation.

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

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

The input schema fully documents the single parameter commentId with a clear description, achieving 100% schema coverage. The tool description adds no extra meaning about the parameter, so it does not elevate beyond the schema baseline. Since the schema already handles it, a score of 3 is appropriate.

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

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

The description 'Remove a comment from an issue.' states a specific verb and resource, clearly distinguishing it from sibling tools like delete_doc_comment by specifying 'from an issue'. It is unambiguous and immediately conveys the tool's purpose.

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

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

The description implies usage for issue comments but provides no explicit guidance on when to prefer this over alternatives like edit_comment or delete_doc_comment. The context of 'from an issue' hints at the correct domain, but there is no stated exclusion or conditional 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 destructiveHint=true and readOnlyHint=false, so the description's confirmation of permanence adds value. The description goes beyond annotations by disclosing that nested pages are 'lifted to its own place rather than deleted,' which is a non-obvious behavioral consequence. This is valuable context beyond the structured hints.

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

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

The description is two concise sentences with no filler. The main action is front-loaded, the nested-page behavior is stated efficiently, and the alternative tool is mentioned in a separate sentence. Every word serves a purpose.

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 mutation with annotations already covering destructive behavior, the description covers the key aspects: permanence, nested-page handling, and the archive alternative. It does not mention permissions or other side effects, but those are not necessary for a simple delete operation given the annotations and schema. The description is sufficient for an agent to invoke the tool correctly.

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

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

The schema covers 100% of the single parameter with a clear description ('A document id, or its exact title'). The tool description adds no additional parameter guidance, so it relies on the schema. Given the high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the primary action—'Delete a document permanently'—which matches the title and adds the specific nuance of permanence. It also differentiates from the sibling archive_doc by naming it explicitly and contrasting the outcomes. This leaves no ambiguity about the tool's purpose.

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

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

The description provides explicit guidance on when to use this tool versus an alternative: 'Use archive_doc to hide a document instead of destroying it.' This directly instructs the agent to choose the appropriate sibling based on intent, making the usage context unambiguous.

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

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

Annotations already mark destructiveHint=true, so the safety profile is known. The description adds valuable behavioral nuance: documents inside are not deleted, they lose the collection link unless reassigned via reassignTo. This goes beyond the annotation and clarifies the non-recursive nature of the deletion, which is critical for an agent to predict consequences.

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 sentences with no filler. The core action is front-loaded, followed by the most important side effect. However, the first sentence 'Delete a folder' is slightly imprecise and could be tightened to 'Delete a document collection' for consistency. Overall, it is concise and structured well.

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

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

For a destructive tool with two parameters, one required, and no output schema, the description covers the essential behavior: what happens to documents when the collection is deleted. It also implies the optional reassignTo parameter. The annotations supply the destructive hint, so the description complements rather than repeats. No missing information critical for invoking the tool correctly.

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

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

Schema coverage is 100%, so the schema documents both parameters. The description adds a sentence about reassigning documents, which directly relates to the reassignTo parameter, providing behavioral context but no additional syntax or format details. It slightly enhances understanding but the schema carries the main load.

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 the action ('Delete a folder') and the resource (folder/collection), though 'folder' is imprecise given the tool name and schema use 'collection'. It distinguishes from other delete_* tools by specifying the resource type and adds a key side effect about documents retaining their workspace position. The purpose is clear enough for an agent to identify the target.

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

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

The description implies usage (when you want to delete a collection) but does not explicitly contrast with alternatives like delete_doc or update_doc_collection. It does not mention when not to use this tool, such as when documents themselves need deletion. The context is adequate but lacks explicit routing to or away from 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?

The annotation destructiveHint: true already discloses the destructive nature, and the description ('Remove') is consistent with that. However, it adds no extra behavioral context such as permanence, cascade effects, or failure conditions. With annotations present, the bar is lower, but the description contributes nothing 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?

The description is a single, concise sentence with no wasted words. It is front-loaded with the verb and clearly states the action. Ideal for quick parsing by an agent.

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 delete operation with one parameter and destructive annotation, the description covers the core requirement. It lacks minor context like whether the user needs permission or if the comment must exist, but these are not critical for a tool of this simplicity. The output schema absence is acceptable for a delete operation.

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

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

The schema provides full description of the sole parameter commentId ('The comment id.'). The description adds no additional meaning or format details. Since schema coverage is 100%, the baseline of 3 is appropriate; the description does not enhance parameter understanding.

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

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

The description clearly states the action ('Remove') and the resource ('a comment from a document'), which is distinct from the title. However, it does not differentiate from sibling tools like delete_comment, leaving the agent to infer the difference. The purpose is unambiguous but lacks 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?

There is no guidance on when to use this tool versus delete_comment or edit_doc_comment. No context is given about the intended scope (e.g., only document comments vs. issue comments) or any prerequisites. The agent must rely on the name alone to decide, which is insufficient.

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 mark the tool as destructive and non-idempotent, so the description adds meaningful context by specifying that attached content is deleted and that the action is irreversible. This goes beyond the structured annotations without contradicting them.

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 with no filler. The most important facts—permanence, scope, and the preferred alternative—are packed efficiently and front-loaded.

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

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

For a simple single-parameter destructive tool, the description is complete enough. The schema covers the parameter, annotations cover the safety profile, and the description covers what is destroyed and the alternative. No output schema is needed for this kind of 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?

There is only one parameter and the schema already describes it fully, including an example format and the fallback to an issue id. The description adds no parameter-level detail, but the schema coverage is 100%, 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?

The description clearly states a specific action (permanently delete), a resource (an issue), and the scope of destruction (everything attached to it). It distinguishes itself from archive_issue, its closest sibling, by highlighting irreversibility.

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 explicitly names archive_issue as the preferred alternative and warns that this operation cannot be undone. It does not spell out the exact condition for choosing delete over archive, but the permanence warning makes the tradeoff clear.

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

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

Annotations already mark the operation destructive and non-idempotent. The description adds important behavioral context by disclosing the cascade effect: removing the label from every issue that carries it. This goes beyond the annotation hints and clarifies the real scope of the destructive action.

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

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

A single, direct sentence that front-loads the action and scope. Every word earns its place; there is no filler or repetition of the title.

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

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

For a simple one-parameter destructive tool, the description covers what is removed, the cascade effect, and the parameter is fully documented in the schema. Annotations cover safety, and no output schema is present, so 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?

The schema documents the single parameter 'label' with the description 'Label name or id', achieving 100% coverage. The description does not add additional parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Remove' with a clear resource 'label' and states the full scope: the workspace and every issue carrying it. This clearly distinguishes it from sibling tools like create_label, update_label, and list_labels.

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

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

The description implies when the tool should be used (when a label needs to be permanently removed), but it does not explicitly mention alternatives or exclusions. The sibling list provides context, but the description itself offers no guidance on choosing this tool over others.

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

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

Annotations already declare destructiveHint=true, so the description correctly adds more value by explaining the precise consequence: issues survive but lose the milestone link. This is critical non-obvious behavior that the annotations alone do not 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?

Two short sentences with no fluff. The primary action is front-loaded, and the side effect is stated concisely right after.

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

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

For a one-parameter destructive operation, the description fully covers what the tool does, what happens to related issues, and what input is needed. The annotations fill in the remaining safety profile, so nothing necessary for correct invocation is missing.

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

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

Schema coverage is 100% and the param description 'The milestone id.' is sufficient. The tool description does not add new semantics for the parameter, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb 'Remove' with a concrete resource 'a milestone', making the purpose immediately obvious. It also distinguishes itself from sibling delete tools (e.g., delete_sprint, delete_issue) by naming its unique effect on issues, so an agent can tell it apart without opening other definitions.

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

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

The description gives clear context: use this to remove a milestone while keeping its issues intact. It does not explicitly name alternatives or exclusions, but the side-effect statement implies the appropriate scenario where this tool is the right choice.

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

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

Annotations already declare destructiveHint=true, so the description's 'Permanently delete' aligns with that. The description adds valuable context beyond annotations: issues survive but lose their project link. This is a meaningful behavioral disclosure. It doesn't mention irreversibility explicitly, but 'permanently' covers that.

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 with no waste. The key behavioral fact ('permanently delete') is front-loaded, and the alternative is stated concisely.

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 the destructive nature, the description is nearly complete. It explains the consequence for issues and routes to the preferred alternative. It could mention that deletion is irreversible, but 'permanently' implies that.

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

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

Schema coverage is 100%, so the schema already documents the 'project' parameter. The description doesn't add parameter-specific details beyond what the schema provides, but the baseline of 3 is appropriate since the schema fully covers 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?

The description states a specific verb ('Permanently delete') and resource ('a project'), and explicitly distinguishes it from the sibling archive_project. It also clarifies the consequence for issues, which is a key differentiator.

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 explicitly says 'Prefer archive_project', which tells the agent when not to use this tool and points to the alternative. This is clear usage 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 mark destructiveHint=true, so the description adds valuable context beyond that by specifying the non-destructive effect on issues: they survive and fall back to no sprint. This explains the precise outcome, which is crucial for an agent.

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 that front-load the primary action and then provide essential consequence and rationale. No redundant phrases or filler.

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

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

For a single-parameter delete with no output schema, the description covers the primary behavior and the critical consequence (issues surviving). It could mention error cases or idempotency, but these are less critical given the destructive annotation.

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

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

Schema coverage is 100% with the sprint parameter described as 'Sprint name, number or id.' The description adds no extra parameter nuances, so it meets the baseline expected when the schema carries the full documentation.

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

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

The description states a specific action 'Remove' and resource 'sprint', and the added clause about issues surviving clarifies the exact effect, distinguishing it from other delete_* tools that might cascade or destroy related data.

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

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

Provides a clear use case: 'which is what descoping a cancelled sprint needs' – indicating when this tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full 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 destructiveHint=true and readOnlyHint=false, so the agent knows the operation is destructive. The description adds valuable behavioral context: that a state holding issues is refused unless moveTo names another status on the same team. This goes beyond the annotations and helps the agent anticipate failure conditions and requirements.

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, both directly informative. The first sentence states the core purpose, the second adds a critical constraint. No filler, no repetition of schema information, and the key behavior is front-loaded.

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

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

For a destructive operation with three parameters (one optional) and no output schema, the description covers the essential behavior and the key exception. It does not mention permissions or side effects beyond the refusal condition, but given the annotations already convey destructiveness, this is adequate. The description is complete enough for an agent to understand the tool's contract without opening 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?

The schema provides 100% coverage for all three parameters with basic descriptions, but the description adds meaning by clarifying the conditional requirement for moveTo (required when the state holds issues) and the constraint that it must be on the same team. This contextual information is not present in the schema and helps the agent construct valid calls.

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 pair, 'Remove a status from a team board', which precisely identifies the tool's action and target. It also distinguishes it from sibling delete tools (delete_issue, delete_project, etc.) by explicitly scoping it to workflow states on a team board. The sentence about refusal conditions adds further specificity.

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

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

The description does not explicitly mention when to prefer this tool over alternatives like update_state or reorder_states, nor does it state any exclusion criteria. The purpose is clear enough to imply usage, but there is no direct guidance on alternative selection or when not to use it. The only guidance is about the moveTo parameter, which is more behavioral than usage.

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

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

Annotations already declare destructiveHint: true, so the agent knows the operation is destructive. The description adds no additional behavioral context, such as irreversibility, side effects on dependent views, or confirmation requirements. It merely restates the action without enriching the safety profile beyond what 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?

The description is a single, concise sentence with no wasted words. It is efficiently phrased, though it borders on being a tautology. The structure is front-loaded with the action, but it lacks any elaboration that would justify a higher score.

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

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

Given that this is a destructive operation with one parameter and no output schema, the description is minimal but incomplete. It does not state whether deletion is permanent, what happens if the view does not exist, or whether it affects other objects. The annotation covers the destructive nature, but the description itself adds little beyond that, leaving gaps in behavioral understanding for an agent.

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

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

The input schema already provides a description for the 'view' parameter ('View name or id.') with 100% schema coverage. The tool description does not add any additional meaning or constraints about the parameter, such as format, uniqueness, or how to obtain valid values. Baseline of 3 is appropriate since the schema carries the semantic load.

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 'Remove a saved view' is essentially a synonym for the title 'Delete a saved view'. It clearly identifies the verb and resource but adds no specificity beyond the title, such as whether the deletion is permanent or affects associated data. It does not distinguish itself from siblings because there is no other view-deletion tool, but it also does not clarify scope.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, consequences, or when a different action (e.g., update_view or archive) would be more appropriate. No exclusions or alternative tool references are given.

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

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

Annotations already signal mutating/destructive behavior (readOnlyHint=false, destructiveHint=true), so the description does not need to restate that. It adds an ownership constraint ('this user wrote') that is not captured in the schema or annotations, adding some behavioral context. No additional side effects, rate limits, or irreversibility details are 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?

One short sentence that front-loads the action and scope with no filler. It earns its place and remains readable.

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

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

For a simple two-parameter mutation with destructive annotations, the description plus schema covers the essential calling context. It does not describe the return value or side effects beyond body replacement, but that is a minor gap for this simple operation.

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

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

Schema description coverage is 100%, with both commentId and body already described meaningfully. The description adds no parameter-level nuance beyond saying the body is rewritten, which matches the schema. Baseline 3 is appropriate.

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

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

The description names the exact action ('Rewrite'), the resource ('body of a comment'), and the scope ('this user wrote on an issue'). This distinguishes it from delete_comment and edit_doc_comment without needing schema inspection.

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

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

It clearly conveys this is for replacing the body of an existing issue comment, and the 'this user wrote' qualifier tells the agent it applies to the user's own comments. It does not explicitly name alternatives or when-not-to-use, but the issue-comment scope makes the context clear among 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 indicate destructiveHint=true and readOnlyHint=false, so the description need not restate that this is a mutation. The description adds the constraint 'this user wrote' (implying ownership), which is useful. However, it does not mention potential side effects, permissions required, or whether the comment must exist. With annotations covering the destructive nature, a 3 is appropriate.

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

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

The description is a single, concise sentence without fluff, front-loading the action. It is efficient and easy to parse, though it could be slightly more informative about alternatives.

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

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

Given the tool's low complexity (two parameters, no output schema, no nested objects), the description and annotations together are sufficient for an agent to call it correctly. It lacks explicit mention of preconditions (e.g., comment must exist, user must be author), but those are implied by 'this user wrote' and the schema's required body. The ownership scope is the main added context, and it is adequate.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('Replacement Markdown body' and 'The comment id'). The description adds no extra semantic detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Rewrite') and a clear resource ('the body of a comment this user wrote on a document'), which distinguishes it from comment creation and deletion. However, it does not explicitly differentiate from the sibling 'edit_comment', which likely performs a similar function on issues, so it is clear but not fully distinguishing.

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

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

The description implies usage for editing a comment's body, but it does not explicitly state when to use this tool versus alternatives like 'edit_comment' or 'delete_comment'. The restriction to 'this user wrote' provides some context but lacks explicit exclusions or alternative routing.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds analytical scope but no additional behavioral traits such as auth requirements, rate limits, or return format details. No contradiction exists.

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

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

Three sentences with no filler: purpose first, then concrete use cases, then parameter capabilities. The description is front-loaded and every sentence earns its place.

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

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

For a simple read-only analytics tool with no output schema, the description adequately conveys what data it returns and when to use it. It could be more explicit about the output shape, but the 'overview' phrasing and metric list make the tool usable without that detail.

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 have clear enums and descriptions. The description's mention of filtering time range and measuring by issues or points echoes the schema without adding meaningful new semantics 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 states a specific verb ('Retrieve'), a specific resource ('high-level analytics overview of the workspace'), and lists concrete metrics the tool covers (throughput, median cycle time, blocked work, current WIP). This clearly distinguishes it from sibling progress and list tools.

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

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

The description gives explicit usage guidance: 'Use this to answer questions about...' followed by concrete metric types. It does not name sibling alternatives or state when not to use it, so it falls just 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?

The description goes beyond the annotations by explaining that the full body is returned and that output format depends on document kind, with a kind field indicating it. The annotations already cover read-only, idempotent, non-destructive behavior, so this added return-format context earns a strong score.

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 deliver the core behavior without filler. The key idea, returning the full body, is front-loaded, and the format clarification is concise and useful.

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 single-parameter read tool, the description is complete: it explains what is returned, how format varies, and that a kind field disambiguates. The schema documents the parameter and the annotations cover the safety profile, so nothing essential is missing.

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

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

Schema description coverage is 100%, and the param schema already states that the value is a document id or exact title. The tool description adds no additional meaning about the parameter, so the baseline score 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?

The description states a clear verb and resource: return a document with its full body, and it adds format-specific details. It does not explicitly differentiate itself from sibling tools like list_docs or read_attachment, so it stops short of a 5.

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

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

The read intent is clear and implies when to use it, but there is no explicit guidance about alternatives or when not to use it. An agent is left to infer that this tool is for fetching a single document body rather than listing or searching documents.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the response includes description, labels, and relations, which is useful but not essential. It does not mention auth, rate limits, or other behaviors, but given the annotations, the bar is met. 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?

The description is a single sentence with no wasted words. It front-loads the action and resource, then lists the returned fields. Efficient and to the point.

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

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

For a simple, single-parameter, read-only tool with no output schema, the description is sufficiently complete. It specifies the purpose, the identifier, and the included fields. It could mention that it returns a single object, but that is implied by 'one issue'. The annotations cover safety, so 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% with a clear description for the 'issue' parameter. The tool description restates the identifier formats but adds no new semantics beyond what the schema provides. Baseline of 3 is appropriate when the schema fully documents the parameter.

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

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

The description clearly states the action ('Fetch') and the resource ('one issue'), and specifies the identifier formats ('ENG-42' or by id). It also mentions the included fields (description, labels, relations), distinguishing it from sibling tools like list_issues or search_issues that operate on collections.

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

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

The description clearly indicates when to use this tool: when you need a single issue by identifier. It does not explicitly mention alternatives or exclusions, but the specificity of 'one issue' implies it is for individual retrieval rather than listing or searching. Given the large sibling list, a note about using list_issues for multiple issues would strengthen it, but the current wording is unambiguous enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds context beyond that: it specifies the exact data returned (user, workspace, role, teams) and the authorization basis (OAuth grant). This enriches the agent's understanding of what to expect without contradicting the annotations.

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

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

The description is exactly two sentences: the first states the core functionality, the second provides a pragmatic usage instruction. No filler words, no redundancy, and the most critical information (what it returns) is front-loaded.

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

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

For a zero-parameter, read-only introspection tool with rich safe-operation annotations, the description fully covers what an agent needs: what data is returned and when to call it first. There is no missing information that would prevent correct invocation.

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

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

The tool has zero parameters, so the baseline per rubric is 4. The description adds no parameter-specific details, which is fine because there are none to document. The schema fully covers the empty parameter set.

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

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

The description clearly states the verb 'Return' and the specific resource: 'Orbit user, workspace, role and teams authorized by the OAuth grant.' It also indicates the primary purpose ('Call this first to learn which teams you may write to'), which distinguishes it from all sibling tools that operate on other resources.

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 explicitly instructs 'Call this first to learn which teams you may write to,' which is a clear when-to-use guidance. It does not mention alternatives, but given the tool is uniquely for identity retrieval, alternatives are not applicable. The guidance is explicit enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds value beyond annotations by clarifying the advisory nature of the content and explicitly stating it is not a permission boundary—critical context for an agent deciding how to act on the returned instructions. This is a meaningful addition that prevents misinterpretation.

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 with no filler. The action and resource are front-loaded in the first sentence, and the second adds a crucial qualifier. Every word earns its place, making this an exemplary concise definition.

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

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

Given the tool's simplicity (no parameters, no output schema) and the strong annotation coverage, the description is nearly complete. It covers what the tool does and the interpretive caveat. A slight gap is the lack of detail on what the 'workspace guidance' actually contains or its format, but for a read-only getter this is minor and unlikely to hinder 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?

There are zero parameters, so schema coverage is trivially 100%. Per the rubric, a baseline of 4 applies when no parameters exist, and the description correctly avoids inventing parameter details. Nothing further is needed.

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

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

The description states a specific verb ('Return') and resource ('current workspace guidance for connected agents'), making the tool's purpose unambiguous. It is clearly distinct from the many list/get siblings because it addresses workspace instructions rather than project data. The phrasing 'workspace guidance' is specific enough to convey intent.

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

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

The description gives clear context by clarifying that the returned guidance is advisory and not a permission boundary, which helps the agent interpret the output correctly. While it does not explicitly state when to use this tool versus alternatives, there are no obvious sibling tools with overlapping function, so the need is implied. The absence of exclusions or alternative references is acceptable given the uniqueness.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses important behavioral details: the invitation remains pending, no email is sent, and admin invites are restricted to admins. These traits materially affect expectations and are not inferable from the schema or annotations alone.

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

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

Three short sentences with no wasted words. The core action, a key non-behavior (no email), and permission constraints are all front-loaded and each sentence earns its place.

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

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

For a three-parameter tool with no output schema, the description covers the essential purpose, side-effect profile, and authorization requirements. It leaves minor edge cases unspecified, such as duplicate invites or the acceptance flow, but those are not necessary for correctly invoking the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying role-based permission semantics that the schema does not encode, specifically that only admins can invite admins. It does not need to repeat the schema's documentation of email, role, or teams.

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

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

The description uses a specific verb and resource: 'Create a pending workspace invitation for an email address.' It is clearly distinct from sibling tools like add_team_member because it focuses on a pending workspace-level invitation rather than adding an existing member to a team. The additional clarification that no invitation email is sent further sharpens the purpose.

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

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

The description provides clear context for when to use this tool: when creating a pending invitation by email. It also states authorization requirements, including 'Requires a role that can invite members' and 'Only admins can invite admins.' It does not explicitly name alternative tools or exclusion conditions, but the context is strong enough for an agent to make a correct selection.

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 indicate this is a mutation (readOnlyHint=false) and not destructive. The description adds a valuable side effect: 'Associating also starts watching the repository, which is what lets its pull request and check events reach Orbit.' This goes beyond annotations and helps the agent understand the non-obvious consequence.

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 sentences with no redundant words. The main purpose is front-loaded, and the side effect is mentioned succinctly. It 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?

The description covers the core action, the workspace vs. project distinction, and the watching side effect. It doesn't mention error conditions or return values, but given the lack of output schema and the simple nature of the operation, it is adequately complete for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with both parameters having detailed descriptions. The tool description does not add new parameter semantics beyond what the schema already provides; it only reiterates the workspace vs. project distinction, which is already in the project parameter description. Baseline 3 is appropriate.

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

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

The description clearly states the action: 'Associate a connected repository with a project, or with the whole workspace when no project is given.' It uses a specific verb and resource, and distinguishes from siblings like unlink_github_repository and list_github_repositories by focusing on the association 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?

The description provides clear usage context: it explains the two modes (with project vs. whole workspace) and the many-to-many relationship. It doesn't explicitly contrast with alternatives, but the conditions for use are clear from the description.

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

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

Annotations already carry readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add behavioral nuance. It adds the comment-coverage distinction versus list_issue_attachments, but it does not describe return format or whether results are limited to direct attachments, so the added transparency is moderate.

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

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

Three sentences carry the purpose, the routing alternative, and the intended scope with virtually no filler. It is slightly less crisp than ideal because the first and third sentences overlap in scope, but each sentence contributes information.

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

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

For a simple read-only list with two fully documented parameters and strong annotations, the description covers the main selection decision. It does not specify return shape, but with no output schema and a straightforward list resource this is an acceptable gap rather than a blocking omission.

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

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

Input schema fully documents both parameters (100% coverage), so the baseline is 3 and the description does not need to restate them. The description does not add parameter-level details, and the schema's parentId note ('Issue identifiers are not accepted') is left unresolved by the description.

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

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

Description states a clear action and resource: it lists files attached to an issue, comment, doc, or project, and names the sibling tool that should be used for issues. It stops short of 5 because the final sentence, 'This is for docs and projects,' slightly muddles the scope after the first sentence explicitly included comments and issues.

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

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

It explicitly tells the agent to use list_issue_attachments for an issue because that tool also covers issue comments. This is strong routing guidance, but it does not fully explain when to choose this tool for comments, and the final sentence only loosely states the intended use case.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds scope ('of this workspace') and ordering ('number order'), which are useful behavioral details. However, it does not disclose return format, pagination, or whether archived sprints are included, which would be helpful for a list operation 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?

The description is a single, focused sentence that directly states the operation, scope, and ordering. Every word contributes value with no filler or repetition of the title.

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

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

For a simple list operation, the description is adequate but leaves gaps: it does not specify what fields each sprint object contains, whether the list is paginated, or if any filtering options exist. Given the absence of an output schema, these details would help an agent fully anticipate the response, but the core functionality is clear.

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

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

The tool has zero parameters, so the schema carries no semantic burden. The description correctly avoids inventing parameters. Per calibration, a zero-parameter tool gets a baseline of 4, and the description adds no conflicting or redundant parameter information.

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

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

The description clearly states the action (List) and the resource (sprints of this workspace), and adds ordering (number order). It is unambiguous and distinct from sibling tools like create_cycle or update_cycle, which are mutations.

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

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

The tool's purpose is self-evident as a read-only list operation. While it does not explicitly mention alternatives or exclusions, the context of sibling tools makes it clear that this is the canonical way to retrieve all sprints. There are no other list_* tools for cycles, so no ambiguity.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the behavior that it returns folders with counts, but does not disclose other behavioral traits such as sorting, pagination, or whether empty collections are included.

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

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

A single, front-loaded sentence with no filler. It states the core purpose first and the count detail second, making it optimally concise for the tool's simplicity.

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-parameter, read-only list tool with no output schema, the description adequately conveys the return value (folders and their counts). Minor ambiguity remains about whether archived/empty collections are included and the exact result structure, but these are not critical for a correct invocation.

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

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

The tool has zero parameters, and the schema confirms this with no properties. With no parameters to explain, the description carries no parameter burden, and the baseline for 0 params is 4.

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

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

The description uses a specific verb ('Return') and resource ('folders documents can be filed under') plus the count detail, making its purpose unambiguous. It is clearly distinct from sibling list_docs (which lists documents) and the doc_collection mutation 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?

Usage is implied: an agent would call this when needing the list of document collections and their document counts. However, the description provides no explicit when-to-use/when-not-to-use guidance or alternatives, though the zero-parameter design makes selection straightforward.

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, idempotentHint, and non-destructive behavior, so the description's burden is lower. It adds the meaningful behavior that results are ordered oldest first and presented as a thread, but it does not disclose pagination, return shape, or error behavior.

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

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

One short, front-loaded sentence states the resource and ordering without filler. Every word contributes, and there is no redundant restatement of the title.

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

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

For a single-parameter, read-only list operation with full schema coverage and safety annotations, the description is nearly sufficient: it names the resource, ordering, and the fact that a thread is returned. It would be complete with a bit more detail on the response shape or pagination, but given the low complexity this is a minor gap.

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

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

Schema description coverage is 100%, with the sole parameter `doc` fully described as either an id or exact title. The description adds no parameter-specific detail beyond the schema, so it meets baseline but does not elevate 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?

The description uses a specific verb ('Return') and resource ('comment thread on a document'), and adds an ordering constraint ('oldest first'). It clearly points at document comments rather than issue comments, though it does not explicitly differentiate itself from siblings like list_issue_comments.

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

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

No guidance is given for when to use this tool vs alternatives such as list_issue_comments, get_doc, or comment_on_doc. An agent must infer from the name/resource semantics; there are no explicit exclusions or conditions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral details: the ordering behavior (sidebar vs relevance) and the 'user can read' permission scope, which are useful beyond the schema. It doesn't contradict annotations and adds context about the tool's behavior.

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

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

Two sentences with no fluff. The primary purpose and ordering behavior are front-loaded, followed by a compact list of filter options. Every word 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 list tool with 5 optional parameters and no output schema, the description covers the main usage scenarios: listing all readable docs, ordering, and filtering. It doesn't mention pagination, default exclusion of archived docs (though there's an includeArchived param), or return format, but these are not critical given the annotations cover safety and the schema documents parameters. It's reasonably 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 all parameters are documented in the schema. The description adds the relevance-ordering effect of the query parameter and mentions the filter dimensions (project, collection, unfiled) which align with the params, but it doesn't go into syntax or format details. This is a slight addition over the schema, but not substantial.

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

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

The description states a specific action (list documents) and the resource (documents this user can read), plus ordering criteria (sidebar or relevance) and filters. It clearly distinguishes from siblings like list_doc_collections and list_doc_comments by focusing on the document list 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 context on ordering and filter options, and implies it's the right tool for retrieving readable documents. However, it doesn't explicitly mention alternatives or when not to use it, such as 'use search_issues for issues' or 'use get_doc for a single document.' It provides clear usage context but lacks explicit 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it explains that associations are for organization, not routing, and details how PRs are matched to issues. This clarifies the semantic meaning of the output and a key execution nuance, exceeding what 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?

The description is three sentences, front-loaded with the core purpose in the first sentence. The second and third sentences add meaningful context about associations and PR matching without redundancy. Every sentence earns its place, making it concise and well-structured.

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

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

Given zero parameters, no output schema, and annotations covering safety, the description adequately explains what the tool returns (repositories and their projects) and the semantic meaning of associations. It also explains PR matching behavior. It is complete for a simple list tool, though it omits pagination or limits, which are minor and not always specified.

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

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

The tool has zero parameters, so schema description coverage is trivially 100%. The description does not need to explain any parameters, and the baseline for 0 params is 4. It adds no parameter-specific info, but since there are none, it appropriately focuses on output semantics, which is acceptable.

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

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

The description clearly states the tool lists every GitHub repository the app is installed on for the workspace, along with associated projects. It distinguishes itself from siblings like link_github_repository and unlink_github_repository by focusing on listing rather than modification, and from list_issue_pull_requests by targeting repositories. The verb 'list' and specific resource make the purpose 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 description gives clear context on when to use it (when needing repository info) and clarifies the meaning of associations, which helps interpret results. It does not explicitly mention alternatives or exclusions, but given the niche nature of this tool, the context is sufficient. There is no direct competing listing tool, so the lack of explicit 'instead of' is acceptable.

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

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

Annotations already cover readOnly, idempotent, and destructive hints. The description adds 'immutable' and 'newest first' ordering, and 'currently accessible' implies permission constraints. 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?

Two concise sentences, front-loaded with the core purpose and then a pagination hint. No wasted words.

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

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

For a paginated read tool with no output schema, it explains the resource and cursor but does not describe the response structure or the limit parameter. Acceptable but with notable gaps.

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

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

Schema coverage is 0%, so the description must explain parameters. It only hints at cursor via 'Use the returned cursor for older updates' but does not explain the required conversationId or the limit parameter. This is a significant gap.

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

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

The description states a specific verb (read), resource (notification events for a conversation), ordering (newest first), and scope (currently accessible conversations). It clearly differentiates from sibling tools like list_inbox_conversations (listing conversations) and list_notifications (general notifications).

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: it's for a specific conversation and includes pagination guidance via the cursor. However, it does not explicitly name alternatives or state when not to use this tool, so it's not fully 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?

Beyond the readOnly/idempotent annotations, the description reveals non-obvious behavior: filters run before pagination, cursors belong to a live feed so a fresh first page is needed, and count values are conversation counts rather than event counts. This is high-value behavioral 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?

Four dense sentences, each carrying a distinct fact: grouping model, ordering, cursor semantics, and count semantics. No filler and the most important definition is front-loaded.

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

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

The description covers the main invocation pitfalls for a read-only list tool: grouping, filter-before-pagination, live cursors, and count meaning. Given the absence of an output schema, it could still say more about what fields each conversation contains and how each tab behaves.

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

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

With 0% schema coverage, the description must add parameter meaning; it explains cursor freshness and pagination ordering. However, it never details the tab enum values or how limit/pagination results are shaped, leaving part of the parameter surface to inference.

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 defines the resource as 'inbox grouped into one conversation per pull request, document, or issue activity family,' making the listing scope clear even though it lacks an explicit verb. It does not name or contrast sibling tools, so it misses the top level of 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?

'Counts are unread conversations, not events' and 'one conversation per ... activity family' imply this is the aggregated view versus event-level tools, but the description never tells the agent when to use this instead of list_inbox_conversation_events or list_notifications. Cursor and pagination guidance is operational rather than alternative-selection guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds meaningful behavior beyond annotations: it includes files attached to comments and guarantees oldest-first ordering.

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 with no wasted words. The scope and ordering are front-loaded, and the usage guidance is concise and actionable.

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 single-parameter, read-only listing tool, the description provides complete selection guidance, invocation context, and behavioral details. No output schema exists, but the tool's purpose and return scope are sufficiently clear.

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

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

Schema description coverage is 100%, so the single required 'issue' parameter is already fully documented in the schema. The description does not add additional parameter semantics, which is acceptable at the baseline.

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

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

The description states a specific verb and resource: 'Every file attached to an issue or to a comment on it, oldest first.' This clearly differentiates from siblings like read_attachment and list_attachments by scoping to issue attachments and defining ordering.

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

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

The description gives explicit usage context: 'Call this before you answer a thread that refers to a document, a screenshot or an export, so you work from what was actually attached rather than guessing from the filename.' It does not explicitly name alternatives or exclusions, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: the ordering guarantee ('oldest first') and the practical purpose (avoid repeating replies). It doesn't mention pagination behavior, but the schema's cursor/limit parameters already imply that.

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

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

Two sentences, zero filler. The core behavior is front-loaded, and the usage guidance is a single actionable sentence. Every word 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 list tool with full schema coverage and safety annotations, the description is nearly complete. It could add pagination details, but the cursor/limit parameters in the schema already signal that. The 'oldest first' ordering is a nice completeness touch.

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 description adds no parameter-specific detail beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Return') and resource ('comment thread on an issue'), and adds ordering detail ('oldest first'). It clearly distinguishes from siblings like list_doc_comments and add_comment by focusing on reading the existing thread.

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 explicitly tells the agent when to use this tool: 'Read this before replying, so you answer what was actually asked and do not repeat a reply you already posted.' This is strong usage guidance that also implies when not to use it (when you need to post, use add_comment/edit_comment).

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false, openWorldHint false), and the description adds substantial behavior beyond that: the non-obvious linking rule, the self-linking consequence of copy_branch_name, the branch field in results, and the read-permission requirement. 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?

Three front-loaded sentences with the core purpose in the first. The linking-mechanism and permission sentences each earn their place, though the copy_branch_name aside could arguably be tightened. Slightly dense, but no wasted words.

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

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

For a one-parameter, read-only, non-destructive list tool, this is complete: the parameter is fully documented in the schema, the linking semantics and permission level are disclosed, and the return content (PRs with branches) is stated. No output schema exists, so the description adequately covers the 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% — the 'issue' parameter is already documented with format examples ('ENG-42, or an issue id'). The description's linking explanation implicitly reinforces that the parameter is an issue identifier, but it adds no new syntax or format detail, so the baseline of 3 applies.

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

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

The title states a specific verb+resource ('List the pull requests linked to an issue') and the description sharpens it further: 'The pull requests Orbit has linked to an issue, with the branch each one is on.' This names the exact scope and the returned content, making it easy to distinguish from siblings like list_issue_comments or list_issue_attachments.

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

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

The description provides useful context — the linking mechanism (a PR names the issue identifier in branch/title/description) and the permission prerequisite ('Requires only the permission to read the issue'). However, it never explicitly addresses when to choose this tool over alternatives or when not to use it; the cross-reference to copy_branch_name is behavior explanation rather than selection 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the workspace scope and the team-based narrowing behavior, which is useful context beyond the annotations, but it doesn't describe return format, pagination, or other runtime details. That is acceptable for a simple read-only list 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, well-structured sentence that front-loads the main purpose and appends the optional narrowing condition. There is no filler or redundant detail.

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

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

For a simple read-only list operation with one optional parameter, the description plus annotations and schema cover what an agent needs to select and call the tool. There is no output schema, but the return value is clearly implied by 'list labels'. It doesn't mention pagination or ordering, but these are minor for this tool's 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?

The schema already documents the single optional 'team' parameter with 100% coverage, so the baseline is 3. The description reiterates the narrowing behavior ('narrowed to the ones a team can use') but doesn't add significant new semantics beyond what the schema provides.

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

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

The description names a specific verb ('List'), a clear resource ('labels'), and a scope ('available in the workspace'), with an optional team narrowing. This distinguishes it from label mutation tools like create_label, update_label, and delete_label without needing to open 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?

The description clearly states the tool's context: listing workspace labels, optionally filtered by team. It doesn't explicitly enumerate when not to use it or name alternatives, but the read-only intent and optional team parameter make the usage context clear enough for a tool with no competing label-listing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context by explaining that roles determine permissions ('which is what decides what they may do'), which goes beyond the structured metadata. It does not contradict any 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 a single, well-structured sentence that front-loads the verb and resource, then adds the key differentiator (role) and its significance. Every word contributes to understanding, with no unnecessary filler.

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

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

For a simple list tool with no parameters and no output schema, the description fully explains what the tool does and what it returns (membership with roles). It covers the essential information an agent needs to decide whether to call it and what to expect.

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

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

The tool has no parameters, so schema coverage is trivially 100%. The description adds meaning about the return content (roles and their implications), which is valuable given there is no output schema. With zero parameters, this is a strong baseline, and the description enhances 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?

The description clearly states the verb 'List' and the resource 'workspace membership', and further specifies that it includes each person's role. This distinguishes it from sibling tools like list_users and list_teams, which likely don't include role information. It is specific and 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 description does not provide any guidance on when to use this tool versus alternatives like list_users or list_teams. It implies a purpose but does not explicitly state the conditions or exclusions. For a tool with no parameters, this is a notable gap because an agent might confuse it with other listing tools.

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

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

Annotations already establish that this is a safe, read-only, idempotent call, so the description does not need to repeat safety behavior. It adds the 'in order' behavior, but does not specify the ordering key or any pagination/result-shape details, so the extra behavioral context is minimal.

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

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

The description is a single focused sentence with no filler. The key information (list, project scope, ordering) is front-loaded and every word 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 simple read-only listing with one required parameter, the description is largely complete: the action, resource, scope, and ordering are stated, and annotations cover safety. The main omission is the exact meaning of 'in order' and any differentiation from list_project_milestones, but these are not blocking for 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% and the single 'project' parameter is already documented as accepting name, slug, or id. The description adds no new meaning for the parameter, 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?

The description clearly states the action ('List') and the resource ('milestones on a project'), and adds that results are ordered. It does not explicitly distinguish itself from the sibling list_project_milestones, which appears to target the same resource, so it stops short of full differentiation.

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

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

There is no guidance about when to choose this tool over alternatives; in particular, the existence of list_project_milestones makes the absence of an exclusion or distinguishing condition notable. The description only states what it does, not when it is the right choice.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context — result ordering and the awaiting-review scope — but does not disclose pagination or return-format behavior, so it lands at 'some value but not rich behavioral 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 sentences with zero filler; the core behavior and ordering are front-loaded in the first sentence, and the filtering guidance in the second earns its place. Every clause carries information.

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

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

For a simple read-only list tool whose annotations carry the safety profile and whose schema documents both optional parameters, this is nearly complete: scope, ordering, and filter usage are all present. The only gaps are that limit's behavior is left entirely to the schema and there is no output schema describing return values.

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 50%: stateCategory is documented in the schema, and the description reinforces it with the 'started' example. The limit parameter has no prose description in either the schema or the tool description, so the agent must infer its meaning from type/default/min/max alone.

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

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

States a specific verb ('List') and a clearly scoped resource ('issues assigned to the caller or awaiting their review'), plus result ordering ('most recently updated first'). The personal scope distinguishes it from siblings like search_issues, get_issue, and list_issue_comments without needing to open their 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?

The intended use case is clear from the scope ('assigned to the caller or awaiting their review'), and the second sentence gives a concrete narrowing example ('state category such as "started"'). However, it doesn't name an alternative tool (e.g., search_issues for broader queries) or state explicit when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to repeat that. The description adds context that Orbit never notifies about the user's own actions, which is useful behavioral information. However, it doesn't mention pagination (cursor) or filtering behavior beyond what the schema suggests, which is a minor 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?

The description is concise, at two sentences, and front-loads the core purpose ('inbox' and 'find work handed to you by name'). Every sentence adds value, with no fluff or repetition.

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

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

The description is complete enough for a read-only list tool with a well-documented schema and annotations. It explains the scope (personal notifications) and addresses the self-action exclusion. Pagination details are not described, but the schema covers them, so this is a minor omission. With no output schema, return values are not specified, but that's acceptable for a list tool.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The description doesn't add extra meaning beyond the schema; it only gives a high-level summary of the resource. The baseline of 3 is appropriate as 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?

The description clearly states the tool lists notifications addressed to the user, with a specific verb ('list') and resource ('notifications'). It also distinguishes it from other list tools by emphasizing personal inbox content (mentions, assignments, etc.) and notes that it excludes self-generated actions, which differentiates it from generic list tools.

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

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

The description implicitly tells when to use it: when you want to find work handed to you by name. It does not explicitly list alternatives like list_my_issues or mark_notification_read, but the context is clear enough for an agent to infer usage. No explicit exclusions are provided, but the 'by name' phrasing gives 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 the tool safe (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the description's burden is lighter. The description adds one behavioral detail—output includes target dates—but does not describe ordering, pagination, or error behavior.

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

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

The description is one short, direct sentence with no filler. The key action and target resource are front-loaded, and every word contributes meaning.

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

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

For a simple, read-only, single-parameter tool with strong annotations, the description is nearly complete: it names the resource and the return content. It does not describe the output structure in detail, but no output schema exists and the simple nature of the tool reduces the need for more.

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

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

Schema description coverage is 100%, and the single parameter is already described as 'Project name, slug or id.' The description adds no additional meaning beyond what the schema provides, so the baseline score 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?

The description clearly identifies a verb ('Return') and resource ('milestones on a project') and adds the relevant detail that target dates are included. However, it does not explicitly distinguish this tool from the sibling 'list_milestones', which could be a broader or differently-scoped variant.

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

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

No guidance is provided about when to use this tool versus the sibling 'list_milestones'. There are no exclusions, preconditions, or hints about which tool is appropriate for different scopes of milestone listing.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description adds behavioral context by indicating the returned information includes status and health, and implies project scoping to the workspace.

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

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

A single, front-loaded sentence communicates the action, scope, and returned information with no redundant words. 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 a simple, read-only, single-parameter list operation, the description is fully sufficient. Annotations cover the safety characteristics, the schema covers the parameter, and the description states the scope and the key output fields.

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 the single includeArchived parameter fully documented in the schema. The tool description does not add parameter-specific meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description uses a specific verb ('List') with a clear resource ('projects') and scope ('in the workspace'), and adds the useful return dimension ('with their status and health'). It is clearly distinguishable from sibling tools like archive_project, update_project, and list_project_milestones.

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

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

The description clearly states the context: listing projects within the workspace informs the agent when to use this tool. It does not explicitly name alternatives or exclusions, but the need is straightforward and no sibling does the same job.

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

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

Annotations already cover read-only (readOnlyHint=true) and non-destructive (destructiveHint=false), so the description does not need to restate those. It adds value by mentioning 'board order' (a specific ordering behavior) and by tying the result to issue creation/movement. This is useful behavioral context beyond the annotations.

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

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

Two concise sentences with no filler. The core action is front-loaded, and the usage hint is placed as a second sentence. Every word serves a purpose.

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 list tool with one parameter and no output schema, the description is complete. It explains what it returns (states in board order) and how to use the result. Nothing an agent needs to call it correctly is missing.

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

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

The input schema fully describes the only parameter (team) with a clear description, so schema coverage is 100%. The description adds no additional detail about the team parameter beyond what the schema provides. Baseline of 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the verb 'List', the resource 'workflow states', and the scope 'of one team', with the added detail of 'in board order'. It also connects to downstream usage ('when creating or moving an issue'), making it unmistakable among sibling list tools like list_teams or list_projects.

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 explicitly states a use case: 'Use a state name from this list when creating or moving an issue.' This implies when to use it, though it does not contrast it with alternatives. Since the sibling set is dominated by other resource-specific list tools, the context is clear enough; a slightly more explicit 'when you need state names' would push it to 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context by noting the caller-visibility scope and the team key semantics, which are not available from annotations alone.

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

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

Two concise sentences with no filler. The core behavior is front-loaded, and the extra detail about team keys is directly useful for understanding how teams are represented.

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 list tool with one optional parameter and no output schema, the description is sufficient: it states the scope, the visibility rule, and a key property of the returned teams. Nothing essential is missing for an agent to select and 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?

The only parameter, includeArchived, is fully documented in the schema with its default value (false). The description adds no parameter-specific information, so the baseline of 3 applies because 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: lists the teams in the workspace, with an additional scope qualifier ('that the caller can see') and a useful distinguishing detail about team keys prefixing issue identifiers. This clearly separates it from sibling list tools such as list_members or list_users.

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

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

The description provides clear context for when to call it: to see visible teams in the workspace. It does not explicitly name alternatives or exclusions, but for a simple list operation the use case is readily inferable from the description and title.

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