TAPD MCP Server

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

No annotations provided, so description bears full burden. Discloses read-then-write strategy to avoid overwrite, file type/size limits, and error handling for write failure. Could mention idempotency or concurrency, but sufficient for safe use.

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?

Concise paragraph: first sentence summarizes action, then details constraints and error behavior. No filler, every sentence adds value.

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

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

No output schema, but description explains partial failure. Lacks return value details (e.g., what is returned on success). For a mutation tool with error handling, this is adequate but not exhaustive.

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

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

Schema coverage is 100%, baseline 3. Description adds minor context: file_base64 can include data URI, workspace_id can be obtained via other tools. Does not significantly enhance schema info.

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 explicitly states the multi-step action: upload image, read current description, append image, and write back. It distinguishes from siblings like tapd_upload_bug_image (upload only) and tapd_writeback (manual write).

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

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

Clear context: used for appending images to bug descriptions without overwriting. Mentions fallback to tapd_writeback on write failure. However, lacks explicit when-not-to-use or comparison to all siblings (e.g., tapd_upload_bug_attachment).

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?

Discloses behavioral traits beyond the readOnlyHint annotation: it can perform writes but is controlled, requires path to match official docs, pagination defaults to 30, file uploads not supported, workspace_id required, POST body format options, and need for explicit confirmation. 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?

Long but dense with useful information. Front-loaded with purpose and examples. Each sentence adds value, though could be slightly trimmed. Structured logically from overview to details.

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?

Comprehensive given complexity: covers purpose, usage guidelines, all parameter semantics, behavioral traits (write control, path rules, pagination, file upload exclusion, workspace_id requirement), and alternative tools. No output schema but that's acceptable for a generic pass-through 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 has 100% coverage, but description adds significant meaning: provides path examples and pattern explanation, clarifies use of data vs params, explains when to use body_format json vs form, and notes that workspace_id is needed. Description complements schema well.

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?

Clearly states it's a universal pass-through tool to call any TAPD OpenAPI REST endpoint for scenarios not covered by dedicated tools. Provides verb (call/invoke) and resource (TAPD OpenAPI), and distinguishes from siblings by noting it's for uncovered scenarios.

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

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

Explicitly states when to use (uncovered scenarios) and when not to use (prefer dedicated tools for file uploads and write operations). Gives context on POST write operation restrictions, requiring environment variable and confirmed=true, and advises to use dedicated write tools like tapd_create_bug.

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 mentions creation and optional story linking, but lacks details on permissions, error handling, idempotency, or any destructive side effects. The 'confirmed' boolean is noted, but overall transparency is adequate but not exhaustive.

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

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

The description is two sentences long, front-loaded with the core action, and covers key capabilities without redundancy. Every sentence earns its place, and there is no wasted text.

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

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

Given 49 parameters and no output schema, the description covers high-level capabilities and common fields well. The rich schema fills in the details. However, it omits context about return values, error handling, and required permissions, which would improve completeness for a tool of this complexity.

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

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

Schema coverage is 100%, so the schema already documents all parameters thoroughly. The description adds value by summarizing common fields and providing a workflow hint (use tapd_search_users), but it does not add significant meaning beyond what the schema provides. 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 clearly states the verb '创建' (create) and the resource 'bug' in TAPD, distinguishing it from sibling tools like tapd_list_bugs and tapd_create_story. It also lists key configurable fields, leaving no ambiguity about 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 description provides a specific usage guideline: suggesting users call tapd_search_users to confirm handler nicknames before creation, and noting the default assignment if no handler is provided. However, it does not explicitly state when to avoid this tool in favor of alternatives like tapd_create_story.

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?

