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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: initialization steps, mode-specific requirements, error conditions, and the consequence that re-activation 'switches modes and resets system state.' It covers authentication needs, network dependencies, and file system permissions, though it lacks details on rate limits or exact error handling.

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 well-structured with clear sections (activation modes, requirements, process, error conditions), but it is verbose with 18 sentences. Some details, like the step-by-step activation process, could be condensed without losing clarity, as the schema already covers parameter validation and requirements.

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

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

Given the complexity (5 parameters, no annotations, no output schema), the description is mostly complete. It covers purpose, usage, parameters, behaviors, and errors. However, it lacks information on return values or output format, which is a gap since there's no output schema, leaving the agent uncertain about what to expect after activation.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds significant value by explaining the semantics of parameters: it clarifies that 'projectRoot' is an 'absolute path' and creates a local directory, 'apiToken' is for 'authentication,' 'remoteProjectId' is a 'unique identifier,' and 'url' is optional with a default. This enhances understanding beyond the schema's basic 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 clearly states the tool's purpose: 'Activates the task trellis system in local or remote mode' and 'initialize and configure the task trellis system for operation.' It specifies the verb ('activate') and resource ('task trellis system'), and distinguishes it from sibling tools by emphasizing it must be called before any other task management operations.

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 usage guidance: 'Must be called before any other task management operations can be performed,' 'Must be successfully completed before using any other task trellis tools,' and explains when to use local vs. remote modes based on workflows (single-user vs. collaborative). It also mentions re-activation behavior for switching modes.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining that log entries create 'a permanent audit trail' (implying immutability) and that timestamps are 'automatically added by system.' However, it doesn't address important behavioral aspects like whether this operation requires specific permissions, what happens if the issue doesn't exist, whether there are rate limits, or what the response format looks like. The description adds some context but leaves significant gaps 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?

While the description is well-structured with clear sections, it's excessively verbose for a tool with only 2 parameters. The detailed lists of 'Log entry purposes,' 'Log content guidelines,' and 'Activity tracking patterns' could be condensed or moved to external documentation. The core functionality could be explained in 2-3 sentences rather than multiple paragraphs, making it less front-loaded than ideal.

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

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

For a mutation tool with no annotations and no output schema, the description provides good context about the tool's purpose and usage patterns. However, it lacks critical information about error conditions, authentication requirements, response format, and system constraints. The detailed usage examples partially compensate but don't fully address the gaps in behavioral transparency needed for a write 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 has 100% description coverage, providing clear documentation for both parameters ('ID of the issue to append log to' and 'Contents to append to the log'). The description doesn't add any parameter-specific information beyond what's already in the schema. According to scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in 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?

The description clearly states the tool's purpose with a specific verb ('Appends') and resource ('content to an issue's log in the task trellis system'). It distinguishes this tool from siblings like 'create_issue' (creates new issues), 'update_issue' (modifies issue properties), and 'delete_issue' (removes issues) by focusing specifically on adding to an audit trail rather than managing the issue 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?

The description provides explicit guidance on when to use this tool: 'Use this tool to add progress updates, notes, or activity records to an issue's audit trail.' It also implicitly distinguishes from alternatives by focusing on log appending rather than issue creation, modification, or deletion. The detailed examples of log entry purposes further clarify appropriate use cases.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's a write operation (appends/updates), merges descriptions for previously modified files, and serves audit/compliance purposes. However, it lacks details on error handling, permissions, or rate limits, which would be valuable 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 well-structured with clear sections (purpose, usage, guidelines) and front-loaded key information. However, the 'File modification tracking purposes' bullet list is somewhat redundant with earlier content, slightly reducing efficiency without adding critical new insights.

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

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

For a mutation tool with no annotations and no output schema, the description does a good job covering purpose, usage, and input semantics. It lacks details on return values or error cases, but given the context (2 parameters, 100% schema coverage), it provides sufficient guidance for effective use, though not fully exhaustive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value beyond the schema by explaining the semantics of 'filesChanged' (e.g., mapping file paths to modification descriptions) and providing detailed guidelines for file paths and descriptions, enhancing understanding of how to structure input data effectively.

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

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

The description clearly states the tool's purpose: 'Appends modified files information to a trellis issue in the task trellis system.' It specifies the action (append), resource (modified files information), and target (trellis issue), distinguishing it from siblings like 'append_issue_log' (general logs) or 'update_issue' (general updates).

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 when to use this tool: 'Use this tool to record files that have been modified during task execution, along with descriptions of the modifications made.' It provides clear context (task execution) and purpose (tracking changes), differentiating it from alternatives like 'append_issue_log' for general logs or 'update_issue' for broader updates.

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

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

