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

Discloses validation of link_original_items_with_role against target project enum, stripping of outgoing links, and dry_run preview. Annotations already indicate non-read-only, but description adds concrete behavioral details.

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, front-loaded with core purpose. Additional details are relevant and efficiently stated, though the paragraph 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?

Covers prerequisites, default behavior, key parameter options, and validation. Output schema exists, so missing return info is acceptable. Adequate for a complex tool with 10 parameters.

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 parameters. Description adds meaning beyond schema by explaining behavior of link_original_items_with_role and remove_outgoing_links, and default destination behavior.

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

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

States clearly: 'Copy a document, duplicating its structure, body, and contained work items.' Explicitly distinguishes from create_document/update_document which lose contained items.

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 when-not: 'Rebuilding via create_document/update_document loses the contained items.' Also advises checking list_documents first for name availability.

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 discloses important behavioral traits beyond the annotations: duplicate name conflicts, write-time validation, the necessity of rendering layout types for fields to appear, Markdown-to-sanitized-HTML conversion, table caption widget behavior, and round-tripping of raw HTML. This is rich, non-obvious context that annotations (readOnlyHint=false, etc.) do not convey.

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

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

The description is appropriately sized for the tool's complexity. Every sentence adds value, from the core purpose to caveats and workflow guidance. It is front-loaded with the primary action, then logically progresses through prerequisites, layout requirements, and Markdown behavior 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 the 12-parameter schema with 100% coverage and an output schema, the description covers all necessary context: uniqueness, validation via enum options, layout requirements, Markdown handling, and follow-up operations. It provides a complete picture of how to use the tool correctly and what to expect, without needing to detail return values (covered by output schema).

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

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

Even though the schema describes each parameter, the description adds crucial semantic context: document_name uniqueness and the need to check existing documents; type/status/custom_fields validation requiring enum resolution; rendering_layout_types must include every work item type or fields won't render; home_page_content Markdown conversion and caption behavior. This significantly enriches understanding of how parameters interact.

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 'Create a document in a space' with a specific verb and resource. It distinguishes itself from sibling tools like list_documents, update_document, and copy_document by focusing on creation and adding detailed caveats (uniqueness, layout types, Markdown conversion) that are unique to creation.

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

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

The description provides explicit usage guidance: 'check list_documents first' to avoid duplicate names, 'resolve ids via list_document_enum_options first' and 'list_work_item_enum_options' for validation, and references to post-create actions via update_document and move_work_item_to_document. It clearly signals when to use this tool 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?

Annotations provide readOnlyHint=false, destructiveHint=false, idempotentHint=false. Description adds critical behaviors: total upload cap 25 MiB, not idempotent, batch rejected on collision, cannot delete uploads. This enriches annotations without contradiction.

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 thorough but slightly verbose. However, each sentence adds value, and it is well-structured with primary function first, then constraints and warnings. Very efficient for the complexity.

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

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

Completely covers all aspects: usage, limitations, parameter semantics, error conditions, performance tips. Without the output schema, it still fully informs an agent how to invoke and 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%, but description adds substantial meaning: file_path read from local disk, file_name becomes attachment id usable in update_document, dry_run previews. Explains collision and idempotency implications for parameters.

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

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

The description clearly states it uploads 1-10 local files as document attachments in one request. It specifies the resource (document attachments) and action (upload/create), and the detail about file_name becoming the attachment id distinguishes it from other tools.

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

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

Extensive usage guidelines: when to use (upload attachments), when to avoid (cannot delete, check collisions, idempotency). Explicitly states 'Pure create -- nothing is replaced.' Advises checking list_document_attachments first and splitting oversized batches. Provides clear exclusions and 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 annotations already indicating write, non-idempotent, and open-world behavior, the description adds valuable context: comments are authored by the token's user, 'text/html' is sent unsanitized, retries duplicate comments, and attachment references must name existing document attachments. This goes well beyond the structured 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 compact and front-loaded with the primary purpose. Every line adds operational value—batching, parent IDs, sanitization, idempotency, and attachment resolution—without redundancy or padding.

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

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

Given the tool's complexity (batch create, formatting options, attachments) and the presence of an output schema, the description covers all critical behavioral and prerequisite information. It leaves no major gaps for an agent to misuse the tool, from idempotency to authentication to attachment handling.

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 covers all parameters with descriptions, providing a high baseline. The description enriches this by explaining parent_comment_id should come from list_document_comments and that 'text/html' text is unsanitized, which directly informs parameter usage. It does not fully explain dry_run, but schema coverage already handles that adequately.

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 begins with a specific verb+resource: 'Create one or more comments on a document in one request.' This clearly distinguishes it from siblings like create_work_item_comments and update_document_comment, and the batch aspect ('in one request') adds further specificity.

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

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

The description provides clear context on how to use the tool, such as setting parent_comment_id from list_document_comments and resolving attachments via list_document_attachments first. It does not explicitly state when not to use this tool versus alternatives, but the resource-specific title and first sentence make the usage domain evident.

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

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

The description discloses non-obvious behaviors not fully covered by annotations: server reads file_path locally requiring absolute paths, 25 MiB cap per call, server-assigned attachment_ids differing from file_name, whole-batch rejection on collision, and explicit non-idempotency. This aligns with annotations (idempotentHint=false, readOnlyHint=false) with 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 detailed but every sentence serves a purpose: core action, alternatives, prerequisites, file_path caveat, size limits, output naming, collision behavior, and idempotency. It is front-loaded and structured logically, 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?

For a complex upload operation with 6 parameters, the description covers all essential aspects: purpose, alternatives, prerequisites, operational constraints, error conditions, and idempotency. An output schema exists, so return values are not required in the description.

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

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

