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

With no annotations, the description carries full behavioral burden and does so comprehensively. It discloses the append-only safety model, concurrency behavior ('Takes NO version and never conflicts'), response shape ('deliberately NOT the page body'), whitespace-only edge case (400), and write-access requirements (403 for read-only/guest). No contradicting 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 long but every sentence earns its place: purpose, safety, concurrency, formatting, response, error handling, and permissions. It is front-loaded with the core action and then layers necessary behavioral context. No redundant or filler sentences.

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

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

With no annotations and no output schema, the description fully equips an agent to invoke the tool correctly and understand consequences. It covers when to use, key behaviors, return value, error conditions, and auth requirements, making it complete for a mutation tool of this complexity.

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

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

Input schema covers both parameters at 100% with detailed descriptions, so baseline is 3. The description adds extra value for content_markdown by explaining server-side markdown rendering ('same parser create_wiki_page uses') and advising to 'lead with a heading' for findability. It doesn't add much for page_uuid, but the schema already handles that.

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 scope: 'Add markdown to the END of a page that already exists.' It clearly distinguishes itself from the sibling tool create_wiki_page ('the thing create_wiki_page cannot do without leaving you a second page of the same name') and further clarifies its append-only nature ('cannot change or remove a word').

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

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

Explicitly states when to use the tool ('This is the tool for writing what you learned into your own section of a shared page') and contrasts with create_wiki_page. It also provides guidance for corrections ('if you need to correct something you appended, append the correction') and notes that no edit/delete tool exists, which prevents misselection.

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

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

With no annotations provided, the description fully carries the behavioral transparency burden. It discloses that archived tickets leave the board, disappear from list_tickets/search, return 404 from get_ticket, can be restored for 30 days, are auto-destroyed after that, and that 404 is ambiguous (already archived, never existed, or inaccessible). It also explains that no version parameter is accepted and that a retry is safe because there is no conflict. This is exceptional transparency.

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 primary purpose in the first clause, then methodically expands into effects, lifecycle, security, and prereqs for the sibling delete_ticket. While long, every sentence adds distinct value—no fluff or repetition. The structure flows from action → consequences → nuance → guidance, which is optimal for an AI agent needing to make safe decisions.

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 there being no output schema and no annotations, the description is remarkably complete for the tool's complexity. It covers the effect on all relevant ticket operations, the restoration window, the lack of a restore endpoint, the 404 ambiguity, and the prerequisite for delete_ticket. Given the tool's dangerous and nuanced behavior, this fully equips an agent to invoke it correctly and avoid irreversible mistakes.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that only task_uuid is needed and explicitly states there is no 'version' parameter, which is a semantic detail beyond the schema. It also explains 404 semantics related to task_uuid (already archived, never existed, or on an inaccessible board), giving the agent deeper understanding of how the parameter value is interpreted. This far exceeds the minimal schema information.

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

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

The description opens with a specific verb and resource: 'Move a ticket to the workspace trash — the recoverable half of deleting.' This immediately clarifies the action and differentiates it from permanent deletion (delete_ticket). It also conveys the key consequence (leaves board, hidden from list/search, 404 on get_ticket), which distinguishes it from sibling tickets 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 explicitly frames archiving as the 'recoverable half of deleting' and warns that there is no restore tool on this server, making the human-web-app restoration the only path back. It then provides a concrete alternative: 'If you intend to destroy the ticket permanently, call get_ticket FIRST and keep its workspace_uuid: delete_ticket needs one...' This gives 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?

With no annotations provided, the description carries the full behavioral disclosure burden. It discloses markdown parsing, concurrency safety (no version, cannot 409), role permissions (commenter allowed), the 404 for inaccessible tickets, and that posting does not mark the thread read. This is exceptionally transparent.

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 starts with the core action, then flows through markdown behavior, concurrency, permissions, error conditions, and side effects. No fluff exists; the length is justified by the high information content.

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

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

Given no output schema and the tool's role as a write operation, the description covers all necessary context: behavior, error cases (404), authorization limits, concurrency safety, and post-condition (no read status). An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 50%: task_uuid has a description but body does not. The description adds vital semantics for body by explaining Markdown parsing, and explicitly notes the absence of a version parameter, which clarifies the parameter space beyond the schema. This fully compensates for the low schema coverage.

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

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

The opening sentence 'Add a comment to a ticket' uses a specific verb plus resource, making the purpose immediately clear. It further distinguishes itself from update_ticket by explicitly framing it as the right way to report something rather than editing the description out from under someone. No ambiguity exists.

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 contrasts with update_ticket and move_ticket, noting that a commenter role is refused those but allowed this. It identifies clear when-to-use scenarios: concurrent edits and read-only key contexts. This is strong guidance for selecting this tool over alternatives.

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

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

With no annotations, the description fully covers behavioral implications: immediate activation, persistent standing permissions, attribution to the key's user, non-retroactive due-date rules, column.empty firing on already-empty columns, and the run_limit mechanism. It also discloses error responses (403, 402, 400) and the depth cap for self-feeding rules.

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?

Although long, the description is densely packed and every sentence delivers unique, actionable information. It is front-loaded with the core purpose and critical warning, then systematically addresses triggers, conditions, and edge cases without redundancy. The structure uses natural paragraphs to separate concerns.

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 10 parameters, nested objects, no annotations, and no output schema, the description is remarkably complete. It covers permission requirements, failure modes, defaults, timing semantics, per-trigger behavior, and even the exception for create_linked_ticket-only schedule rules. It leaves little ambiguity for an AI agent deciding whether and how to invoke the tool.

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

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