With no annotations provided, the description carries full burden and delivers substantial behavioral context. It explains claiming behavior for different parameter combinations, details task readiness criteria (status, prerequisites, ownership, scope), outlines the claiming workflow steps, and warns about force parameter implications. The only minor gap is lack of explicit mention of error conditions or rate limits.

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

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

The description is well-structured with clear sections (Claiming behavior, Task readiness criteria, Claiming workflow, Common patterns), but could be more concise. Some sentences repeat information (e.g., 'Essential for AI agents' appears twice), and the final sentence restates earlier points. The front-loading is good, but overall length could be optimized.

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 3 parameters, no annotations, and no output schema, the description provides comprehensive context. It covers purpose, usage, parameters, behavior, workflow, and patterns. The main gap is lack of information about return values (though no output schema exists), but otherwise it gives agents sufficient information to use the tool effectively in autonomous workflows.

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?

Despite 100% schema description coverage, the description adds significant value beyond the schema. It explains the semantic meaning of each parameter in context ('Without taskId: Claims the next available task', 'scope: Limits claiming to tasks within a specific project', 'force: Overrides normal claiming restrictions'), provides usage patterns, and clarifies default behaviors. The schema only provides basic descriptions without this contextual richness.

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

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

The description clearly states the tool's purpose with specific verbs ('claims a task', 'assign yourself to available tasks') and distinguishes it from siblings by focusing on task claiming rather than creation, completion, or issue management. It explicitly identifies this as essential for AI agents to pick up work items, establishing a distinct role.

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 ('Essential for AI agents to pick up work items from the task queue'), offers clear alternatives through common patterns (claim any ready task, claim from project, claim specific task, force claim), and includes cautionary advice ('use with caution' for force parameter). It effectively distinguishes this from sibling tools like complete_task or get_next_available_issue.

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

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

With no annotations, the description carries full burden and provides rich behavioral details: it describes the multi-step completion process (validation, status updates, timestamp recording, dependency handling), file change tracking specifics, and automatic notifications/triggers. It doesn't mention rate limits or auth needs, but covers most operational behavior thoroughly.

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 well-structured with clear sections (Required completion data, Completion process, File change tracking, Best practices) and front-loaded purpose. It's appropriately detailed for a complex tool but could be slightly more concise by integrating some best practices into the main flow.

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

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