No annotations provided, so description must carry full burden. It discloses creation with confirmation requirement and default owner assignment, but does not describe return value, side effects, rate limits, or error handling. The lack of output schema amplifies this 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 front-loaded with purpose and capabilities. The second sentence provides a crucial usage tip. Minimal waste, but the first sentence is long; could be slightly more 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 complex tool with 33 parameters and no output schema, the description is adequate but lacks explanation of return value, failure modes, and differentiation from sibling write tools. The prerequisite guidance is helpful 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 description coverage is 100% with detailed parameter docs. The description adds value by advising pre-use of tapd_search_users for owners, clarifying default owner behavior, and noting label auto-creation. This supplements the schema without redundancy.

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

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

The description clearly states it creates a confirmed requirement in TAPD, listing key settable fields. It implicitly distinguishes from sibling tools like tapd_create_bug by specifying it is for stories/requirements.

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 explicit guidance to first use tapd_search_users to confirm owner nick and notes default owner behavior. Lacks explicit when-not-to-use or comparison with update tools like tapd_writeback_story, but the advice is actionable.

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

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

Annotations declare readOnlyHint=true, which the description does not contradict. The description adds behavioral context by specifying the returned content (descriptions, steps, comments, attachments, images, videos) and that status includes workflow display name. No side effects or permissions mentioned, but readOnly is 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?

Two sentences: first states core action, second adds a specific output detail. No redundant words, front-loaded, efficient.

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 get-tool with 2 simple params and no output schema, the description adequately lists the types of content returned (descriptions, steps, comments, attachments, etc.) and a notable formatting detail. Covers necessary information.

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 descriptions for both bug_ids and workspace_id. The description adds minimal parameter info beyond the schema; the main added value is about output (status format). 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 tool's purpose: batch get TAPD bug details, listing specific content types (description, steps, comments, attachments, etc.). It distinguishes from siblings like tapd_list_bugs (likely summary) and tapd_list_bug_changes (history).

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

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

No explicit when-to-use or when-not-to-use guidance. The workspace_id parameter description hints at using other tools to find workspace IDs, but no differentiation from sibling tools like tapd_list_bugs for listing vs. detailed get.

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

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

Annotations declare readOnlyHint=true, consistent with 'get' behavior. Description adds useful context: returns detailed content including comments, attachments, images, videos, and status with workflow Chinese name. No contradictions, but could mention rate limits or auth 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 concise sentences: first states core purpose and included content, second adds detail on status format. No redundant information. Front-loaded with key action and resource.

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 retrieval tool with no output schema, description covers returned fields (description, comments, attachments, images, videos, status with workflow name). Missing details on pagination, error handling, or response structure, but adequate for typical 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?

Schema coverage is 100% with both parameters described. The description does not add significant new semantics beyond the schema; it merely restates the batch retrieval nature. Baseline 3 is appropriate as description doesn't 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?

Description clearly states it retrieves full content of multiple TAPD stories including descriptions, comments, attachments, images, and videos. Title '批量获取 TAPD 需求详情' reinforces purpose. This distinguishes from siblings like tapd_list_stories which likely provide summaries.

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 explicit guidance on when to use this tool vs alternatives. Does not mention when not to use (e.g., for single story retrieval, or for updating stories). No comparison to siblings like tapd_get_bugs or tapd_list_stories provided.

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. The description adds specific behavioral details: status changes include Chinese workflow names, and include_add_bug=true returns creation records. These go beyond annotations, though pagination behavior is not described.

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, front-loaded with the main purpose, and covers key usage, parameters, and special output in three sentences. No redundant 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 tool has 10 parameters (1 required) and no output schema, the description explains the required mutual exclusivity, filtering, sorting, and special behavior for status changes. It lacks explicit pagination or return format details, but these are implied by parameter descriptions.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the mutual exclusivity of bug_id/created/id, the effect of include_add_bug, and the workflow name output for status changes—details not in 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 clearly states the tool queries TAPD bug change history, specifying the resource ('bug changes') and the action ('查询'). It distinguishes from siblings like tapd_list_bugs (list bugs) and tapd_list_story_changes (story changes) by focusing on bugs and history.

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

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