Schema coverage is 100%, so baseline is 3. The description adds critical semantics beyond the schema: file_path must be absolute and server-readable, file_name is not the id, iteration matches get_test_record, and collision behavior with existing attachments. This meaningfully enhances agent understanding.

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

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

The description states a specific verb ('Upload'), resource ('test record attachments'), and scope ('1-10 local files in one request'). It explicitly distinguishes from sibling tools by directing document attachments to create_document_attachments and work item attachments to create_work_item_attachments.

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

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

Provides explicit when-to-use guidance: names alternatives and when to use them. Also instructs to verify record coordinates via list_test_records first and advises on handling size caps (split batches) and name collisions (check list_test_record_attachments).

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 give minimal safety hints, but the description adds critical behavioral context: atomicity, duplicate iteration semantics, verbatim comment handling, full id returns, and validation rules that go far beyond the annotations.

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

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

The description is dense but every sentence contributes important information. The purpose is front-loaded, though the overall structure is a single paragraph that could be better organized into bullet points for readability.

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

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

The tool is complex (batch atomic creation, validations, duplicate semantics) and the description covers all key aspects, including return IDs and validation rules. It is complete even with an output schema available.

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?

Since schema description coverage is 100%, baseline is 3. The description adds meaningful semantics beyond the schema, such as validation of result, that defect must reference an existing work item, and that comment_format controls verbatim sending.

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 1-50 test records on one test run, with a specific verb and resource. It also distinguishes from sibling tools by naming create_test_runs and list_test_records.

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 list_test_records for reading back, create_test_runs for creating the run, and resolve invalid test_case_id via list_work_items. It also explains batch behavior and duplicate handling.

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 discloses several important behaviors beyond the annotations: id must be provided per item, type/status are validated against project enumerations, template_id against existing templates, custom_fields keys are validated but enum-typed values are not, and the operation is atomic. This adds substantial value over the sparse 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 structured with a lead sentence followed by four bullet points covering key validation details. While a bit dense, each sentence provides useful information. It is appropriately sized for the complexity of the 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?

The description thoroughly covers validation behavior, atomicity, and references related tooling. It is complete given the tool's complexity and the existence of an output schema, which means return-value details are not necessary.

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 critical semantics not present in the schema: id is required per item and never auto-generated, type/status validation rules, template_id validation source, and custom_fields validation caveats. This compensates for the nested fields that lack schema descriptions.

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

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

The description opens with 'Create 1-50 test runs in one project in one bulk request', specifying the verb, resource, and scope. It clearly distinguishes itself from sibling tools like create_test_records by naming 'test runs' and emphasizing the bulk, single-project nature.

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

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

The description provides clear context for when to use the tool: bulk creation of 1-50 test runs in one project. It also references list_test_runs(templates=True) as a prerequisite for template validation. However, it does not explicitly state when not to use it or mention 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?

The description goes far beyond the annotations. It discloses that file_path is read from the server process, the 25 MiB cap, non-predictable server-assigned attachment_ids, duplicate file_name behavior, heading-type work item portal limitation, and the non-idempotent nature with a concrete consequence. This is rich, actionable context not present in the annotations, and no contradictions with annotations exist.

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 sized for the tool's complexity. It is front-loaded with the core purpose, then logically moves to alternatives, constraints, edge cases, and idempotency. Every sentence carries unique information; there is no filler or 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 the tool has 4 parameters, annotations, an output schema, and 45 sibling tools, this description is exceptionally complete. It covers usage, constraints, behavioral quirks, failure handling, and result semantics, making it self-sufficient for an agent to select and invoke the tool correctly.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema. It explains file_path semantics (absolute paths, server-side read), the significance of attachment_ids as reference tokens, duplicate file_name allowances, and the 1–10/25 MiB constraints, which are not fully captured in the property descriptions.

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

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

The description opens with a specific verb and resource: 'Upload 1-10 local files as work item attachments in one request.' It clearly scopes count and context, and immediately distinguishes from the sibling tool create_document_attachments, leaving no ambiguity about what this 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?

Explicit guidance is provided: 'For document attachments use create_document_attachments instead.' It also advises using the Polarion portal for oversized files, splitting oversized batches across calls, and verifying with list_work_item_attachments after ambiguous failures—covering when to use this tool, alternatives, and fallback actions.

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

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

The description adds significant behavioral context beyond annotations: text/html is unsanitized (security risk), not idempotent (retry duplicates), always authored by token's user, and image refs must match existing attachments. Annotations already indicate non-idempotent and non-readOnly, so the description reinforces and expands on these traits with no contradiction.

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 front-loaded: the first sentence states the core purpose. Subsequent sentences add critical behavioral and usage details in a structured manner without redundancy. 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 complexity of supporting multiple comments, replies, formatting, and image references, the description covers behavioral aspects, usage guidance, and parameter semantics thoroughly. The presence of a separate output schema (not shown but indicated) handles return value documentation, so the description is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds valuable context for parameters like parent_comment_id (source from list_work_item_comments), title (optional heading), and text_format ('text/html' unsanitized). It does not mention dry_run, but the schema covers it. The added meaning justifies a score of 4.

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

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

The description clearly states the tool creates one or more comments on a work item in one request. It distinguishes from sibling tools like list_work_item_comments (reading) and update_work_item_comment (updating). The verb 'create' and resource 'work item comments' are specific and unambiguous.

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

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

The description provides explicit when-to-use guidance: setting parent_comment_id for replies, optional title, handling unsanitized HTML, and resolving image references via list_work_item_attachments. It warns about non-idempotence and that comments are always authored by the token's user. No when-not-to-use is needed because the tool's purpose is clear.

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

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