For a mutation tool with no annotations and no output schema, the description provides comprehensive context: it explains the completion process, behavioral effects, parameter usage, and best practices. The only minor gap is lack of explicit error handling or return value information, but overall it's highly complete for the 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds some context: it explains that 'filesChanged' is a 'Map of modified files with descriptions' and provides an example, but doesn't add significant meaning beyond what the schema provides. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose: 'Completes a task in the task trellis system' and 'mark a task as finished and record completion details.' It distinguishes from siblings like 'claim_task' (which likely starts a task) and 'update_issue' (which modifies but doesn't complete), providing specific verb+resource 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?

Explicit guidance is provided: 'Use this tool to mark a task as finished' and 'Critical for task lifecycle management.' It includes when-not scenarios: 'Complete tasks only when all acceptance criteria are met' and 'Verify dependent tasks can now proceed before completion.' This clearly defines usage context versus alternatives.

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

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

With no annotations provided, the description carries full burden and does well by disclosing key behaviors: system validates parent types during creation, default values for priority and status, and hierarchy constraints. It doesn't mention error conditions, rate limits, or authentication needs, but provides substantial operational context.

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

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

The description is well-structured with clear sections (Available issue types, Supported hierarchy structures, Available status values, Key aspects, Best practices) but could be more concise. Some information is slightly repetitive (e.g., 'open' status listed twice), but overall it's efficiently organized with front-loaded 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 creation tool with 7 parameters, no annotations, and no output schema, the description provides comprehensive context about hierarchy rules, valid values, defaults, and system behavior. It doesn't describe the return format or error responses, but covers most operational aspects needed for successful tool 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%, so baseline is 3. The description adds significant value by explaining the meaning and constraints of parameters: it defines all possible values for 'type', 'status', and 'priority', explains parent-child relationships and hierarchy rules, and clarifies prerequisites define execution order dependencies.

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 specific action ('creates a new issue') and resource ('in the task trellis system'), distinguishing it from siblings like 'update_issue' or 'delete_issue' by focusing on creation. It immediately establishes this is for creating tasks, projects, or work items within a hierarchical system.

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 'Use this tool to create new issues' and provides extensive context about when to use it through hierarchy rules, status values, and best practices. It distinguishes from siblings by focusing on creation rather than modification, listing, or deletion operations.

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

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

With no annotations provided, the description carries full burden and excels by detailing behavioral traits: irreversible nature, relationship validation, dependency protections, force deletion bypass, impact on metadata and relationships, and audit trail considerations. It comprehensively explains what gets destroyed and safety mechanisms.

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 well-structured with clear sections (Safety considerations, Deletion impacts, Best practices) and front-loaded key information. While comprehensive, some sentences could be more concise (e.g., the final warning reiterates earlier points), but overall it earns its length with valuable content.

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

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

For a destructive tool with no annotations and no output schema, the description provides complete context: purpose, usage guidelines, behavioral transparency, parameter semantics, and sibling differentiation. It addresses complexity through detailed safety considerations, impacts, and best practices, leaving no significant gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the semantic meaning of 'force=true' ('bypass safety checks for administrative cleanup') and contextualizing the 'id' parameter ('ensure you have the correct issue ID'), elevating it above baseline.

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

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

The description clearly states the specific action ('Deletes an issue') and resource ('from the task trellis system'), distinguishing it from sibling tools like 'update_issue' or 'create_issue'. It goes beyond the tool name by specifying the permanent removal from a task hierarchy context.

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

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

The description provides explicit guidance on when to use this tool ('permanently remove issues') versus alternatives ('Consider updating status to 'cancelled' instead of deletion'), including when-not scenarios ('Exercise caution as deletion... cannot be easily undone') and best practices for specific contexts like administrative cleanup.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool as a read-only retrieval operation ('Gets,' 'retrieve'), specifies it returns 'complete issue data' with six detailed categories of information, and emphasizes it's 'essential for understanding the full context... before making modifications.' However, it doesn't mention potential limitations like rate limits, authentication needs, or error conditions.

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

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

The description is appropriately front-loaded with the core purpose in the first sentence, but it includes extensive bulleted lists and usage scenarios that, while informative, could be more concise. Some redundancy exists (e.g., repeating retrieval concepts), and not every sentence earns its place efficiently for a single-parameter tool.

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

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

Given the tool's low complexity (1 parameter, no nested objects, no output schema), the description is largely complete. It covers purpose, usage, and behavioral aspects thoroughly. However, without annotations or an output schema, it could benefit from more explicit details on return format or error handling to fully compensate for the lack of structured data.

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

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

The input schema has 100% description coverage (the 'id' parameter is documented as 'ID of the issue to retrieve'), so the baseline is 3. The description adds value by emphasizing the 'unique ID' requirement and clarifying that it retrieves 'detailed information about a specific issue,' reinforcing the parameter's purpose beyond the schema's basic 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 clearly states the tool's purpose with a specific verb ('Gets') and resource ('an issue from the task trellis system'), distinguishing it from siblings like 'list_issues' (which retrieves multiple issues) and 'create_issue'/'update_issue' (which modify issues). The first sentence establishes a precise read-only retrieval operation.

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

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

The description explicitly states 'Use this tool to retrieve detailed information about a specific issue by its unique ID,' providing clear when-to-use guidance. It also lists six specific usage scenarios (e.g., 'Review task details before starting work,' 'Check issue status and dependencies'), which implicitly differentiate it from alternatives like 'list_issues' (for browsing) or modification 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: 'Returns the highest priority available issue of the specified type,' 'Does not modify task status or claim ownership,' 'Finds issues that are ready to work on (all prerequisites complete),' and details on return formats for success, no issues, and errors. This covers safety (non-modifying), prioritization logic, and error handling, though it doesn't mention rate limits or authentication needs.

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 well-structured with clear sections (Behavior, Available issue types, Required parameters, Usage patterns, Return format) and front-loaded key information. It's appropriately sized for the tool's complexity, but some redundancy exists (e.g., repeating 'Essential for discovering' in the opening and closing). Most sentences earn their place by adding value, though it could be slightly more concise.

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 (2 parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, behavior, parameters, and return formats. However, without an output schema, it doesn't detail the structure of the 'complete issue object' returned on success, which could leave gaps for an agent interpreting results. It compensates well with behavioral details but has minor omissions.

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 significant value beyond the schema: it explains the meaning of 'issueType' with available types and their hierarchy ('Top-level containers', 'Large features within projects', etc.), provides context for 'scope' with examples ('Limits search to issues within a specific project or area'), and includes usage patterns that clarify how parameters interact. This enhances understanding beyond the schema's enum and 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?

The description clearly states the tool's purpose: 'Gets the next available issue of a specific type' and 'Essential for discovering what work is available when you're ready to start on a new project, epic, feature, or task.' It specifies the verb ('Gets', 'find') and resource ('issue'), and distinguishes from siblings like 'list_issues' by focusing on the 'next available' issue based on priority and readiness.

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 when to use this tool: 'Use this tool to find the next available issue that's ready to work on' and 'Essential for discovering what work is ready to be done.' It provides clear usage patterns with examples (e.g., 'Find next project to work on: issueType='project''), and distinguishes it from alternatives by noting it 'Helps you discover what work is available without having to browse through all issues,' implying it's preferable over 'list_issues' for this specific 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and does so effectively. It describes the tool's filtering capabilities, default behaviors (e.g., 'includeClosed' defaults to false), and the structure of returned results (TrellisObjectSummary instances with specific fields). It also implies this is a read-only operation through context ('lists', 'retrieve'), though it doesn't explicitly state this as a safety guarantee.

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 well-structured with clear sections (purpose, available values, filtering options, usage patterns, results) and front-loads the core purpose. However, it's quite lengthy with detailed enumerations and examples—while informative, some of this could potentially be streamlined without losing essential guidance, preventing a perfect score for conciseness.

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 complexity (5 parameters, no output schema, no annotations), the description provides comprehensive coverage of purpose, parameters, usage, and results. It explains the return format in detail (TrellisObjectSummary fields), which compensates for the lack of output schema. The only minor gap is not explicitly addressing pagination or limits on result sets, which might be relevant for a list 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 description adds significant value beyond the input schema's 100% coverage. While the schema documents parameter types and basic descriptions, the description provides detailed semantics: it enumerates all valid values for 'type', 'status', and 'priority' parameters, explains what 'scope' means ('Limit results to a specific project or area of work'), clarifies array acceptance for certain parameters, and provides numerous concrete usage examples that illustrate parameter combinations and effects.

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 issues from the task trellis system' with a specific verb ('lists') and resource ('issues'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this from sibling tools like 'get_issue' (which retrieves a single issue) or 'get_next_available_issue' (which suggests a different retrieval pattern), missing full sibling differentiation.

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

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

The description provides clear context for usage ('Essential for discovering existing work items, understanding project structure, and finding issues that need attention') and includes specific usage patterns with examples. However, it doesn't explicitly state when NOT to use this tool (e.g., for retrieving a single issue use 'get_issue') or mention alternatives among the sibling tools, which would be needed for a perfect score.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool validates relationships and preserves an audit trail, automatically refreshes timestamps while preserving metadata, and includes a 'force' parameter for bypassing validation. However, it doesn't mention potential side effects like error conditions or permission requirements, leaving some gaps.

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

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

The description is well-structured with clear sections (purpose, available values, updatable properties, common patterns, behavioral notes) and front-loaded key information. While comprehensive, some sentences could be more concise (e.g., the introductory paragraph is slightly verbose), but overall it efficiently conveys necessary details without significant waste.

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

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

Given the complexity of a mutation tool with 7 parameters, no annotations, and no output schema, the description does an excellent job covering purpose, usage, parameters, and behavior. It explains status workflows, priority levels, and update patterns. The main gap is the lack of output details (what the tool returns), but otherwise it provides strong contextual completeness for effective agent use.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds significant value by explaining the semantics of 'status' and 'priority' with enumerated values and workflows, detailing what 'prerequisites' represents (dependency relationships), and clarifying the purpose of 'force' (bypass validation). It also provides common usage patterns that illustrate parameter combinations, enhancing understanding 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 specific action ('Updates an existing issue') and resource ('in the task trellis system'), distinguishing it from siblings like 'create_issue' and 'delete_issue'. It explicitly lists what can be modified (status, priority, prerequisites, content), making the purpose highly specific and differentiated.

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

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

The description provides explicit guidance on when to use this tool ('to modify properties of existing issues') and includes specific examples of common update patterns. It also advises on when to use the 'force' parameter ('only when bypassing standard validation is necessary for administrative operations'), offering clear usage context and exclusions.

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