The description explicitly states the required parameter condition ('bug_id, created, id 至少提供一个'), filters, and sorting. It implies usage for bug change history, but does not explicitly state when not to use or name alternatives. However, siblings like tapd_list_bugs for listing bugs provide clear differentiation.

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?

Read-only annotation is consistent. Description details aggregation across projects, pagination per project, order behavior, and status format 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?

Description is a single verbose paragraph. While front-loaded with purpose, it could be more structured (e.g., bullet points) to improve readability for an AI 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 tool with 57 parameters and no output schema, description covers major behaviors (defaults, aggregation, pagination, order, presentation rules). Lacks details on return structure beyond Markdown table mention.

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 covers 100% of parameters. Description adds contextual interaction details (e.g., id bypasses owner filter unless current_owner specified, story_id requires workspace_id), supplementing 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?

Description clearly states it queries TAPD bug list, defaults to current user, and specifies how to filter by owner, id, story_id, workspace_id. However, it does not distinguish from sibling tapd_get_bugs, which may overlap in functionality.

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 explicit guidance on when to use parameters (e.g., current_owner, id, workspace_id) and default behavior. Lacks explicit exclusions or alternatives to sibling tools like tapd_get_bugs.

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

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

The readOnlyHint annotation is consistent with the query nature. The description provides extensive behavioral context: support for multiple IDs, fuzzy matching, time queries, sorting, pagination, and custom field filtering. No contradictions.

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 that packs a lot of information. It is front-loaded with the main action. While slightly lengthy, it is efficient and each component adds value.

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 18 parameters, 100% schema coverage, and no output schema, the description adequately covers the tool's purpose and usage. It does not detail return format, but that is acceptable for a list tool; the context is complete enough for an AI 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?

Schema coverage is 100%, so the description does not need to explain schema fields. However, it adds value by summarizing the filtering capabilities and the use case (selecting iteration_id). This exceeds the baseline of 3.

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 queries TAPD iteration lists with filtering, sorting, and pagination. It distinguishes from sibling tools like tapd_list_bugs and tapd_list_stories by focusing on iterations, and explicitly mentions its use for selecting iteration_id in create/update 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 hints at usage context (when creating/updating requirements) but does not explicitly say when not to use this tool or mention alternatives. The sibling list tools are distinct, so the usage is clear 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 only provide readOnlyHint=true, which matches the query-only behavior. The description goes further by disclosing aggregation pagination (per-project pages) and final sort order after merge, beyond what annotations convey.

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

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

The description is lengthy but well-structured: core behavior first, then filtering, then display convention. It could be more concise, but the detail is warranted given the tool's complexity. Front-loaded with key info.

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 43 parameters and no output schema, the description covers essential invocation details: return format (Markdown table with all columns), pagination, sorting, and aggregation behavior. Minor gaps in exact column list, but sufficient for selection and 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 some extra context (e.g., id bypasses owner filter, aggregation pagination) but does not significantly enhance parameter understanding beyond the schema's 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 queries TAPD stories, with default behavior (current user's stories) and options to filter by owner, workspace_id, and many fields. It distinguishes from sibling tools (e.g., bugs) by focusing on stories.

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 explicit guidance on when to use: default owner, workspace_id scoping, aggregation vs single project, and suggests using tapd_search_users and tapd_list_workspaces for preparation. Also explains pagination and sorting differences.

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's '查询' aligns with the readOnlyHint=true annotation. It adds a behavioral detail by mentioning that include_details=true maps to TAPD's need_parse_changes=1. No contradictions or hidden side effects are mentioned, but it could disclose more about response 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 two sentences, front-loading the core purpose and then adding key usage constraints. Every sentence is informative 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?