The description is exceptionally transparent about behavior beyond annotations: atomicity, role/target existence validation, defaulting behavior (target_project_id defaults to source, revision pins else HEAD), suspect flag meaning, entire batch rollback on duplicate, and the critical phantom success caveat where a new same-role link reports created but is not persisted on document-attached sources. This goes far beyond the simple write hints in annotations.

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

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

The description is front-loaded with the purpose, then logically organized into validation/spec, rollback behavior, and phantom success warning. It is dense but each sentence provides critical operational detail. It could be slightly tighter, but the structure and direct information justify a high score.

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

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

For a complex batch creation tool, the description covers all essential behavioral aspects: atomicity, validation, defaults, rollback, output ids (delete-path ids), and a non-obvious phantom success scenario. An output schema exists to cover return values, and the description complements it thoroughly. No significant gaps remain.

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. However, the description adds meaningful semantic detail for parameters: target_project_id defaults to source, revision pinning vs HEAD, suspect flags re-review, and duplicate role+target causing batch rollback. These enrich understanding beyond the plain schema descriptions, though it doesn't fully detail every parameter's edge cases.

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

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

The description opens with 'Create 1-50 outgoing links from one source work item, atomically' – a specific verb, resource, and scope. It clearly distinguishes this from sibling link/attachment tools (list/delete/update_work_item_links) by focusing on creation and batch atomicity.

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

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

Provides clear context: atomic batch creation, validation before writing, and rollback on duplicate role+target. It tells the agent to re-query list_work_item_links before retrying and to verify with list_work_item_links, but it does not explicitly contrast with alternatives like update_work_item_link or delete_work_item_links, so it falls short of full when/when-not guidance.

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

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

The description adds significant behavioral context beyond annotations: atomicity (batch rejection), description format nuances (Markdown vs HTML, table styling, caption widget), validation behavior for enums and custom_fields, and the fact that returns new IDs. Annotations are limited (readOnlyHint false, destructiveHint false), so the description carries the full burden and delivers thoroughly, with 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 relatively long but every sentence adds value. It is well-structured with clear logical flow: first states the core action, then uses newlines to segment important caveats (free-floating, atomicity, description format, validation). Minor redundancy could be trimmed but overall efficient and front-loaded with key points.

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 (bulk creation with many optional fields, atomicity, format rules, validation needs), the description is remarkably complete. It covers creation procedure, post-creation step requirements, error implications, description format nuances, and points to sibling tools for enum resolution and document placement. The output schema exists to document return values, so that aspect is covered.

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?

Although schema coverage is 100%, the description adds operational meaning for each parameter: for 'items', it explains sub-field usage (description as Markdown only, enum validation, custom_fields key requirements) and links to list_work_item_enum_options for ID resolution. For 'dry_run', it explains preview behavior. The project_id parameter is straightforward. The description compensates for any schema terseness by providing actionable 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 creates 1-50 work items in one project in a single request. It explicitly distinguishes from a sibling tool by stating 'place into a document with move_work_item_to_document (this tool cannot)', which differentiates its purpose from related creation tools.

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

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

The description provides explicit guidance on when to use this tool: for bulk creation, and notes that items are created free-floating, requiring another tool for document placement. It warns about atomicity (one bad item rejects the whole batch), explains description format rules (Markdown only at creation, HTML later), and advises resolving enum IDs before use. It implies not to use for updates or single-item creation (covered by siblings). No explicit 'when not to use' but strong contextual cues.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable behavioral details: stale refs never fail, results split into deleted/not_found, and mentions dry_run feature. No contradiction with annotations.

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

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

The description is highly concise: two short paragraphs with no wasted words. The main action and limit are front-loaded, and essential usage notes follow immediately. Every sentence earns its place.

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

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

Given the tool's destructive nature and 4 parameters, the description covers behavior for stale refs, dry run, and directionality. An output schema exists, so return values are not needed. A minor gap is the lack of explicit prerequisites or permissions, but overall it is sufficiently complete.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by clarifying that the 'links' parameter should contain existing outgoing links (obtained from list_work_item_links) and that stale refs are handled gracefully. This enriches the agent's understanding.

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

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

The description clearly states the action (delete), resource (outgoing links from a source work item), and scope (1-50 links). It effectively distinguishes from sibling tools like list_work_item_links and update_work_item_link by specifying 'outgoing only'.

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 (for outgoing links) and when not (for back links, use the source item). It references list_work_item_links for obtaining link IDs and explains behavior with stale refs, providing clear context for correct usage.

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

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

Annotations already mark readOnlyHint=true, but the description adds valuable behavioral detail: the nature of content_html (raw homePageContent HTML, inline prose only), the dependency on it for update_document, and the warning not to feed back a blanked body. These go beyond the annotation and help the agent avoid mistakes.

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 yet information-dense. It uses two short paragraphs: the first states the core purpose, the second details the optional flag and critical caveats. No filler words; every sentence contributes actionable guidance.

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

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

Given the output schema exists (handling return structure), the description covers the essential aspects: the tool's purpose, the optional behavior, and cross-tool dependencies. It also warns about a subtle failure mode (blanked body). This is complete for a read-only metadata retrieval 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?

Since the schema already provides descriptions for all four parameters (100% coverage), the baseline is 3. The description adds substantial meaning for include_home_page_content_html, explaining its purpose for round-trip editing and its relationship to raw HTML, which exceeds the schema's one-line description. Other parameters are already well-schema-described.

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 explicitly states the tool retrieves document metadata and enumerates the fields (title, type, status, timestamps, editors, custom fields). This clearly distinguishes it from sibling tools that handle attachments or content rendering.

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 by naming read_document as the alternative for rendered content with headings and embedded work items, and by linking include_home_page_content_html to update_document for round-trip editing. This tells the agent when to use this tool 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?