The description adds substantial meaning beyond the schema: explains run_as_user_uuid default, enabled default, run_limit semantics, and the relationship between trigger_config and trigger types. It also elaborates on create_linked_ticket action parameters (title templating, relationship options) that the schema's generic `additionalProperties` does not specify.

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: "Create an automation rule on a board from a trigger, one to twenty actions, and optional conditions." It clearly distinguishes this from sibling tools by contrasting it with "a one-off write like every other tool here" and by singling out the create_linked_ticket action as an exception within the 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 when-to-use and when-not-to-use guidance: warns against speculative creation, explains permission requirements (OWNER/ADMIN), and details conditions under which the rule is refused. It also contrasts with other tools by stating this is a standing grant of permissions, not a one-off write, and names specific scenarios (e.g., schedule-only create_linked_ticket rules) where behavior differs.

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

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

With no annotations, the description fully discloses behavior: template seeding, one-time application, no link back afterwards, manual arrangement without template, and specific error outcomes (404 workspace, 402 limit). This goes far beyond basic 'creates a board'.

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

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

The description is a dense but well-organized paragraph. It front-loads the core action, then details template behavior, then error conditions. Every sentence earns its place with useful, non-redundant information.

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

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

Given no annotations and no output schema, the description covers everything an agent needs to invoke safely: template constraints, irreversibility, error handling, and plan limits. It is sufficiently complete for a creation tool with three 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 coverage is only 33%, but the description compensates for the template parameter by specifying exact allowed values and the 400 error for anything else. It also adds meaning for workspace_uuid by implying it must be an openable workspace. 'name' receives no extra semantic detail, but schema min/max length suffice.

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 a board in a workspace', a specific verb and resource. It distinguishes from sibling tools like list_boards and get_board by covering creation semantics, and clarifies template-driven behavior.

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

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

It clearly implies when to use (creating a board) and provides decision-relevant context: what happens with/without template, and which errors are not worth retrying. It does not explicitly name alternative tools, but the create vs. read distinction is clear from siblings.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It thoroughly explains Markdown parsing in the description field, the behavior of landing in the first column when neither status nor status_uuid is given, position-based ordering, and the idempotency caveat that calling twice creates two tickets. It also reveals the response structure (uuid and version), making the agent aware of post-call implications.

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 provides critical operational detail: parameter selection, Markdown behavior, positioning, response contents, and retry strategy. It is front-loaded with the core action and flows logically without redundant phrases, making it efficient for agent consumption.

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

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

For a create operation with 8 parameters and no output schema, the description fully compensates by explaining the return value (new ticket with uuid and version), the default column behavior, and the idempotency caveat. It also covers failure handling via list_tickets. This is a complete context for an agent to invoke the tool correctly and follow up appropriately.

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% (all 8 parameters have descriptions), so the baseline is 3. However, the description adds valuable semantic depth beyond the schema: it clarifies the mutual exclusivity of status and status_uuid, explains that position is a sort key not an index, and notes that returned positions are decimal strings sent as numbers. This goes above the baseline by providing practical contextual semantics.

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

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

The description opens with 'Create a ticket on a board', which is a specific verb+resource statement that clearly defines the tool's purpose. It also distinguishes the tool from siblings like update_ticket, archive_ticket, and delete_ticket by stating it creates new tickets, not modifying or deleting existing ones.

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 such as choosing between status/status_uuid and handling timeouts by using list_tickets with the title as a fallback. This gives the agent clear direction on when to use this tool and how to recover from ambiguous failures, which is a strong alternative-oriented explanation.

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

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

With no annotations, the description carries the full disclosure burden and succeeds: it reveals create-only semantics, no overwrite/delete, duplicate-page behavior, server-side markdown conversion, image URL requirements, raw HTML literal handling, and permission failures. It even explains the underlying reason (collaborative editor) for not offering overwrite.

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 longer than average but every sentence adds substantive value: usage context, parameter origins, markdown behavior, mutation safety, permission notes, and requirements. It is organized into logical paragraphs and is front-loaded with the core purpose. No filler or redundant phrases.

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

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