Given 11 parameters and no output schema, the description covers the conditional requirement and filtering well. It hints at include_details behavior. However, it lacks description of the output structure (e.g., field_changes format) and pagination details beyond page/limit, which are more important 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 baseline is 3. The description adds value by grouping the three mutually exclusive parameters and explaining the filtering options (e.g., by change type, field, creator). It also provides an example for 'order'. This goes beyond the schema's individual 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 clearly states the tool queries TAPD story change history and field-level details. The verb '查询' and resource '需求变更历史' are specific, and it distinguishes from sibling tools like tapd_list_bugs or tapd_list_bug_changes by being story-specific.

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 the mandatory condition (at least one of story_id, created, or id) and lists filtering options. However, it does not explicitly tell when not to use this tool or compare it with alternatives like tapd_list_bug_changes, which would improve 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, and the description adds that results are 'directly associated' and filtering is local ('本地过滤'), providing behavioral context beyond annotations.

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

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

The description is a single sentence that efficiently conveys the tool's purpose and key behavior with 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?

With 6 parameters and no output schema, the description is adequate but lacks details on return structure, pagination behavior, and the effect of include_test_plan, leaving some gaps.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds little parameter-specific meaning beyond what is in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists test cases associated with a TAPD story, with local filtering. It is distinct from sibling tools like tapd_list_bugs and tapd_list_stories.

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 querying test cases by story, but does not explicitly state when to use it versus alternatives, nor when not to use it.

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

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

Annotations already indicate readOnlyHint=true, and the description adds valuable behavioral context: default query for current user, automatic filtering of organization entries, and the relationship with sibling tools for aggregated queries. No contradictions.

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 and well-structured: three sentences that front-load the main purpose, then add filtering and usage context. Every sentence adds value 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?

The description covers the tool's purpose, defaults, filtering, and integration with sibling tools. However, it does not explicitly describe the output structure (e.g., that it returns workspace IDs or full project objects), which would add completeness. For a simple list tool with no output schema, this is adequate but not fully 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 description coverage is 100%, so the schema already documents both parameters. The description repeats some details (default user for nick, default false for include_organization) but adds minimal extra meaning beyond explaining the aggregation use case, which is covered in context.

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 TAPD projects for a user, distinguishes from siblings like tapd_list_bugs by explaining it provides workspace IDs for aggregated queries, and specifies default behavior and filtering of organization entries.

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 guides when to use this tool (to obtain workspace IDs, especially before calling tapd_list_bugs/stories without workspace_id), implies when not to use (if workspace IDs are known or need user nick lookup with tapd_search_users), and explains the default filtering behavior.

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 confirms the read-only nature already indicated by readOnlyHint annotation. It adds context about the purpose of searching to retrieve nick, but does not disclose other behavioral details 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 concise with only two sentences, front-loaded with the primary purpose and then a usage directive. Every sentence is necessary and impactful.

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, the description covers its primary function and usage context. It does not detail output format, but that is acceptable as output schema is absent. The description is fairly complete for an agent to decide when and how to use it.

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

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

While schema descriptions cover all parameters, the tool description adds value by explaining the keyword parameter's matching behavior (name, nick, email) and the purpose of using the tool (to get nick for updates). This enhances 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 tool searches project members by name, TAPD nick, or email, and provides a specific use case of confirming a handler's nick before updating a bug. This distinguishes it from sibling tools like tapd_list_bugs or tapd_create_bug.

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 the tool: before updating a bug handler to confirm the target's nick. It implies usage within a workspace but does not explicitly list scenarios where it should not be used. Overall, it provides clear 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?

No annotations provided. Description discloses file size limit, supported types, and base64 requirement. Does not mention authentication, rate limits, or side effects beyond creating an attachment. Adequate but not exhaustive.

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

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

Four concise sentences, front-loaded with core action and constraints. Every sentence adds value: type/size, encoding method, usage recommendation, and verification hint.

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

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