Annotations already declare readOnlyHint=true, and the description reinforces a read-only fetch. It adds valuable behavioral context by specifying supported image extensions (PNG, JPEG, GIF, WebP) and their return format, and that SVG returns source markup as text while other extensions are rejected before any request. This goes beyond the annotation to clarify exact output behavior and limitations.

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 four sentences long, with the main purpose in the first sentence. Each subsequent sentence adds necessary information about media types, rejection, and sibling alternatives, with no redundant 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?

Given the moderate complexity and the presence of schema descriptions and readOnlyHint annotation, the description fully explains the tool's return behavior (image vs SVG text), the pre-request rejection of unsupported extensions, and how to discover attachment ids. With no output schema, this behavioral explanation compensates adequately.

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 covers 100% of parameters with descriptions, including attachment_id as 'bare filename token' and space_id as '_default'. The description adds little beyond this coverage, only linking to list_document_attachments for discovery, so the baseline score of 3 is appropriate.

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

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

The description uses the specific verb 'Fetch' with the resource 'document attachment's content for viewing,' clearly stating the operation. It distinguishes from sibling tools by explicitly directing work item attachments to get_work_item_attachment_content and pointing to list_document_attachments for discovery.

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 when-to-use guidance: 'Use get_work_item_attachment_content for work item attachments' and 'Use list_document_attachments to discover attachment ids, file names, and sizes.' It also warns that unsupported extensions are rejected beforehand, implying not to attempt unsupported types.

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, so the description goes beyond that by disclosing that hand-written markup breaks numbering and that the tool covers macro-id and metadata-scope caveats. While it doesn't elaborate on the caveats, it adds useful behavioral context beyond the annotation.

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

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

The description is three sentences long, front-loaded with the primary purpose. Each sentence adds value: the second explains why templates are mandatory, and the third mentions additional caveats. No filler or redundancy.

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

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

For a read-only, zero-parameter tool with an output schema, the description covers purpose, usage context, and important caveats. It is sufficient for an agent to know when to call it and what to expect, with output shape presumably in the schema.

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

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

The tool has zero parameters, so there is no parameter semantics to address. Per the baseline for 0-parameter tools, a score of 4 is appropriate; the description doesn't need to explain parameters.

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

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

The description clearly states the tool fetches the required HTML templates for specific elements (tables, captions, links, widgets) used with update_work_items/update_document. The verb 'Fetch' and resource 'HTML templates' are specific, and the mention of these elements distinguishes it from siblings like get_sql_query_recipes.

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: any new table, numbered caption, link, or widget must be adapted from these templates. It also warns against the alternative (plain hand-written markup) by explaining it renders unstyled and breaks numbering, giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint=true, and the description confirms a read-only operation by stating 'Fetch copy-paste SQL recipes' and 'Includes the table schema.' Additional context about output content and usage is provided, which adds value 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 exceptionally concise, consisting of two sentences that immediately convey the action ('Fetch copy-paste SQL recipes') and usage guidance. No extraneous information is included.

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 no parameters and an output schema, the description covers all necessary context: what it does, when to use it, and what it includes (recipes and table schema). The sibling tools are all distinct, so no confusion arises.

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 no parameters with 100% coverage, so no parameter descriptions are needed. The description adequately describes the tool's function without requiring parameter details, earning the baseline score of 4.

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

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

The description clearly states the tool's purpose: fetching SQL recipes for the list_work_items SQL prefix. It specifies the resource (SQL recipes) and includes context about table schema, distinguishing it from sibling tools that handle work items, documents, and comments.

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

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

The description explicitly advises using this tool before writing any SQL query (document scope, custom-field, traceability) and adapting a recipe instead of hand-writing joins. This provides clear when-to-use guidance, though alternatives are not explicitly named due to the unique nature of this tool.

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

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

Annotations only declare readOnlyHint=true, and the description adds valuable behavioral context: comment_html carries raw HTML comments, plain-text comments return as-is, and verification of coordinates via list_test_records. No contradiction with annotations, and the added detail goes beyond the schema.

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

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

The description is compact, front-loaded with the core purpose, and every sentence earns its place: it states the function, directs to alternatives, and notes output behavior. 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?

The tool has read-only annotations, a fully described schema, and an output schema, so the description does not need to explain return values. It covers usage alternatives, output nuances, and verification steps, making it complete for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the input schema fully documents all parameters. The description adds a hint about test_case_id format ('as returned by list_test_records') but does not significantly extend the schema's parameter explanations, which is acceptable given the baseline for high 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 uses a specific verb ('Get full detail') and names the exact resource ('one test-case iteration inside a test run'), clearly distinguishing it from run-wide summaries and run metadata tools. It also names sibling tools explicitly, making the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: use list_test_records for run-wide summaries, get_test_run for run metadata, and verify coordinates via list_test_records if not found. This provides clear alternatives and context for selecting this tool.

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

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

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral details beyond that: PNG/JPEG/GIF/WebP return as viewable images, SVG returns source markup, and other extensions are rejected before any request. This gives the agent clear expectations for output format and failure modes.

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

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

The description is four sentences long, front-loaded with the core purpose, and every sentence provides distinct value: functionality, output format, exclusions, and cross-tool alternatives. No redundancy or filler.

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

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

Despite having no output schema and only readOnlyHint annotation, the description covers purpose, return types, rejection behavior, domain alternatives, and discovery methods. For a read-only content-fetching tool, this is comprehensive and leaves no critical ambiguity.

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 practical parameter acquisition guidance by pointing to list_test_record_attachments to discover attachment ids, file names, and sizes. This goes slightly beyond the schema's static property descriptions and helps the agent populate the required fields.

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

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

