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

Annotations only provide destructiveHint=false, so description carries most behavioral burden. It discloses the side effect (upload + chat post), the two input modes, and the optional comment. It does not mention confirmation_required behavior (though the confirm param description hints at it), auth requirements, or what happens on failure/duplicates.

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

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

Two sentences: first states the action and mechanism, second gives the invocation modes. No filler, no repetition of schema descriptions. Front-loaded with the primary purpose.

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

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

Complete for a single-file attachment tool: mechanism, input modes, and optional comment are all covered. The main gap is that the confirmation flow is only implied via the confirm parameter, not described in the tool description itself; however, with schema describing confirm and annotations marking non-destructive, an agent can proceed confidently.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds the key semantic detail that file_path OR content_base64+filename are the two acceptable input combinations, which helps the agent choose the right mode. It doesn't elaborate on the confirm logic beyond what the schema description already says.

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

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

Description starts with a clear verb+object: 'Attach a file to a task', then details the mechanism (upload to YouGile, post into task chat as attachment) and the optional comment. This differentiates it from siblings like yougile_task_chat (chat interaction) and yougile_files (file listing) by focusing on the attach 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 explains how to use it ('Pass file_path, or content_base64 with filename'), giving two explicit invocation modes. It doesn't explicitly say when not to use it or name alternatives, but the chat-attachment mechanism and the dual input options provide clear practical guidance. The confirm parameter description also adds when-to-set guidance.

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

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

Annotations only provide openWorldHint, so the description carries the burden for safety/behavior. It discloses access levels and mentions 'soft-delete' in the header, which hints at destructiveness, but it does not explain side effects, reversibility, or confirmation flow, and the header's rename/move/soft-delete are not reflected in the operation enum. No contradiction with annotations.

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

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