Covers key aspects: what it does, input format, usage context. Lacks output/response details, but no output schema exists. Suggests verification via another tool. Sufficient 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 coverage is 100%, but description adds value: explains base64 encoding rationale, confirms boolean requirement, workspace_id lookup guidance. Exceeds baseline 3 by providing practical context.

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 uploads files to a bug's attachments, specifies supported types and constraints, and differentiates from siblings by noting that videos/screenshots should use this tool rather than embedding in descriptions.

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 explicit guidance: use base64 encoding (no local path), confirmed must be true, and videos/screenshots belong here. Also suggests verifying with tapd_get_bugs. Lacks explicit 'when not to use' but contrast with siblings is implied.

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

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

With no annotations provided, the description carries full burden. It discloses supported image types, single file ≤5MB, no modification to description, and returns html_code. It does not mention rate limits or authentication needs, but these are implied. The description provides adequate transparency for a straightforward upload 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 extremely concise: two sentences that cover purpose, constraints, and usage flow. No redundant information. 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 absence of annotations and output schema, the description is fairly complete. It covers purpose, parameter details, return value (html_code), and the required subsequent steps to complete the bug description update. It could mention potential limitations like rate limits, but overall it provides sufficient context for an agent to use 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 baseline is 3. The description adds value by clarifying that file_base64 can include or omit the data:URI prefix, confirmed must be true, filename must have an appropriate suffix, and workspace_id can be obtained from other tools. This goes beyond the schema definitions.

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

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

The description clearly states the tool uploads an image to TAPD and returns an HTML img fragment for embedding in bug descriptions. It specifies supported formats and size limits, and distinguishes from the sibling tool tapd_append_bug_description_image that performs the full workflow.

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

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

Explicitly explains when to use this tool: it only uploads the image, does not modify the description. It tells the agent to manually fetch the description, concatenate the html_code, and write back using tapd_writeback, or alternatively use tapd_append_bug_description_image for a one-step process. This provides clear context vs 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?

Discloses write operation, non-transactional multi-request behavior, partial success, and field-specific overwrite behavior (description field). With no annotations, description carries full burden and provides adequate behavioral context, though could mention more about permissions 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?

Description is concise and front-loaded with main purpose. Lists operations, then conditions, then warning in a clear structure. No wasted sentences, but could be slightly more efficient.

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 high complexity (52 params, 3 required) and no output schema, description covers what the tool does, constraints, and important behaviors (partial success, field overwrite, status validation). Could mention return format or error handling more, but 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 descriptions cover 100% of 52 parameters, so baseline is 3. Description adds high-level grouping and the constraint 'at least one of...' but does not significantly enhance meaning 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?

Description clearly states it updates TAPD bugs with multiple operations (comment, title, description, status, owners, fields). Verb '更新' and resource 'TAPD bug' are specific, distinguishing from sibling tools like tapd_create_bug (creation) and tapd_list_bugs (listing).

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?

Specifies required minimum inputs (at least one of comment, title, etc.) and notes non-transactionality with partial success. Provides context on when to use (updating a bug) but lacks explicit when-not-to-use or alternative tool references beyond implied sibling differentiation.

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. It discloses non-transactional behavior, partial success, and that description field overwrites. Additional details about confirmed flag and owner update modes are included. No contradictions.

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 (3-4 sentences) with front-loaded key actions. Every sentence adds value: enumerating operations, noting independence, warning about non-transactionality. No redundant or filler 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?

Given 33 parameters, no output schema, and no annotations, the description is fairly complete. It covers overall behavior, partial success, and field specifics. Could mention return format or authentication needs, but sufficient for an agent to use 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%, baseline is 3. The description adds extra meaning beyond schema: explains 'confirmed' must be true, 'description' overwrites, 'owner_update_mode' semantics, and 'is_auto_close_task' requires target_status. This provides valuable context for proper usage.

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 updates TAPD stories with multiple confirmed operations (comment, description, status, owners, fields), distinguishing it from sibling tools that list, create, or get stories. The verb '更新' and resource 'TAPD 需求' are specific.

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

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

The description explains that operations are independent, combinable, and non-transactional (partial success possible). It lists required parameters and warns about description overwriting. However, it does not explicitly compare to alternatives or give when-not-to-use scenarios.

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