The description opens with a specific verb+resource: 'Fetch a test record attachment's content for viewing.' It immediately scopes the tool to test-record attachments and differentiates from sibling tools by explicitly naming alternatives for document and work item attachments.

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

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

Provides explicit usage guidance: 'Use get_document_attachment_content or get_work_item_attachment_content for the other domains' and 'Use list_test_record_attachments to discover attachment ids, file names, and sizes.' Also clarifies supported file types and rejection behavior, helping the agent decide when to invoke this tool.

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

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

Beyond the readOnlyHint annotation, the description explains the behavior of include_home_page_content_html and warns about feeding back a blanked body. This adds useful behavioral context.

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

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

The description is concise and front-loaded with purpose. It provides necessary details without fluff, though it could be slightly more structured. 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 presence of an output schema, the description covers key behavioral aspects and parameter nuances. It is complete for a read-only tool with good annotations and schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning for include_home_page_content_html, specifying when it fills content_html and a warning, which provides value 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 'Get full details of one test run by ID', specifying the verb and resource. It also describes the returned fields, distinguishing it from list_test_runs which returns multiple runs.

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

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

The description implies usage by mentioning 'writable fields' and 'read-only context', but it does not explicitly state when to use this tool versus update_test_runs or list_test_runs. No clear when-not-to or 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?

Does not contradict annotations (readOnlyHint=true). Adds behavioral context about the include_description_html parameter and the caution regarding blanked bodies, which goes beyond the annotation.

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

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

Two short sentences, front-loaded with the main purpose. The second sentence, while technical, is relevant. No unnecessary filler.

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

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

Covers purpose and key parameter behavior. With an output schema, return values need not be described. However, lacking differentiation from read_work_item and no mention of error handling or permissions leaves 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% with descriptions for all three parameters. The description adds extra meaning for include_description_html, noting it is the required source for update_work_items, enriching the schema 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?

Description clearly states the tool gets full details of one work item by ID. However, it does not differentiate from sibling 'read_work_item', which may have overlapping 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?

Explicitly mentions that include_description_html is required for update_work_items and warns against feeding back a blanked body. Provides partial usage guidance but does not contrast with siblings like read_work_item.

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: PNG/JPEG/GIF/WebP return as viewable images, SVG returns source markup as text, and other extensions are rejected. This gives the agent actionable expectations about return format and validation, which annotations do not cover.

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

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

The description is concise and well-structured. The first sentence states the core purpose, and the following sentences provide essential format and alternate-tool guidance. 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?

Given there is no output schema, the description adequately explains return behaviors (image vs. text) and rejection rules. It fully covers the tool's functionality, including how to discover required IDs via a sibling tool, making it complete for 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?

While schema descriptions already cover all three parameters, the description adds valuable context: attachment_id is described as a 'bare filename token' from list_work_item_attachments. This clarifies the parameter's origin and format beyond the schema's basic description, enhancing semantic understanding.

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

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

The description states a specific action: 'Fetch a work item attachment's content for viewing.' It clearly identifies the resource (work item attachment) and distinguishes it from document attachments via explicit reference to get_document_attachment_content. This separates it from sibling tools.

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

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

Provides explicit guidance: 'Use get_document_attachment_content for document attachments' and 'Use list_work_item_attachments to discover attachment ids, file names, and sizes.' Also specifies the rejection of non-supported extensions before any request, giving clear usage constraints.

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

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

Beyond readOnlyHint, the description discloses important behavior: the returned id is the exact attachment token used in bodies, Polarion never validates references (so missing files possible), and ordering is server-defined. These details are not inferable from annotations or schema.

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

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

Every sentence provides distinct value: scope, id behavior, ordering, and cross-tool guidance. Efficient and well-structured despite moderate length.

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

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

With an output schema present, the description doesn't need to explain return values. It fully covers behavioral context, usage boundaries, and guidance for related tools, making it complete for a paginated-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?

Schema covers 60% of parameters (space_id, project_id, document_name have descriptions). The description adds no direct parameter semantics beyond implying pagination with 'paginated page.' page_size and page_number remain undocumented in the description but are self-explanatory from defaults.

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

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

The description states 'List a document's attachments as a paginated page' with a specific verb and resource. It distinguishes from siblings by explicitly noting 'Document attachments only, not work item attachments.'

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

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

It explicitly scopes the tool (document attachments only) and guides users to alternative tools: 'Use read_document for body context, list_documents for valid space/document ids.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations indicate readOnlyHint=true, consistent with listing. Description adds valuable detail: comments are returned as a flat page, threads via parent/child IDs, and text is unsanitized (security warning). Exceeds annotation info.

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?

Extremely concise: two sentences, no redundant words. Front-loaded with purpose, then threading and security warning. 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?

For a read-only list tool with output schema present, description covers purpose, threading, and security. Sufficient for correct invocation and understanding.

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 60% (3/5 params described). Description does not enhance parameter understanding beyond schema; it mentions parent_comment_id but this is output behavior, not parameter detail. No compensation for missing 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 'List a document's comments as a flat page.' with specific verb and resource. Explains threading via parent_comment_id and child_comment_ids, distinguishing it from sibling tools like list_work_item_comments.

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

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

No explicit guidance on when to use this tool vs. alternatives. The sibling list includes list_work_item_comments, but description does not differentiate or provide 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?

Discloses the fallback behavior for unknown document_type, which is beyond the readOnlyHint annotation. No contradictions with annotations.

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

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

Three clear, front-loaded sentences. No fluff, 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?

For a simple listing tool with an output schema, the description covers purpose, usage guidelines, and a behavioral nuance. It is complete given 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?