The description is compact and front-loaded with the operation list, and the bullet format is scannable. It includes some redundancy (Russian translations and the header's update/rename/move/soft-delete vs the 'update' operation line) that slightly muddies the structure, but overall it is efficient.

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

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

For a tool with no output schema and a generic params object, the description gives the operation surface and access rules but omits return format, error behavior, and explicit parameter details (delegated to yougile_help). It is adequate as a high-level map but not self-sufficient for correct invocation without the help 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 documents operation/params/confirm generically, with 67% coverage. The description adds one concrete parameter hint ('list (by projectId)') and directs the agent to yougile_help for per-operation parameters, but it does not otherwise describe create/update fields, so the agent still depends on an external help call.

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

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

The description names the resource (boards) and the operations (list, get, create, update) plus the scoping hint 'list (by projectId)'. It is clear that this tool manages Yougile boards, though it does not explicitly contrast itself with sibling tools like yougile_columns or yougile_projects.

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

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

It gives access levels per operation ([read] vs [admin]) and tells the agent to call yougile_help for parameters, which is some guidance. However, it does not state when to choose boards over related siblings or explicitly list exclusions/alternatives.

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

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

The description discloses access levels (read/write) for each operation, which is valuable behavioral context beyond the minimal openWorldHint annotation. It also notes that parameters require a help call, hinting at complexity. However, it doesn't disclose side effects, rate limits, or the fact that 'reactions' and 'delete' are mentioned but not present as operations, which could mislead. Given the sparse annotation, the description partially carries the burden but isn't comprehensive.

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

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

The description is well-structured with a front-loaded purpose, followed by a concise list of operations with access levels. It avoids fluff and includes a useful pointer to the help tool. The Russian translations add length but serve as clarifications. It is efficient and easy to scan.

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 nine operations and no output schema, the description covers operation names and access levels but omits parameter details, return values, and error behavior. It also introduces 'reactions' and 'delete' that are not in the operation enum, creating ambiguity. The reliance on yougile_help may be acceptable, but the description could be more complete given the tool's breadth.

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 provides descriptions for params and confirm, with 67% coverage. The description adds no meaning about what each operation's parameters should contain; it only defers to yougile_help. For a multi-operation tool with varying parameter shapes, this is insufficient. The description does not compensate for the moderate schema coverage, so the agent lacks guidance on constructing correct params without extra help calls.

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

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

The description clearly states the tool handles chat messages for tasks (with chatId = task id) and group chats, listing operations like history, send, edit/delete, and reactions. It names the resource and actions, distinguishing it from sibling tools like yougile_task_chat by covering both task and group chats. However, it does not explicitly contrast itself with that sibling, so it's clear but not fully differentiated.

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

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

The description provides no guidance on when to use this tool versus alternatives. It lists operations but never states when to choose this over yougile_task_chat or other chat-related tools. The only pointer is 'Call yougile_help("chats.<operation>")' for parameters, which is about parameter help, not usage context. This leaves the agent to infer usage.

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

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

The description explicitly labels operations as [read] or [admin], providing auth-related behavioral context not present in the annotations. The phrase 'update/rename/soft-delete' hints at mutating behavior. However, with only openWorldHint as annotation, the description still does not explain side effects, soft-delete semantics, confirmation flow, or return behavior, so it only partially carries the transparency burden.

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

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

The description is compact and front-loaded: the first line summarizes the tool, followed by a tight operation table and a help pointer. The Russian translations somewhat repeat the operation names, and the opening line overlaps with the operation list, but there is no wasteful or excessive text.

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

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

For a multi-operation tool with no output schema and minimal annotations, this description gives operations, access levels, and a pointer to parameter details. It is minimally viable because an agent can follow the 'call yougile_help' instruction to get the missing information. However, it lacks per-operation parameter semantics, return value expectations, and behavioral side effects, leaving real gaps.

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

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

The input schema already documents operation and confirm. The description adds one concrete parameter clue: 'list (by boardId)', and hints that update may involve rename/soft-delete fields. Yet most parameter details are deferred to yougile_help, so the description adds only modest meaning beyond the schema, which has 67% coverage.

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

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

The description clearly names the resource ('Board columns') and lists concrete operations: list, get, create, update, with the list operation scoped by boardId. This distinguishes it from sibling resources like boards and tasks. However, 'soft-delete' is mentioned in the opening line but is not present as a selectable operation in the schema or operation list, which introduces minor ambiguity.

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 operation list with [read] and [admin] access labels gives basic guidance on which operations are available and at what permission level. It also tells the agent to call yougile_help('columns.<operation>') for parameters. But it never explicitly says when to use this tool versus sibling tools, nor does it provide exclusions or alternative routes.

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

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

Annotations provide only openWorldHint, so the description carries the behavioral burden. It discloses that write/webhook operations require admin access and that webhooks are event subscriptions, which is useful. However, it does not explain side effects, confirmation requirements, or response/return behavior for operations.

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 layout is compact and scannable: a one-line resource summary, a bullet list of operations with access, and a direct pointer to help. There is little wasted text, though the operation labels are terse.

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?

This is a multi-operation facade with no output schema and no per-operation parameter details in the description. It relies entirely on the external yougile_help tool to supply what an agent needs to call most operations, so it is not self-contained or complete enough for direct 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?

Input schema already documents operation enum, params object, and confirm flag; at 67% coverage the schema is the main source. The description adds no operation-specific parameter semantics—it merely defers to yougile_help('company.<operation>'), so the agent still cannot invoke an operation correctly without an extra lookup.

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 'Company details and webhooks' and enumerates five concrete operations with access levels, making the resource scope clear. It distinguishes by resource name from sibling tools (projects, tasks, users), though it does not explicitly contrast with any sibling.

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?

Access labels ([read]/[admin]) give some context about who can call operations, but there is no guidance on when to choose this tool over siblings or when not to use it. The only usage hint is 'Call yougile_help(...)' for parameters, which is parameter lookup, not usage selection.

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

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

Annotations only include destructiveHint: false, so the description carries the burden. It mentions that client copies can be created, a behavioral trait. However, it does not disclose that confirmation may be required for client-facing projects (implied by the confirm parameter) or other side effects. The description adds limited transparency beyond the schema but does not contradict annotations.

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

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

The description is concise, two sentences, with the primary purpose front-loaded. The client copy instruction is a useful addendum. The only flaw is the mention of parameters not in the schema, which detracts from clarity, but the structure itself is efficient.

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

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

For a tool with 13 parameters and no output schema, the description is thin. It doesn't mention the confirmation flow for client-facing writes, error handling, or that client_title/client_description are not actual parameters. The reference to a non-existent sibling (yougile_client_copy) is also unhelpful. The description covers only the basic task creation scenario and misses important operational details.

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

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

The description lists several parameters (board, column, assignees, deadline, planned hours, checklist) but does not add meaning beyond the schema, which already describes most parameters. More critically, it references client_title and client_description which are not defined in the input schema, potentially misleading the agent. This reduces the value of the description in guiding parameter usage.

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

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

The description clearly states the tool creates a task and enumerates key fields (board, column, assignees, deadline, planned hours, checklist), distinguishing it from update/move siblings. The client copy mention adds specificity for a particular scenario. The reference to client_title/client_description not present in the schema is a minor flaw but doesn't obscure the core purpose.

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

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

The description provides specific guidance for client work, instructing to pass client_title and client_description for client copies and referencing yougile_client_copy. It does not explicitly contrast with update/move tools, but the verb 'create' makes the use case clear. The guidance is adequate but could mention exclusions (e.g., when to use update instead).

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

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

The annotations only include openWorldHint: true, which is minimal. The description discloses that there are write and read operations, and that a confirmation might be required for writes (via the confirm parameter), which is somewhat transparent. However, it does not disclose details like potential side effects, data retention, or error handling beyond referring to help. No contradiction with annotations.

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

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

The description is concise and structured, using a list for operations and access levels. It is front-loaded with the purpose. The reference to yougile_help is efficient. However, the bilingual phrasing (English and Russian) might be slightly unnecessary, but it does not add length.

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

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

Given the tool is a dispatcher with openWorldHint, the description covers the basic operations and points to help for details. However, it does not explain the return format (though no output schema exists), and it relies on yougile_help for parameter specifics. For a tool with two operations, this seems minimally acceptable but not fully self-sufficient.

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

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

The schema provides an enum for operation, which is well-defined. The params parameter is a generic object with a description that gives an example and references yougile_help, but the description does not elaborate on each operation's specific parameters. However, since schema description coverage is 67% and the description explicitly tells the agent to call yougile_help for parameters, it adds some value but relies heavily on the help tool. The confirm parameter is self-explanatory.

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

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

The description clearly states the tool is for CRM, specifically contact persons and lookup by external messenger ID. It lists the two operations and their access levels (write/read), which indicates it is a dispatcher for CRM contact operations. This distinguishes it from other Yougile tools that manage tasks, projects, boards, etc.

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

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

The description implies usage by listing operations and access levels, but it does not explicitly state when to use this tool versus alternatives like yougile_help or other CRUD tools. It instructs to call yougile_help for parameters, which is a form of guidance but not comprehensive. There is no explicit mention of when not to use it.

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

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

The description explicitly labels the operation as [write] and states the return value, which is useful beyond the sparse openWorldHint annotation. It does not disclose permission requirements, file size limits, persistence, or confirmation behavior, leaving some burden on the agent.

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

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

The first sentence is front-loaded and informative, and the help pointer is actionable. The operations line and 'Загрузить' translation are somewhat redundant with the schema's const operation, but the overall definition remains compact.

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?

It tells the agent what the tool returns and how to obtain parameter details, which covers basic invocation flow. However, with no output schema and only an openWorldHint annotation, the absence of any upload-specific parameter or side-effect detail makes it only partially complete for a write operation.

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

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

The schema already describes the generic 'params' object and 'confirm', but the description adds no concrete upload parameters (e.g., file path/name). The pointer to yougile_help is a discovery mechanism, not parameter semantics, and with 67% schema coverage the description does not compensate for the missing upload-specific fields.

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

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

Description opens with a specific action and object: 'Upload a file to YouGile', and adds the distinct outcome 'returns a URL to use in chat messages or descriptions'. This is enough to identify it as the file-upload tool among the many task/chat/project 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?

The stated return use ('to use in chat messages or descriptions') gives clear context for when this tool is appropriate. It does not name exclusions or alternative tools, but no sibling performs the same upload function.

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

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

Annotations already declare readOnlyHint=true, and the description enriches that with concrete behavioral detail: completed tasks expose completed_at, column-done tasks expose done_by_column: true with no date, overdue open tasks expose overdue: true, and completed-since/until results are ordered newest first. This goes beyond the annotation and helps the agent interpret returned data 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 a compact paragraph with no filler. It front-loads the core purpose, then efficiently explains search scope and output flags, with each sentence contributing meaningful behavioral or filtering 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 read-only search tool with no output schema, the description covers the important return quirks (completed_at, done_by_column, overdue), default workspace behavior, and the semantics of the completed-period filters. This is sufficient for an agent to invoke the tool and interpret results 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?

Schema coverage is 80%, so the baseline is 3, but the description adds value by explaining the default project/whole-company scope and how completed_since/completed_until select tasks in a period. Schema descriptions already handle most parameters, so the description's extra context lifts it above baseline without fully replacing schema detail.

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: 'Find tasks by project/board/column names, assignee and title words.' This immediately distinguishes it from broader sibling tools like yougile_tasks by focusing on search criteria rather than plain listing. It also communicates the scope behavior (default project or whole company), which sharpens the resource being searched.

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

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

The description implies the tool is for filtered searching, and it explains what happens when no place is specified. However, it never explicitly names sibling alternatives like yougile_tasks or states when NOT to use this tool, so the agent must infer usage from the filter-oriented wording.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds context about what the tool covers (parameters, types, required fields, access) but doesn't disclose additional behavioral traits like output format, pagination, or whether it returns live data vs static documentation. With annotations covering the safety profile, a 3 is appropriate.

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

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

The description is a single concise sentence that front-loads the purpose and lists the key aspects covered. It's efficient with no wasted words, though it could arguably be slightly more specific about the operation parameter's behavior.

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

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

Given the tool's simplicity (1 optional parameter, output schema present, read-only annotations), the description is largely complete. It explains what the tool does and what it covers. The output schema exists, so return values don't need explanation. A minor gap is not describing what the output looks like for different operation values, but the output schema likely covers that.

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

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

Schema description coverage is 100%, so the schema already documents the 'operation' parameter well, including its default and example values. The description adds minimal extra meaning beyond the schema, so the baseline 3 is correct.

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

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

The description states a clear purpose: describing YouGile domain tools and operations, including parameters, types, required fields, and access. It distinguishes itself from sibling tools by being a meta/help tool that explains other tools rather than performing domain operations. However, it doesn't explicitly name any sibling or contrast itself with them, so it's clear but not fully differentiated.

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

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

The description implies when to use this tool: when an agent needs to understand YouGile tools, parameters, types, required fields, or access. The operation parameter with 'list' or a tool name provides clear context for how to use it. However, it doesn't explicitly state when NOT to use it or name alternatives, so it falls short of a 5.

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

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

The description adds the behavioral trait 'keeping the plan', which clarifies that the plan is not modified. However, it does not mention the confirmation requirement for client-facing projects (even though the confirm parameter is described in the schema) or any other side effects. With only destructiveHint=false as annotation, the description carries some but not full responsibility; it adds one useful nuance but lacks depth.

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

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

The description is a single, tightly worded sentence that front-loads the verb and resource. Every word earns its place, with no filler or redundancy.

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

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

The description is minimal but covers the core action. However, it omits the confirmation workflow (critical for writes to client-facing projects) and does not hint at return behavior or error conditions. For a mutation tool with no output schema and sparse annotations, this leaves the agent without guidance on important operational aspects.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions 'worked hours' and 'keeping the plan', which loosely relates to the hours and plan_hours parameters, but it does not add significant meaning beyond the schema. The confirm parameter is not mentioned in the description at all.

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

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

The description clearly states the verb ('Add'), the resource ('a task's time tracking'), and the specific nuance ('keeping the plan'), which distinguishes it from any sibling tool. It is immediately obvious what the tool does and that it is a mutation for logging time.

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

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

The description does not explicitly state when to use this tool versus alternatives or when not to use it. Since no sibling tool handles time logging, the use case is implicitly unique, but the lack of explicit guidance (e.g., 'use this when you need to record worked hours') leaves some room for ambiguity.

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

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

The description goes well beyond the single annotation (destructiveHint: false) by disclosing important behavioral traits: it explains that jumps over a workflow chain are rejected, that moving into a done column marks the task completed (recording the date), and moving out reopens it. This is rich behavioral context that an agent needs to predict side effects. No contradiction with annotations.

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

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

Three sentences, each delivering distinct value: the core action, the workflow chain nuance, and the done/reopen behavior. No fluff or repetition. The most important information is front-loaded, and the structure is logical and easy to parse.

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

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

The description covers the main behavioral complexities (workflow chain and status changes) but does not mention the 'confirm' parameter's role in client-facing projects, though the schema describes it. It also omits any mention of return values (no output schema exists). For a mutation tool with 5 parameters, it is fairly complete, but the absence of a mention of the confirm flow is a minor gap.

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

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

With schema coverage at 80%, most parameters are already described. The description adds meaningful context to the 'column' and 'task' parameters by explaining how the column is interpreted (walking through intermediates) and the completion/reopen effect. It does not add details for 'board' or 'confirm', but the schema already covers them. The added semantics are valuable and go beyond the schema.

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

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

The description clearly states the action: 'Move a task to another column.' It goes beyond a simple verb+resource by explaining the workflow chain behavior and done/reopen semantics, making the purpose unambiguous. While it doesn't explicitly differentiate from yougile_update_task, the core action is so specific that an agent can easily identify this tool's 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 context about workflow chains (referencing yougile_overview) but does not explicitly state when to use this tool versus alternatives like yougile_update_task or yougile_task. It implies you should check the overview first, but there is no clear when-to-use or when-not-to-use guidance. The behavioral context helps, but explicit alternatives are missing.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds value by describing the scope of what is returned: structure, workflow, defaults, done columns, session permissions, and where settings change. This goes beyond the annotation to clarify what 'overview' entails, giving the agent a full picture of the information available.

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

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

The description is a single sentence that front-loads 'Company structure' and then enumerates the covered aspects. It is dense but not redundant; every item adds information. It is concise given the breadth of content, though a slightly clearer separation of items could improve readability.

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

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

For an overview tool with two optional parameters and no output schema, the description provides a clear idea of what will be returned: structural hierarchy, workflow chains, defaults, done columns, session permissions, and settings location. It is complete enough for an agent to know when to call it and what to expect, and it addresses the session-specific nature of permissions.

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?

Both parameters (project and include_ids) are fully described in the schema with 100% coverage, so the description does not need to add parameter details. The description does not mention the parameters, but that is acceptable given the schema already documents them. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description states precisely what the tool does: it provides an overview of company structure, including projects, boards, columns, workflow chains, defaults, done columns, session permissions, and settings locations. It clearly distinguishes itself from siblings by being the entry point ('Start here') while siblings are specific (boards, columns, tasks). The verb is implied but the resource and scope are 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 phrase 'Start here to learn the names' gives clear usage context, implying this is the first tool to call for orientation. It does not explicitly mention alternatives or exclusions, but the sibling list makes it evident that specific tools like yougile_boards or yougile_columns are for detailed data. So it has clear context but lacks explicit when-not guidance.

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

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

The description lists access levels (read vs admin) for each operation, giving some indication of which operations are mutations. However, it does not disclose side effects such as reversibility, confirmation requirements, or the permanence of deletions. With annotations providing only openWorldHint, the description partially covers behavioral transparency but leaves important aspects unstated.

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

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

The description is concise and well-structured, opening with a clear purpose and then listing operations with access levels. It is front-loaded and avoids unnecessary detail. The list is slightly redundant with the enum but adds access context, so it earns its place.

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

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

The tool has nine operations but the description provides only names and access levels, not parameter requirements or return structures. It explicitly defers all parameter details to yougile_help, making the description not self-contained. With no output schema and sparse annotations, an agent cannot construct a valid call without consulting another 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 minimal parameter meaning; it repeats the instruction to call yougile_help, which is already in the schema's params description. It does not explain what each parameter means or how they map to operations, and the confirm parameter is not mentioned. With 67% schema coverage, the description should compensate but instead defers entirely to another tool.

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 resource ('Projects and project roles') and enumerates the operations (list, get, create, update, roles CRUD), which distinguishes it from siblings like tasks or boards. However, it does not elaborate on what each operation does beyond the operation name, so it is clear but not fully detailed.

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

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

There is no explicit guidance on when to use this tool versus alternatives. The description does not mention other tools or provide context for when project management is needed. The only directive is to call yougile_help for parameters, which is not 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 only openWorldHint in annotations, the description carries the behavioral burden. It does add value by tagging each operation as [read] or [admin], which signals permission and side-effect expectations. It does not disclose confirmation requirements, irreversibility, return behavior, or failure behavior, so the disclosure is partial.

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 purpose line is front-loaded and the operation list is compactly structured with access labels. There is some repetition in the Russian labels and access tags, but for a 14-operation facade the list is an efficient way to expose capabilities.

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

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

The tool is complex and has no output schema or per-operation parameter schemas, so the description offers the bare essentials: operation names, access levels, and a route to yougile_help for parameters. It does not explain the domain meaning of stickers/string/sprint/state, return values, or error behavior, leaving a real gap for an agent deciding how to use it.

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

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

The schema only defines the generic params/confirm/operation envelope; the description's instruction to call yougile_help('stickers.<operation>') is a useful pointer for resolving operation-specific parameters. However, the description itself does not define any parameter names or meanings, so it adds a mechanism but not actual parameter semantics.

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

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

The description identifies the tool's domain as Yougile custom stickers ('string/state and sprint') and their states, and enumerates concrete operations (list/create/get/update), so an agent can see it is a CRUD-style facade. It is not a tautology and is distinct from siblings like yougile_tasks, though it never defines what a 'string' sticker is, so it stops short of being fully specific.

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

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

There is no explicit statement about when to use this tool instead of a sibling or which operation to choose in a given scenario. The access list is informative but does not guide selection, and the only practical instruction is to call yougile_help for parameter details.

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

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

Annotations already declare readOnlyHint=true, which the description's 'Open' language is consistent with. Beyond the annotation, the description adds genuine behavioral context: it discloses that sticker types the YouGile API cannot describe (numbers, free text) surface by id under other_stickers, a non-obvious API quirk. No contradictions.

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

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

Two sentences, with the core purpose and feature enumeration front-loaded and the caveat about other_stickers appended. The comma-separated feature list is dense but efficient for a detail-returning tool; no filler or redundancy.

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

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

For a 2-parameter read tool with readOnlyHint=true and no output schema, the description compensates well by specifying what the returned card contains and even flagging the sticker quirk. It leaves nothing critical unsaid given the tool's low complexity, though a brief note on the response shape could push it further.

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

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

Schema description coverage is 100%, so both parameters are already fully documented in the schema. The description adds only marginal semantic value: 'optionally the latest chat messages' mirrors the messages parameter's default=0 behavior. Baseline 3 is appropriate since the schema carries the parameter burden and the tool description does not need to compensate.

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

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

The description states a specific verb and resource ('Open a task card') and enumerates the exact contents returned (status, assignees, deadline, hours, checklists, stickers, description, optional chat messages). It visually distinguishes itself from siblings like yougile_tasks (listing), yougile_task_chat (chat-focused), and yougile_update_task (write operation) through the feature set it names.

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

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

Usage is implied: call this when you have a task number/id and want the full card details. However, the description provides no explicit when-to-use vs alternatives guidance, no exclusions, and does not route the agent to siblings such as yougile_find_tasks for locating tasks or yougile_task_chat for deeper history.

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

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

Annotations only provide destructiveHint: false, which is minimal. The description discloses the optional write behavior ('optionally posting a message first'), which goes beyond annotations. However, it does not mention the confirmation mechanism (the 'confirm' parameter) that may be required for writes into client-facing projects, nor any side effects. Given the low annotation coverage, this is a reasonable but not exhaustive 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 single, concise sentence that front-loads the primary purpose and then notes the optional action. There is no waste, and it reads clearly. It is appropriately brief for the tool's simplicity.

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

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

The description covers the main purpose and the optional write. It does not mention the confirmation flow or that posting is a write that may require user approval, but these are covered in the schema. For a tool with 4 parameters and no output schema, the description is mostly complete, though a brief note about the confirm requirement would enhance completeness.

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

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

Schema description coverage is 100%, so all parameters (send, task, limit, confirm) are already described in the schema. The description adds minimal additional meaning: it mentions reading and posting, which maps to limit and send, but does not elaborate on parameter nuances like the confirm requirement. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the primary action ('Read the latest messages of a task's chat') with a specific verb and resource, and adds the secondary capability ('optionally posting a message first'). It distinguishes from siblings like yougile_chats (which likely lists chats) and yougile_task (task details) by focusing on chat messages of a specific task.

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 context (reading a task's chat) but does not explicitly state when to use this tool over alternatives like yougile_chats or yougile_task. It lacks explicit when-not or alternative routing. The purpose is clear enough that an agent might infer it, but the guidance is not explicit.

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

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

Annotations provide only openWorldHint, so the description adds meaningful value by labeling each operation as [read] or [write], mentioning soft-delete via deleted=true, and noting that a task's chat id equals the task id. However, it does not disclose side effects such as permission requirements, irreversibility of archive/delete, notifications, or response behavior, leaving parts of the behavioral burden uncovered.

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

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

The description is structured with a feature summary, an operation list, and a help pointer, which aids scanning. However, it repeats content—list/search and update capabilities appear both in the prose and in the operation enumeration—and mixes English and Russian, adding noise for an agent trying to parse it quickly.

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 seven-operation aggregator with no output schema and only openWorldHint, the description supplies operations, read/write access levels, available filters and update fields, and a clear help command. It remains incomplete on return values, exact parameter requirements, and side effects, relying heavily on the external yougile_help tool to fill in gaps.

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

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

The input schema has a generic free-form params object with no per-operation field definitions, so the description helps by enumerating likely fields such as columnId, assignedTo, stickerId, title, deleted, timeTracking, and others. It also directs the agent to yougile_help for exact parameters, but types, constraints, and required fields are still absent, so the description only partially compensates for the schema's low effective coverage.

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

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

The description clearly states that this tool handles YouGile task operations: list/search with filters, get by UUID or number, create, update with specific fields like columnId, deadline, and checklists, plus chat subscribers. It is far more than a tautology and identifies a specific resource and verb set, though it does not explicitly contrast with sibling task tools like yougile_task or yougile_create_task.

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 lists operations and instructs the agent to call yougile_help('tasks.<operation>') for parameters, but it gives no guidance on when to use this aggregate tool versus the many sibling tools such as yougile_find_tasks, yougile_update_task, or yougile_task_chat. No exclusions, selection criteria, or alternatives 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?

Beyond the minimal destructiveHint=false annotation, the description adds meaningful behavioral context: 'Only the given fields change' discloses partial-update semantics, and it distinguishes replace vs append for description and 'by name' for assignees. This helps the agent predict side effects without contradicting the annotations.

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

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

A single, front-loaded sentence packs the full editable-field inventory plus the partial-update rule without filler. Every clause earns its place, and the key behavioral note comes at the end for emphasis.

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 17-parameter written tool with no output schema and only a light annotation set, the description covers the essential semantics well: what can be edited, how assignees are matched, and that unspecified fields are untouched. It does not state the return value or discuss the confirm/confirmation flow, but the schema documents the confirm parameter, and the field inventory is complete enough for safe 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?

With only 53% schema description coverage, the description compensates by mapping the field list to parameters (title, description, assignees, deadline, plan_hours, completed, archived, color, checklist items) and adding semantics like 'assignees (by name)' and 'description (replace it, or append to it)'. Most importantly, 'Only the given fields change' clarifies that null defaults mean no-op rather than clearing the field.

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 'Edit a task' — a specific verb plus resource — and then inventories the editable attributes. This clearly distinguishes the tool from siblings like yougile_create_task, yougile_move_task, and yougile_log_time, so an agent can select it without inspecting the schema.

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

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

There is no explicit guidance about when to use this tool versus alternatives, nor any exclusion such as 'for moving tasks use yougile_move_task'. 'Edit a task' implies the general use case, but the description never articulates selection criteria or prerequisites, so the agent must infer usage from the name and sibling list.

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

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

Annotations already indicate idempotent and non-destructive. The description adds context that 'Nothing changes in YouGile' and explains the side-effect on task tools, which goes beyond annotations. It clarifies the tool stores a preference locally rather than modifying the actual board data. No contradiction with annotations.

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

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

Two sentences, both essential, with the primary purpose front-loaded. No redundant phrasing or filler. The description is compact and immediately informative.

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 preference-storing tool with optional parameters and no output schema, the description covers the essential aspects: when to call, what it does, and that it doesn't alter YouGile. It could mention persistence details (e.g., per user) but that's not necessary for correct invocation.

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

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

Schema coverage is 100%, so both parameters are well-documented with descriptions. The tool description does not add additional meaning beyond the schema, but the schema already explains board name format and the 'Project / Board' pattern. Baseline 3 is appropriate since the schema carries the burden.

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

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

The description clearly states the tool's purpose: to remember the user's usual board. It names the specific resource (board) and the action (remember). It distinguishes from siblings like yougile_boards by explaining that this tool stores a preference rather than querying boards.

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

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

The description explicitly says when to call it: 'when the user says which board they work on or asks to remember it.' It also explains the effect on other tools ('task tools use it whenever they get neither a board nor a project'). This gives clear triggers, though it doesn't explicitly say when not to use it, which is minor given the clarity.

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

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

Annotations only include openWorldHint=true, so the description carries the behavioral disclosure burden. It usefully labels operations as read vs admin, indicating which are mutating, but it does not describe consequences of update/remove, confirmation requirements beyond the schema's confirm field, or any side effects.

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

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

The description is compact, front-loaded with the resource scope, and organized as a scannable operation list with access levels. The mixed-language notes add minor noise but do not undermine usefulness.

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 ten-operation dispatcher with no output schema and generic params, the description provides operation names, access levels, and a route to parameter details via yougile_help. It still leaves gaps around operational semantics, expected response shapes, and how this tool relates to sibling tools, so it is adequate but not fully complete.

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

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

Schema description coverage is 67%, and the params field is generic, so the description's instruction to call yougile_help('users.<operation>') for parameters is the main way the agent learns about operation-specific inputs. However, this instruction is largely redundant with the schema's own pointer to yougile_help, and the description does not enumerate or explain any actual parameter values.

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 identifies a clear resource ('Company employees and departments') and enumerates specific operations (list, invite, me, get, update, remove, departments variants), making the tool's scope concrete. It does not explicitly frame this as a multi-operation dispatcher namespace, but the operation list itself disambiguates the purpose well.

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 each operation an access level ([read] vs [admin]), which implies when privileged use is needed, and instructs the agent to call yougile_help('users.<operation>') for parameters. However, it does not explain when to choose yougile_users over sibling tools like yougile_company or yougile_help, nor does it state exclusions or alternative conditions.

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