The description is exceptionally thorough for purpose, parameters, and safety, but with no output schema it does not mention what the tool returns (e.g., the new page's UUID). This is a minor gap for an agent that may need a handle for subsequent operations. Everything else needed for selection and correct invocation is present.

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

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

Despite only 50% schema description coverage, the description enriches all parameters: wiki_uuid is sourced from list_wikis, parent_page_uuid from get_wiki_tree and nests under an existing page, content_markdown receives markdown-feature details and the optionality of body, and title is confirmed required. This compensates fully for schema gaps.

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 'Write a NEW page into a wiki, with its body as markdown' – a specific verb, resource, and scope. It explicitly distinguishes itself from append_wiki_page by stating 'Do not call this twice to update a page... use append_wiki_page instead.'

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 guidance on when to use: 'This is how an agent puts findings somewhere durable instead of handing them back as chat text.' It also gives explicit exclusions and alternatives: 'to add to a page that already exists, use append_wiki_page,' and warns against calling twice. Permission prerequisites (write access, 403 for read-only/guest) are stated.

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

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

With no annotations, the description carries the full burden and exceeds it. It discloses irreversibility ('Nothing undoes this'), the full scope (comments, attachments), 404 behavior for live tickets, 403 for wrong workspace, and the intentionally undistinguished 404. This is rich behavioural context that will prevent misuse.

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?

Although the description is long, every sentence is purposeful and front-loaded with critical information. The first sentence states the destructive action and scope, then goes on to prerequisites and error semantics. No fluff; the redundancy ('Permanently destroy' / 'Nothing undoes this') reinforces the gravity of the operation without wasting 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 complexity and irreversibility of the operation, the description covers prerequisites (must be archived), sources for parameters, error conditions (403/404 distinctions), and appropriate use cases. With no output schema, it also hints at what happens on success (the ticket is destroyed) and what errors look like. It is complete for an agent to invoke safely.

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 50% (only task_uuid has a description). The description compensates by explaining exactly how to choose workspace_uuid: 'must be the workspace the ticket belongs to — from get_ticket before it was archived, or get_board for the board it was on.' It also explains error cases that depend on workspace selection. This adds significant meaning beyond the raw 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 'Permanently destroy a ticket that is ALREADY in the trash, along with its comments and attachments.' This is a specific verb+resource+condition that distinguishes it from siblings like archive_ticket. It further clarifies that live tickets return 404, so the purpose is unambiguous.

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

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

Explicitly tells when to use: 'It is the second step and never the first: archive_ticket, then this.' It also provides strong guidance on what to keep vs. destroy: 'Keep this for tickets that should never have existed... Anything a person might want back can simply be left archived.' This fully differentiates from archive_ticket and other alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It fully delivers: the attachment moves to workspace trash for 30 days, storage quota is freed immediately, there is no restore tool, and all error cases (already deleted, still uploading, or inaccessible ticket) return the same 404. This is exceptionally transparent and goes far beyond a generic 'delete' statement.

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 first sentence states the core action immediately. Every subsequent sentence earns its place by adding vital operational details: the 30-day trash window, the lack of a restore tool, the immediate quota effect, and the unified 404 behavior. It is thorough without being bloated, and the progression from action to consequences is logical.

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

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

Given that there is no output schema and no annotations, the description is remarkably complete. It explains what happens to the attachment, how long it persists, what the agent cannot do afterward, the storage-quota side effect, and the exact error semantics. This is more than sufficient for an agent to safely reason about invoking the tool.

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

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

Schema description coverage is only 50%: task_uuid has a descriptive source hint, but attachment_uuid has no description. The tool description does not compensate by explaining what attachment_uuid is or how to obtain it. The phrase 'Remove a file from a ticket' only weakly implies the attachment identifier's role. Since half the parameters are undocumented and the description adds no specific parameter guidance, the semantics are under-served.

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 starts with a specific verb and resource: "Remove a file from a ticket." It clearly distinguishes this from sibling tools like delete_ticket or archive_ticket by specifying that it operates on attachments and shares the trash mechanism with archive_ticket. The purpose is unambiguous and instantly recognizable.

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

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

The description gives clear usage context: removing an attachment is one-way-but-recoverable, and there is no restore tool available to the agent, so the agent should treat it as final. It does not explicitly name alternative tools or state when not to use it, but the context strongly implies the appropriate scenarios. The finality warning serves as practical guidance for deciding when to invoke 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?

Without annotations, the description discloses key behaviors: the UUID format (bare vs expanded), the payload size (~90% tickets), and the semantics of the returned data for interop with create_ticket, move_ticket, and update_ticket. This goes beyond a simple read operation.

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

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

Four sentences, each adding distinct value: resource definition, UUID semantics, cross-tool comparison, and performance guidance. 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?

Despite no output schema or annotations, the description covers the return structure, UUID resolution, payload size, and usage alternatives, making it sufficient for correct invocation.

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

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

The description adds context beyond the schema by explaining why include_tasks matters (response size) and what the returned UUIDs are used for. It complements the schema's descriptions of board_uuid and include_tasks, but the schema already covers parameter basics.

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 by defining the resource ('A board with its status columns, labels, members and tickets') and explains the significance of the returned status and label UUIDs, distinguishing it from sibling tools like list_tickets and get_ticket by showing how the data format differs.

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 names alternatives: list_tickets and get_ticket return expanded labels, and list_tickets is recommended for ticket listing since it supports limit and status. It also advises setting include_tasks=false when only UUIDs are needed.

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

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

With no annotations, the description carries the full burden. It discloses the expanded label format and why (no board dictionary in this response), the 409/version interaction, and the ambiguous 404 ('the same 404 as one that never existed'). This is rich behavioral context beyond a simple 'get a ticket' statement, exactly what an agent needs to interpret responses correctly.

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 adds value: response contents, usage guidance, label format explanation, and error semantics. It is front-loaded with the core meaning and structured logically, making it efficient despite its 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?

There is no output schema, so the description must cover return values and edge cases. It explains the essential parts of the response (version, expanded labels) and clarifies error semantics (409 retry, ambiguous 404). Given the tool's simplicity (one parameter) and the thorough description, the agent has everything needed to invoke it correctly.

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

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

The input schema already provides 100% description coverage for the only parameter, `task_uuid`, including its source. The description adds no additional parameter-specific semantics, so the baseline score of 3 applies.

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

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

The description opens with 'One ticket in full: its fields, its `subtasks`, its expanded `labels` objects, and the `version` every write needs.' This is a specific verb+resource with a clear scope, and it implicitly distinguishes get_ticket from siblings like list_tickets or get_ticket_comments by enumerating what is included in the full ticket representation.

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 'Read this before you write' and explains that update_ticket, move_ticket, and archive_ticket all require the version field and will respond with 409 if it is stale. It further details the retry behavior and clarifies the difference between get_ticket's expanded labels and get_board's bare `label_uuids`, leaving no doubt about when to use this tool.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses content-type-dependent returns, server-side file writing, path/size return instead of content, the 4 MB context-cost rule, and the unified 404 for missing/uploading/deleted/permission-denied attachments. This is excellent disclosure beyond anything structural annotations could provide.

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

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

The description is long but front-loaded with the core action and every clause provides necessary operational detail about file-type behavior and save_to. It is dense rather than wasteful; a bit of tightening would make it more concise, but the current length is justified by the tool's 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?

For a complex tool with no annotations and no output schema, the description is complete: it covers invocation prerequisite, return behavior for all file categories, save_to usage and location, size thresholds, and error semantics. An agent has enough information to invoke the tool correctly and predict outcomes.

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

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

Schema description coverage is 67% with attachment_uuid lacking a description. The tool description compensates by stating the attachment_uuid comes from list_ticket_attachments and by adding deep semantics for save_to (server machine, path/size return, overwrite behavior). It adds clear meaning beyond the schema's bare field definitions.

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

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

The description opens with 'Fetch one attachment's CONTENT' and clarifies that the result depends on the file type, tying the attachment uuid to list_ticket_attachments. This clearly distinguishes the tool from sibling list/upload/delete attachment tools and states its exact resource and action.

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

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

It explicitly instructs users to first find the uuid via list_ticket_attachments and gives conditional guidance: text/CSV inline, image blocks, and save_to for binary/large files with a 4 MB threshold. It lacks explicit 'when not to use' exclusions, but the context for using the tool and its save_to parameter is strong.

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?

Without annotations, the description carries the full burden. It discloses no paging/cursor behavior, no side effects (doesn't mark read), and consistent 404 for inaccessible/nonexistent tickets. This is rich, precise behavioral context 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 concise yet complete. Each sentence adds value: purpose, structure, pagination, side effects, error behavior. No filler or repetition. Front-loaded with the main output description.

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

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

With no output schema, the description explains the return format (two lists), ordering, pagination, side effects, and error semantics. It covers all critical aspects an agent needs to understand the tool's behavior. Very complete for a single-parameter read tool.

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

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

Schema description coverage is 0%, and the description does not compensate by adding meaning to the sole parameter task_uuid. It only vaguely references 'a ticket you cannot open', but never describes the parameter's role or format. With one obvious parameter, it's not catastrophic, but it fails the coverage requirement.

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 what the tool does: returns the discussion on a ticket as two lists (comments and events). It distinguishes from siblings like get_ticket (ticket details) and list_ticket_attachments (attachments) by explicitly mentioning the content and structure.

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

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

The description implies usage for reading and following a ticket thread, mentioning 'polling this to follow a ticket' and noting lack of side effects. It does not explicitly name alternatives, but the context is clear enough for an agent to select it over write-oriented siblings like comment_on_ticket.

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?

Although no annotations are provided, the description discloses key behaviors: the return includes content and attachments, a 404 does not distinguish between nonexistent pages and access restrictions, and the server cannot edit/delete pages. This is thorough transparency for a read operation.

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

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

The description is 110 words across four sentences, but every sentence adds value: purpose, identifier acquisition, 404 semantics, and server limitations. It is front-loaded with the primary purpose and efficiently packed with actionable context.

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

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

For a tool with one parameter, no annotations, and no output schema, the description covers purpose, parameter source and caveats, error behavior, and relevant server capabilities. It is remarkably complete, leaving no critical operational question unanswered.

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

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

With 0% schema coverage, the description compensates by explaining that page_uuid is a page identifier obtained from get_wiki_tree or search_wiki, and crucially that a page uuid is not a wiki uuid. This adds significant meaning beyond the raw UUID format in the schema.

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

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

The description states 'One wiki page in full, with its content and any attachments it references,' clearly identifying the tool as fetching a single wiki page with its full content and attachments. It distinguishes from siblings like get_wiki_tree and get_wiki_page_version by indicating it provides the full current page rather than structure or versions.

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

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

The description explicitly tells the agent where to obtain the required page_uuid: 'Get page_uuid from get_wiki_tree or from a search_wiki hit.' It warns against confusing page uuids with wiki uuids, clarifies the 404 behavior, and advises using append to correct content when editing is impossible. This provides clear when-to-use and caveats.

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

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

With no annotations provided, the description fully discloses behavior: it states the operation is a READ, the page is not changed and its version does not move. It also explains error semantics (404 for invalid version or inaccessible page) and explicitly notes there is no restore capability.

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 core purpose, then flows naturally into usage, parameter semantics, error behavior, and a warning. Every sentence contributes value without redundancy, making it appropriately sized for the tool's 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?

Although there is no output schema, the description covers the return content (title, content, who saved it). It also addresses edge cases (never-saved version, inaccessible page) and provides critical guidance about not restoring old versions, making the description fully complete for this read-only 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 describes only one of two parameters (version). The description adds significant semantics for version: counting from 1, incrementing per save, and referring to get_wiki_page for the current number. However, page_uuid is not elaborated beyond the schema's format/pattern, leaving a small gap.

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

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

The description clearly states the tool's purpose: retrieving what a wiki page said at an earlier version, including title, content, and author. It explicitly distinguishes itself from sibling tools by referencing get_wiki_page for the current version and noting there is no restore 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 when-to-use guidance: 'This is how you recover something that was overwritten' and 'Reach for it the moment you find that a page no longer says what you put there.' It contrasts with get_wiki_page and warns against attempting a restore, steering users toward read + append.

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

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

With no annotations, the description carries the transparency burden. It discloses the return contents (titles, uuids, nesting, no page content), the 404 behavior for unopenable/nonexistent wikis, and the token cost of large wikis. It does not explicitly state read-only or describe the output tree structure in detail, but it covers key behavioral traits sufficiently.

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, each earn its place: it states the core output, positions against alternatives, explains the 404 case, and gives performance advice. Front-loaded and free of redundant filler.

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

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

Given the tool's complexity and lack of output schema, the description is remarkably complete. It covers what the tree contains, when to use it over alternatives, how to follow up with get_wiki_page, error semantics for inaccessible wikis, and scaling guidance for large wikis. An agent can confidently select and invoke this tool based on this description alone.

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

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

Schema coverage is 67%, with depth and parent_page_uuid already having descriptions. The description adds meaning by recommending these parameters for narrowing large trees ('narrow it with parent_page_uuid and depth rather than reading all of it'). wiki_uuid lacks a description but is inherently clear from its name and format.

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 exactly what the tool does: 'Every page in a wiki as a tree — titles, uuids and nesting — without any page content.' It identifies the specific verb (get), resource (wiki tree), and output scope clearly. It also distinguishes itself from siblings by directly referencing search_wiki and get_wiki_page, making its unique role explicit.

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

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

The description provides explicit guidance: 'This is the cheap way to find a page uuid when you know roughly where it sits; search_wiki is the way when you know roughly what it says.' It also advises when to use depth and parent_page_uuid to avoid reading large trees, which is practical usage direction.

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

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

With no annotations, the description carries the full burden and does well: it explains direction is from task_uuid's perspective, defines 'blocks' vs 'blocked_by', and discloses that ticket reads afterwards include blocked_by, blocks, and is_blocked. It doesn't cover edge cases like idempotency or errors, but the key behavioral traits are communicated.

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 direction rule, then read-effect. Every sentence earns its place with no redundancy. Excellent structure.

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 no annotations and no output schema, the description provides the essential context: purpose, directionality, and the impact on subsequent ticket reads. It could briefly mention removal via unlink_tickets, but that's available in the schema, so the overall coverage is strong.

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

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

Schema description coverage is 100% and every parameter already has a detailed explanation. The description reinforces the direction semantics but doesn't add new parameter meaning beyond what the schema provides, matching the baseline.

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

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

The description opens with a specific verb+resource: 'Record that one ticket must be finished before another can start.' This clearly defines the tool's purpose and inherently distinguishes it from other ticket operations like create/update/delete, while also conveying the core directionality concept.

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 tool ('this is how you work out what order to do things in') and notes the downstream effect on ticket reads, which gives practical context. However, it does not explicitly mention alternatives or when not to use it; for example, unlink_tickets only appears in the schema, not the description.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It explains the live nature of enabled rules (fire within seconds, act as run_as_user_uuid), the per-board limit, the self-disabling after loops, the read access being wider than creation, and the 404 behavior for inaccessible boards. This is rich, non-obvious 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 long but every sentence contributes: it covers return fields, live behavior, usage timing, an API alternative, an edge case (self-disabling loop), and error semantics. It is front-loaded with the core purpose and then adds structured, relevant details without fluff.

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 single parameter, no output schema, and no annotations, the description is remarkably complete. It explains what is returned (fields), how the data behaves, what access is needed, the limitation of no run-history tool, and error semantics. An agent can confidently select and invoke this tool without further documentation.

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 has only board_uuid with 0% description coverage, so the description must compensate. It does not restate the parameter but provides meaningful context: board_uuid refers to the board being read, board access is sufficient, and inaccessible/nonexistent boards yield the same 404. This adds behavioral meaning beyond the schema's format/pattern constraints.

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 immediately identifies the resource as 'automation rules on a board' and enumerates the exact fields included (trigger, conditions, actions, enabled, run_as_user_uuid, version), making it clear this is a read-only listing distinct from creating automations. However, the opening is a noun phrase rather than an explicit verb phrase like 'Lists all automation rules for a board,' so it relies somewhat on the tool name to convey the action.

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

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

The description gives explicit usage timing: 'Read this before creating a rule on a board you did not set up.' It also points out a sibling alternative (creating automations) and notes the lack of a run-history tool, directing users to the API. The wide read access vs. creation permission is explicitly contrasted, providing clear when-to-use guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals that results are access-filtered by the API key, that archived boards are excluded, and that only board uuids/names are returned (status uuids are elsewhere). This is meaningful context beyond a generic list operation, though it does not mention ordering, pagination, or read-only semantics explicitly.

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

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

Three sentences, each with a distinct purpose: what the tool does, access/archive behavior, and what uuids are or aren't available. No filler, front-loaded with the core function.

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

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

For a simple list tool with one parameter and no output schema, the description covers the result content (board uuids and names), access filtering, archive exclusion, and the relationship to downstream tools. It doesn't describe error responses or pagination, but those are less critical here; the given context is sufficient for an agent to decide when to call it.

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

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

There is only one parameter, workspace_uuid, and the schema already provides format and pattern validation. The description implicitly references the workspace in its first sentence, but does not explicitly explain that workspace_uuid is the identifier of the workspace whose boards are listed. With 0% schema description coverage, the description adds minimal extra meaning beyond the parameter name.

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 names the resource (boards) and the action (list), and specifies the output (uuids and names). It distinguishes itself from siblings by clarifying that this is the step from workspace to readable content, and by noting that status uuids are not provided here but via get_board.

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 workflow guidance: it positions list_boards as the bridge from workspace to board-level tools, states which downstream tools (get_board, list_tickets) will need the board uuid, and directs the user to get_board for status uuids. It also explains the consequence of a short list (limited access) and that archived boards are omitted, which frames when to expect incomplete results.

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?

Despite no annotations, the description discloses important behavioral traits: returns metadata never bytes, only finished uploads are listed (in-flight/deleted appear absent), and lists newest first. It also notes that the reply carries metadata, not the file content, which is a key limitation 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 information-dense yet concise. Each sentence earns its place: it states the output fields and ordering, contrasts with get_ticket_attachment, mentions the attachment_total signal, and clarifies handling of in-flight/deleted files. It's well-structured, starting with the core function.

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

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

With no output schema, the description fully describes the return format (metadata fields), ordering, and limitations. It also provides surrounding context (get_ticket for count, get_ticket_attachment for content) that makes the tool's role in the API complete. Nothing critical is missing.

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

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

The schema has only task_uuid with no description (0% coverage). The description compensates by framing the tool as listing 'files on a ticket', making it clear that task_uuid is the ticket/task identifier. While it doesn't explicitly define the parameter, the context and tool name make its meaning unambiguous.

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 what the tool does: lists a ticket's files with metadata (name, content type, size, uuid) ordered newest first. It distinguishes from get_ticket_attachment (which fetches the bytes) and explicitly says 'Nothing else here reads a ticket's files', making it unique among siblings.

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 context: use this to inspect attachment metadata, e.g., checking if a spec is a PDF. It references get_ticket for the attachment_total count to decide if calling is worthwhile, and get_ticket_attachment for fetching bytes, effectively giving alternatives and guidance on when to use each.

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

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

With no annotations, the description carries the full burden, and it delivers. It discloses that `next_cursor` appears only on a full page and that a short page means the walk is over. It explains the UUID-resolution pitfall in `q` (that a UUID returns only that ticket, never fallback text search), and it explicitly states archived tickets are never returned. It also reveals `removed_task_uuids` as the only way to notice deletions by polling.

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

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

The description is well front-loaded with purpose and then systematically covers paging, incremental refresh, and filters. However, it is quite lengthy, and the historical aside inside the `q` explanation ('That sentence used to read...') adds color but is not strictly necessary. Given the complexity and 8 parameters, the length is mostly justified, but a few sentences could be trimmed without losing essential 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?

The description is remarkably complete for a list tool with no output schema. It explains the return shape where relevant (paging cursor, removed_task_uuids, include_descriptions effect), covers all major behaviors (board order, filtering, paging, incremental updates, archived exclusion), and addresses edge cases like UUID resolution and cursor incompatibility with `q`. Nothing important is left unexplained.

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

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

The schema already covers all parameters at 100%, but the description adds substantial meaning beyond names and types. For `q` it explains the ranked behavior, the no-mid-word-substring restriction, and the special UUID resolution semantics. For `cursor` it warns that it is board- and filter-specific and that a mismatched cursor is a 400. For `updated_since` it recommends passing the previous `server_time` to avoid clock drift. The `include_descriptions` parameter is given quantitative context (78% of a column listing).

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 clear, specific statement: 'Tickets on a board, in board order, optionally filtered by status or by free text.' It names the exact resource (tickets on a board), the operation (listing), and the scoping options. It also distinguishes itself from a sibling tool by noting 'get_board returns the same tickets but takes neither `limit` nor a cursor.'

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

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

It explicitly states when to use this tool ('This is what to read a column or walk a whole board with') and contrasts with get_board. It also gives guidance on paging (stop when next_cursor is absent), on using updated_since for following a board, and on include_descriptions=false to save payload while deferring to get_ticket for full details. This is textbook usage guidance.

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

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

With no annotations, the description fully discloses important behaviors: guest keys see nothing (empty list is not proof of no wiki), archiving removes wikis from the list, and the `archived: true` flag is the only way to get archived wiki UUIDs. This goes well beyond a basic description and proactively warns about hidden edge cases.

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

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

The description is front-loaded with the primary purpose and each additional sentence provides necessary context (guest behavior, archiving, restore). It is slightly long but every sentence earns its place, with 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?

For a simple listing tool with two parameters and no output schema, the description covers all essential aspects: entry-point workflow, guest edge case, archived-wiki behavior, and relationship to `restore_wiki`. It is a self-contained guide for correct invocation.

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

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

Schema coverage is 50% (only `archived` has a description). The description adds meaning for `workspace_uuid` (required, start from `list_workspaces`) and enriches the `archived` behavior (mutually exclusive lists, only way to find archived UUIDs). This compensates for the missing schema description effectively.

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

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

Clearly states it lists wikis in a workspace with their UUIDs, and distinguishes itself as the only source of `wiki_uuid`, making it the entry point for all other wiki tools. This is a specific verb+resource with explicit sibling differentiation.

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

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

Provides clear context: `workspace_uuid` is required and can be obtained from `list_workspaces`. It also explains the `archived` parameter and how it relates to `restore_wiki`. However, it does not explicitly mention when to use this tool over specific alternatives, though the entry-point role is strongly implied.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It clearly states that via an API key the result is always exactly one workspace, that archived workspaces are excluded, and that each entry includes billing_status to differentiate read-only from writable workspaces. These are meaningful behavioral nuances that go beyond a simple 'list' definition.

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 yet information-dense. Every sentence adds value: the result contents, the workflow context, the single-entry expectation, archived exclusion, and billing_status significance. No wasted words or repetition of schema information.

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

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

For a zero-parameter tool with no output schema, the description provides a remarkably complete picture: what data is returned, how to interpret unusual results, what is not included, and how to use a key field for operational decisions. It fully equips an agent to invoke and interpret results correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description appropriately focuses on output semantics rather than parameters, and no parameter explanation is needed.

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

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

The description clearly states the tool lists the workspaces the API key can act in, including uuids, names, and the role held in each. It distinguishes itself from siblings by explicitly directing users to start here when they lack a workspace uuid and then proceed to list_boards, making the purpose and place in the workflow 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: 'Start here when you do not already have a workspace uuid, then go to list_boards.' It also explains the normal single-entry result to prevent misinterpretation, and highlights billing_status to detect read-only workspaces before attempting writes, which is valuable contextual 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?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels: it details 400 errors for neither/both parameters, invalid column names, and wrong board UUIDs; explains 409 stale version handling with the current version included; and describes the append-to-bottom position behavior. This is rich operational detail that goes far beyond basic expectations.

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 well-structured, starting with the core purpose and then systematically covering parameters, error cases, and positioning behavior. While every sentence provides value, the paragraph is long and could be broken into bullet points for easier scanning; slight verbosity in error message quotes earns a 4 rather than 5.

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 (concurrency versioning, positional semantics, multiple error modes) and the lack of annotations or output schema, the description is nearly complete. It covers inputs, side effects, and error handling thoroughly, but does not specify the nature of the success response (e.g., updated ticket or confirmation), which would be helpful in the absence of 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?

The schema already covers 80% of parameters with descriptions, but the description adds crucial semantics: the mutual exclusivity of status and status_uuid, case-insensitive and trimmed matching, and the version requirement from get_ticket. These details are not in the schema and are essential for correct invocation.

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 a ticket to another column,' which is a specific verb+resource statement that clearly distinguishes this tool from update_ticket (which likely modifies other fields). It further clarifies the domain by referencing get_board for column identifiers and get_ticket for versioning, solidifying its unique role.

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

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

The description provides clear usage context: it explains the either/or requirement for status vs status_uuid, where to obtain these values (get_board), and how to handle versioning with get_ticket. It does not explicitly name alternative tools for exclusions, but the context is sufficiently clear for an agent to know when to invoke it.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the operation affects the wiki and all pages, may republish pages to the internet, that archived wikis are invisible elsewhere, that non-archived/nonexistent/wrong-workspace Uuids are indistinguishable, and that there is intentionally no archive tool. These behaviors are not in the schema or annotations.

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

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

Every sentence in the description earns its place: purpose, parameter source, 404 ambiguity, and a note about missing archive functionality. The text is front-loaded with the core action, and the additional details are concise and relevant, not padded.

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

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

For a single-parameter tool with no output schema, the description covers the purpose, the source of the parameter, expected effects, error semantics, and a limitation. It is fully adequate for an agent to select and invoke the tool correctly without additional 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?

The schema only provides the type/format of wiki_uuid, but the description adds critical semantic meaning: it explains that the uuid must be from list_wikis with archived: true and that this is the only context where such a uuid is visible. This compensates fully for the 0% schema description 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 opens with a specific verb and resource: 'Undo an archive: brings a wiki, and every page under it, back into list_wikis and back onto the internet if any of its pages were published.' This clearly states the action, the target, and the effect, and it differentiates the tool from siblings like archive_ticket or list_wikis.

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

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

It explicitly tells the user where to obtain the required parameter: 'wiki_uuid comes from list_wikis with archived: true — that is the only place one is visible at all.' It also provides an exclusion by noting that a wiki not archived, permission-denied, or nonexistent all return 404. This is clear when-to-use guidance with an alternative (list_wikis) and a caution.

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

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

With no annotations, the description carries full burden. It discloses rich behavioral details: the four result lists, that boards is easy to miss, matching rules (whole words and prefixes, 3-char minimum), return format (short lines, not full content), and the control characters \x01/\x02 in excerpts. This goes well beyond a basic search description.

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 every sentence serves a purpose: core action, usage context, result structure, matching caveat, return granularity, and excerpt format. It is front-loaded with the main purpose and follows with essential details. No filler.

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

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

Given the lack of an output schema, the description thoroughly explains the four return lists, their semantics (comments are ticket references, no duplicates), and the pitfall with boards. It also covers matching constraints and follow-up actions. This is complete for a complex search 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% (only 'limit' is described). The description adds meaningful context about the query behavior (matching, minimum length) which relates to 'q', but it does not explicitly map each parameter by name. It also doesn't describe workspace_uuid beyond the search scope. Some compensation, but not complete.

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 scope: 'Search tickets, wiki pages AND ticket comments across a whole workspace in one call, ranked by relevance with a highlighted excerpt.' It clearly distinguishes from the sibling list_tickets by noting that list_tickets requires a board_uuid whereas this tool does not.

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 advises using this tool when the board or wiki location is unknown, and contrasts with list_tickets which requires a board_uuid. It also recommends follow-up tools (get_ticket, get_ticket_comments, get_wiki_page) for full content, but does not explicitly state when-not-to-use scenarios beyond the implicit contrast.

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

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

With no annotations, the description takes full responsibility for behavioral disclosure. It reveals non-obvious behaviors: title matches outrank body matches, single-word prefix matching, multi-word query syntax, control-character delimiters in excerpts, and a 404 for missing/inaccessible wikis. This goes far beyond typical descriptions and equips the agent with critical operational knowledge.

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 in this description earns its place. It opens with the primary purpose, then details matching behavior, excerpt formatting, source of the wiki UUID, error behavior, and an alternative tool reference. There is no fluff or repetition; it's information-dense yet still scannable.

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

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

Given the tool's complexity, lack of annotations, and lack of output schema, the description is remarkably complete. It covers purpose, query syntax, response formatting, error semantics, parameter provenance, and the sibling alternative. The only nominal gap is a detailed return structure, but the description adequately covers the highlighted excerpt behavior.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It explains `wiki_uuid` as an identifier from `list_wikis` and gives a rich explanation of `q` semantics: prefix matching for single words, quoted phrases, excluded terms, and OR. This adds substantial meaning beyond the bare schema constraints.

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: 'Full-text search inside ONE wiki, returning matching pages with a highlighted excerpt.' It clearly distinguishes itself from the sibling `search` tool by scoping to a single wiki and later naming the alternative. This is a model of purpose clarity.

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

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

The description gives explicit usage context: when to search within a single wiki, and directly states an alternative: 'To search tickets and wikis together across a whole workspace, use `search` instead.' It also mentions that `wiki_uuid` comes from `list_wikis`, providing a prerequisite chain. This clearly guides 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?

With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals that the tool removes all link kinds (dependency, related-to, duplicate-of), not just the dependency created by link_tickets; that it is idempotent (no error if never linked); and that unreadable or nonexistent uuids yield a 404. These are critical behavioral traits.

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 each sentence earns its place. It starts with the main action, then explains link-type behavior, idempotency, and error conditions, using concrete terms like 'dependency' and 'related-to'. No filler or repetition exists.

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 subtle behaviors (multiple link types, idempotency, 404 conditions) and the absence of annotations or an output schema, the description covers all aspects needed for correct invocation. It also points to `blocked_by` and `blocks` for existence checks, completing the contextual picture.

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

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

The schema covers only task_uuid with a description (50% coverage). The description adds crucial meaning: 'Order does not matter — it finds the pair from either end,' clarifying that the two parameters are symmetric. It doesn't explicitly describe other_task_uuid's provenance, but the order-independence note compensates for the partial schema coverage.

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

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

The description opens with 'Remove the link between two tickets', a clear verb+resource statement. It further explains that order does not matter and that it removes ALL link types, distinguishing it from sibling link_tickets. This provides a specific and unambiguous purpose.

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

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

The description explicitly states when to use the tool: to remove a link regardless of which ticket is recorded as the blocker. It also gives a clear exclusion: 'this cannot be used to test whether a link exists; read `blocked_by` and `blocks` on the ticket for that,' pointing to alternative approaches.

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

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

With no annotations, the description carries the full burden and excels: it discloses the 409 conflict behavior, whole-set replacement for labels/assignees/custom_fields, silent dropping of unknown custom field UUIDs, and the need to read back custom_fields to confirm writes. This is exemplary behavioral disclosure.

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

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

The description is a dense paragraph with no wasted words, but it covers a lot of ground. It is appropriately sized for a tool with 12 parameters and many gotchas, though it could benefit from bullet points for readability. Still, 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 complexity (12 params, nested objects, no output schema), the description is remarkably complete. It explains concurrency, replacement semantics, silent failures, and even mentions that the reply carries stored custom_fields. It leaves few unanswered behavioral questions.

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 substantial value by highlighting the most critical param behaviors: version must come from get_ticket, description replaces rather than appends, and the replace semantics for label_uuids, assignee_uuids, and custom_fields. It goes well beyond the baseline by summarizing and reinforcing the schema details.

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 'Change a ticket,' a specific verb and resource. It clearly distinguishes from sibling tools like create_ticket, move_ticket, and comment_on_ticket by implication, and the detailed context about versioning and replace semantics makes the tool's 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 clear context for how to use the tool (version handling, replace semantics) but does not explicitly state when to use it vs alternatives. The schema's status parameter mentions 'move_ticket is the tool for a move alone,' but the description itself lacks that exclusionary 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?

With no annotations provided, the description carries the full burden and does an excellent job. It discloses write semantics, server-side MIME type validation, byte-content matching enforcement, a 25 MB limit, 402 quota behavior with no retry expectation, and the context cost of file_path.

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 every sentence earns its place by adding constraints, usage preferences, or error semantics. It is front-loaded with the purpose and structured logically from usage modes to validation rules to failure cases.

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 use cases, constraints, and failure modes thoroughly, but it does not state what the tool returns on success (no output schema exists). It also omits mention of the content_type parameter in prose, but the schema covers it. These are minor omissions in an otherwise complete 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%, but the description adds significant meaning: the distinction between file_path and text, the requirement that text needs filename, filename's default from file_path, and how the extension determines content type. It does not mention the content_type override parameter in prose, but the schema already describes it, so this is only a minor gap.

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

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

The description uses specific language ('Attach a file to a ticket') and clarifies the tool's role as putting evidence on a ticket. It clearly distinguishes this from sibling tools like list_ticket_attachments, get_ticket_attachment, and delete_ticket_attachment.

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

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

The description gives explicit when-to-use guidance for each parameter mode: file_path for existing files on disk with a preference expressed ('costs no context, so prefer it'), and text for agent-written content needing filename. It also notes the 403 for read-only roles, implying when not 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.