The schema provides descriptions for most parameters (field_id, project_id, document_type) covering 60% of parameters. The description adds critical context about document_type fallback and pre-write usage. Pagination params are standard, so the description adds value without over-explaining.

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

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

The description uses a specific verb ('list') and clarifies the scope ('valid enum option ids for a document field of a given type'). It distinguishes from siblings like list_work_item_enum_options by specifying 'document field'.

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 call this tool ('before create_document / update_document') and warns about invalid enum IDs being rejected. Also provides a caveat about unknown document_type falling back to '~'.

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?

Description adds caching behavior (60s) beyond readOnlyHint annotation. Also lists returned fields, providing transparency on output. No contradiction with annotations.

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

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

Two concise sentences with front-loaded purpose. No redundancy; 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?

Given output schema exists to document return values, description completes the picture with caching and tool differentiation. Missing parameter details slightly reduce completeness.

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 only 33% (project_id described). Description implies project_id needed but does not explain page_size or page_number. With low coverage, description should compensate, but it falls short.

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

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

Clear verb-resource pair: 'List a project's documents.' Specifies returned fields (space_id, document_name, etc.) and explicitly distinguishes sibling tool get_document by stating when to use it for author/editor ids.

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 guidance to use get_document for more detail, implying this tool is for summary listing. Also mentions 60-second cache, but lacks explicit when-not-to-use or alternatives beyond get_document.

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's 'List' action is consistent. It adds valuable non-obvious behavior about Lucene query wildcard rules (trailing allowed, leading rejected) and clarifies that only accessible projects are returned. No contradiction with annotations.

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

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

Two concise sentences: the first front-loads the purpose, and the second adds a key constraint about wildcard usage. No filler or 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?

The description covers the core purpose, scope ('accessible'), and a critical query behavior. With an output schema present, return values need not be described. The only minor omission is pagination semantics, but the schema provides defaults and limits, making the description sufficient for a simple 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 only 33%, with only 'query' described. The tool description adds useful detail about the query format (e.g., 'name:ILCU*', trailing wildcards only), partially compensating. However, page_size and page_number are not explained in the description, though their names and schema constraints are fairly self-explanatory.

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

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

The description uses a specific verb ('List') and resource ('accessible Polarion projects'), and adds context that it is the source of project IDs. This clearly distinguishes it from sibling tools that handle attachments, comments, documents, and work items.

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

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

The phrase 'the source of project ids' gives clear context that this tool should be used when project IDs are needed. There are no sibling tools that list projects, so no explicit exclusion or alternative is required.

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

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

Adds beyond readOnlyHint annotation: paginated, server-defined order, empty result meaning, and verification advice. No contradiction.

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

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

Three sentences: purpose, sibling differentiation, behavior; front-loaded and 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?

Complete for a listing tool with output schema: explains pagination, ordering, empty results, and offers troubleshooting hint.

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 67%, description adds critical context for test_case_id format and pagination, but page_size/page_number not detailed.

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 'List a test record's attachments' with specific verb and resource, and distinguishes from siblings list_work_item_attachments and list_document_attachments.

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

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

Explicitly tells when to use (test record attachments) and when to use alternatives, and clarifies the format of test_case_id.

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

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

Annotations provide readOnlyHint=true. Description adds that return is summaries, id matches update_test_records record_id, and defect_id links failure work item. 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?

Five concise sentences, front-loaded with purpose, then guidelines, filter info, and output semantics. 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?

Given output schema exists and 5 parameters, description covers main use case, result filtering, and key output fields. Pagination is implicit via schema defaults, but sufficient.

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

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

Schema coverage 60%. Description adds meaning to result parameter (filter by enum ID, empty for not executed) and explains output fields. Other parameters well-covered by 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?

Description clearly states the tool lists execution records of one test run, one row per test case iteration, distinguishing it from get_test_run (metadata) and update_test_records (which uses the record_id).

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

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

Explicitly directs to use get_test_run for run metadata, states Lucene query is not supported, and explains result filter behavior with empty result for not-yet-executed records.

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 useful behavioral context such as default return type and the fact that author.id does not match on test runs. No contradictions present.

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 very concise with two sentences and a clause. It front-loads the primary purpose and provides essential details without 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 an output schema exists, the description does not need to detail return values. It covers default behavior, template mode, and filtering caveats. Pagination parameters are in the schema, and the description adds relevant context for effective 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 schema covers 60% of parameters with descriptions. The description clarifies the templates parameter and provides a specific usage hint for the query parameter regarding author.name formatting, adding value 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 explicitly states 'List / search test runs in a project', providing a specific verb and resource. It is clearly distinct from sibling tools like list_work_items or get_test_run.

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 when to use the templates parameter ('Returns run instances by default; set templates=True for the reusable template blueprints') and warns about filtering nuances with author.name. It does not explicitly compare to alternatives like get_test_run, but the context makes the tool's purpose clear.

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

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

Beyond the readOnlyHint annotation, the description reveals that the returned id is a token used in body references, that Polarion does not validate references, that order is server-defined, and that results are paginated. This provides significant behavioral context.

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

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

The description is concise with four sentences, each serving a purpose: stating the action, differentiating scope, explaining behavioral details, and providing a prerequisite. No redundant or unnecessary 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 presence of an output schema and the readOnlyHint annotation, the description covers all essential aspects: purpose, scope, pagination behavior, ID semantics, and prerequisite. It is complete for an agent to correctly select and invoke this tool.

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

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

The schema covers 50% of parameters (project_id and work_item_id have descriptions). The description implies pagination with page_size and page_number but does not detail their semantics or constraints, though the schema provides those via defaults and min/max. The description adds moderate value over the schema's missing 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 lists a work item's attachments as a paginated page, differentiating it from document attachments by explicitly directing users to list_document_attachments for documents. It also mentions using list_work_items to discover valid IDs, providing prerequisite 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 explicitly states when to use this tool (work item attachments) and when not to (documents, directing to list_document_attachments). It also provides a prerequisite (use list_work_items to discover valid IDs), giving clear guidance on tool selection.

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

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

Annotations already declare readOnlyHint=true, so safe read is known. Description adds valuable context: comments are unsanitized and should be treated as untrusted when rendering, plus explains thread reconstruction structure. This goes 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?

Two sentences efficiently cover action, thread reconstruction, and a security warning. No wasted words; front-loaded with the core 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?

With output schema present and annotations as readOnlyHint, the description explains thread reconstruction and security, but does not elaborate on pagination behavior beyond 'flat page'. Minor gap but largely complete for a read tool.

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

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

Schema description coverage is 50% (only project_id and work_item_id have descriptions). The description adds no parameter-specific details, leaving page_size and page_number behavior implicit. It does not compensate for the moderate coverage gap.

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

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

Description clearly states it lists a work item's comments as a flat page, with specific detail about thread reconstruction via parent_comment_id and child_comment_ids. This distinguishes it from sibling tools like list_document_comments (documents) and create_work_item_comments (creation).

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

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

The description implies it's for reading comments but provides no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives like create_work_item_comments or update_work_item_comment, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true. Description adds that invalid enum ids cause rejection on write and that an unknown work_item_type silently falls back to '~'. These are useful behavioral details beyond the annotation but not extensive.

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

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

Two concise sentences, no fluff. First sentence states main purpose, second adds usage guidance. Front-loaded and 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 the output schema exists (not shown), the description adequately covers the main use case, prerequisites, and a critical fallback behavior. Could mention pagination or the output format, but overall sufficient for the tool's simplicity.

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

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

Schema description coverage is 60% and the description does not elaborate on individual parameters beyond what the schema already says. The description implies the 'type' parameter but adds no new semantic detail for field_id, project_id, page_size, or page_number.

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 the verb 'List' and the resource 'valid enum option ids for a work item field of a given type'. Differentiates from sibling list_document_enum_options by specificity to work items. Fully unambiguous.

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

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

Explicitly instructs to call before create/update work items because invalid enum ids are rejected. Also warns about the fallback of unknown work_item_type to '~' and recommends verifying the type id first. Provides both context and caveat.

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 aligns with by describing a read operation. The description adds behavioral context: direction impacts returned data (role preservation). No contradictions. Could elaborate on pagination behavior.

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

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

Two sentences, highly concise and front-loaded. No redundant phrasing. 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?

Given read-only annotations, output schema presence, and the tool's listing nature, the description covers the key nuance (direction behavior). Pagination and other parameters are not addressed, but output schema likely covers return structure. Slightly incomplete.

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 40%, only 2 of 5 parameters are described in schema. The description adds no parameter-level details (e.g., syntax, constraints). The direction enum is implied but not explained further. Additional parameter context would improve score.

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 a work item's links, with a specific verb ('List') and resource ('work item's links'). It also notes directionality, distinguishing it from potential siblings like delete or update link tools.

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

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

The description explains when to use forward vs back: forward carries role and suspect; back is a Lucene fallback that drops role. It provides a recovery suggestion ('recover it via forward on the source'). However, it lacks explicit alternatives or 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.

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

Discloses that leading wildcards are rejected, module and body text are not Lucene-indexed, and advises using SQL via get_sql_query_recipes. Annotations already state readOnlyHint=true, consistent.

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 pack essential information, but second sentence is dense with multiple pieces of guidance. Still efficient and front-loaded.

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

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

Given output schema exists, description covers behavior, limitations, and alternatives comprehensively. No gaps apparent.

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?

Adds context beyond schema for query parameter (e.g., module/body text not indexed) but schema already describes query types. Other parameters not elaborated, but schema coverage is 50%.

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 the tool lists/searches work items in a project, distinguishes from get_work_item for single item and mentions read_document_parts as alternative for scope.

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

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

Explicitly says when not to use (e.g., for one known id) and provides guidance on query types (avoid leading wildcards, use get_sql_query_recipes before hand-writing SQL).

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

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

Beyond annotations, the description explains the failure mode for already detached items, confirms item preservation and re-attachability, and notes that headings are detachable. This adds valuable behavioral context.

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

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

Three sentences, front-loaded with purpose, then key behavioral details, no filler. Every sentence is essential.

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 a clear purpose, usage conditions, behavioral insights, and an output schema complementing return values, the description fully covers what an agent needs to use this tool correctly.

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

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

Schema coverage is 100%, and the description does not add extra meaning to parameters beyond what the schema already provides. Dry_run is mentioned but not elaborated.

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 detaches a work item from its document and declares itself as 'the ONLY detach path,' distinguishing it from sibling tools that handle comments, attachments, or other 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?

Explicitly warns of non-idempotence, advises confirming attachment via get_work_item, and mentions the re-attach alternative move_work_item_to_document, providing clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (destructiveHint, openWorldHint), the description discloses critical side effects: the attach path 'atomically sets module and inserts a part,' it 'auto-creates one link to the enclosing heading,' and warns that 'a later same-role create_work_item_links reports created but is NOT persisted.' This goes well beyond the structured annotations and reveals permanent and non-obvious behaviors.

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 dense but every sentence earns its place. It front-loads the purpose, then groups related constraints (positioning, heading rejection, move-vs-copy, link side effect) into concise paragraphs. No filler words; the only minor flaw is the unusual capitalization 'THE attach path,' but it does not hinder comprehension.

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 7 parameters and an output schema, the description covers all critical aspects: positioning rules, heading restrictions, move semantics, link auto-creation, persistence caveat, and data source for part IDs. The output schema handles return values, and annotations cover safety; the description fills the remaining behavioral and contextual gaps comprehensively.

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?

Although the schema covers 100% of parameters, the description adds essential meaning not fully captured in the schema: it explains the exclusivity of previous_part_id/next_part_id in plain language ('At most one'), the behavior when omitting both ('append'), and where to obtain valid part IDs ('read_document_parts'). This makes the parameter semantics much clearer.

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

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

The description opens with 'Move an existing work item into a document at a given position,' which clearly states the action (move), the object (work item), and the destination (document). It explicitly distinguishes from copying ('moved, not copied') and from the sibling 'move_work_item_from_document' by naming the direction. This is a specific verb+resource+target definition.

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 when-to-use and alternatives: 'Headings are rejected — add headings via update_document <hN>' tells users to use another tool for headings. It also states 'Part ids from read_document_parts' as a dependency, and explains the parameter usage: 'At most one of previous_part_id (AFTER) / next_part_id (BEFORE); omit both to append.' These are clear directives on when and how to use the tool.

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

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

Description adds behavioral context beyond the readOnlyHint annotation, such as output format and interleaving behavior. No contradictions 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?

Concise with three sentences, front-loading the main purpose. The middle sentence could be seen as extraneous but overall 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?

Covers main purpose and important warnings, but lacks explanation of pagination parameters and does not mention output structure despite having an output schema.

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

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

Description does not add meaning to parameters beyond the schema. Schema covers 60% but page_size and page_number lack descriptions; the tool description does not clarify them.

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 the tool renders a document as flowing Markdown for reading. Distinguishes from siblings like get_document and list_work_items by specifying different use cases.

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 says it is the way to read a body, warns against using output for update_document, and directs to get_document for round-trip and list_work_items for metadata-only extraction.

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

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

Annotations declare readOnlyHint=true, and the description is consistent, describing a read-only operation. It adds context about the type of output (structural parts, ids, headings, Markdown), but does not elaborate on other behaviors like pagination or potential exceptions. With annotations covering the safety profile, the description provides adequate but not extensive behavioral context.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by clear usage guidance. Every sentence serves a purpose, and there is no redundancy or unnecessary detail.

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

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

Given the presence of an output schema, the description adequately explains the type of data returned (structural parts with ids, headings, Markdown). It also provides context on when to use the tool. While it does not detail pagination or the exact output structure, it is reasonably complete for a listing tool with an output schema.

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

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

Schema description coverage is 60%, with descriptions for space_id, project_id, and document_name, but page_size and page_number lack descriptions. The tool description does not add any parameter-level information to compensate for the missing schema descriptions, leaving ambiguity for the pagination parameters.

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

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

The description clearly states the tool lists a document's structural parts in order, specifies usage for structure (part ids, heading levels, per-part Markdown), and explicitly distinguishes from sibling tools read_document and list_work_items.

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: 'Use for structure...' and 'For plain reading use read_document; for a document's work items use list_work_items.' This clarifies when to use this tool 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?

The description adds value beyond the readOnlyHint annotation by disclosing that the output collapses Polarion anchors and that the body is rendered as Markdown. No contradiction with annotations.

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

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

Two sentences that are front-loaded with the core purpose, followed by critical usage warnings. Every sentence serves a purpose with no 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 the presence of an output schema and the readOnlyHint annotation, the description adequately covers the tool's behavior and return format. The warning about synthesis output completes the behavioral context.

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

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

Schema description coverage is 100% with clear parameter descriptions. The tool description does not add further parameter details, but the schema already suffices. Baseline 3 appropriate.

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

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

The description clearly states 'Read one work item with its body rendered as Markdown.' It identifies the specific verb ('read') and resource ('work item'), and distinguishes from siblings like 'get_work_item' by noting the Markdown rendering.

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 warns against feeding the output to update_work_items and provides a clear alternative for edits: 'get_work_item(include_description_html=True)'. This gives both when-to-use and when-not-to-use guidance.

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

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

Goes well beyond annotations by explaining PATCH semantics ('omitted fields stay unchanged'), raw HTML handling ('empty string rejected, pass '<p></p>''), and rendering_layout_types replacement behavior. Also warns about validation of status/type ids and custom_fields.

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

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

The description is long but efficiently structured: purpose first, then PATCH semantics, HTML guidance, body rules, and layout/workflow constraints. Every sentence carries essential information for safe usage.

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 (13 parameters) and rich schema, the description is comprehensive: it covers edge cases (empty string rejection), alternative tools, and validation rules. It fully prepares an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful cross-parameter constraints (e.g., workflow_action must pair with an attribute) and source guidance (home_page_content_html from get_document). This pushes it above baseline, though some parameters rely solely on 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?

'Update a document's metadata or body' clearly states the action and resource. It distinguishes from siblings by explicitly directing users to other tools for body text and work items: 'For body text or work items use create_work_items + move_work_item_to_document, NOT this tool.'

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

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

Provides explicit 'read BEFORE writing' and detailed when-to-use guidance. It names alternatives for body text and attachments, and specifies constraints like 'workflow_action must pair with at least one attribute' and 'resolve ids via list_document_enum_options'.

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?

Describes key behaviors beyond annotations: 'Resolving the root resolves the whole thread' and 'Idempotent.' Annotations already indicate idempotentHint=true and destructiveHint=false, and the description adds context about thread-level effect. 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?

Three concise sentences with front-loaded purpose. Every sentence adds essential information: action, scope constraint, idempotent note. No 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 6 parameters, full schema coverage, and output schema present, the description covers all critical behavioral points: purpose, usage guidelines, root-only constraint, thread resolution effect, and idempotency. No gaps.

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