Tiflux

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

Annotations provide idempotent, non-destructive hints, and the description adds meaningful context: browser login flow, two-auth-mode behavior, permanent vs session-only token, and no-args behavior. It does not disclose exact outcomes after submitting a token, but the added context exceeds what annotations alone offer.

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 purpose and explains both workflows in two sentences. All clauses contribute meaning, though the 'MCP.AI for IDE agents (Cursor, etc.)' preamble could be slightly tightened.

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 one-parameter auth tool with no output schema, the description covers the primary usage paths: browser login, config header, token call, and no-args link generation. Missing return/error semantics after token submission are a minor gap but do not undermine usability.

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 one optional token parameter with zero description coverage. The description compensates by explaining the token is a JWT used for session-only login and that omitting it returns a login link, which is sufficient for this simple parameter.

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 authenticates the user to MCP.AI for IDE agents through browser login and token exchange. It specifies two concrete usage modes: permanent config header or session-only token, which distinguishes it from sibling tools like connect.

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 explains when to use the permanent config-header approach versus the session-only token call, and clarifies that calling with no arguments returns the login link. However, it does not mention alternatives or 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.

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail beyond annotations by specifying exact response states: authenticated:true with empty pending[] when connected, and connect_url plus per-install URLs when credentials are missing. This is effective disclosure, especially with no output 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 two sentences, front-loaded with the core purpose, and provides conditional details without unnecessary filler. Every sentence adds value.

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

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

For a zero-parameter no-output-schema tool, the description covers all relevant behavioral branches and key return fields. It is sufficiently complete for an agent to know what to expect and when to use 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 tool has zero parameters, so the baseline is 4. There is nothing to explain beyond the schema, and the description correctly focuses on behavior instead.

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 'Returns connection status and URLs', which specifies the verb and resource. It also explains conditional outcomes, making the purpose unambiguous, though it does not explicitly differentiate from siblings like authenticate.

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 conveys clear usage context: use this to check connection status and retrieve URLs. It gives conditional behavior for connected vs missing-credential states, but does not explicitly state when not to use it or mention alternative tools.

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

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

Though annotations are minimal (readOnlyHint=false, openWorldHint=true, etc.), the description discloses extensive behavioral traits: invoke works even without installation, returns connect/checkout links for missing credentials/payment, requires workspace owner/admin for writes, and covers the prompt library's sharing behavior without login. It clearly explains what happens on invoke when MCP is not installed and the retry flow after payment, which is critical context the annotations don't 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 well-structured: it starts with the overarching purpose, then explains the core flow, key invoke behavior, install vs invoke tradeoffs, list_tools, permissions, and the prompt library. It is front-loaded with the marketplace identity, then follows a logical order. Though dense, every sentence adds value; no redundancy or fluff. It could be tightened, but for a tool with 14 actions, the length is largely justified.

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 (14 actions, 23 params, no output schema), the description provides a high level of context: it explains the search→describe→invoke workflow, auth requirements, payment edge cases, install semantics, list_tools purpose, and prompt library behavior. It doesn't exhaustively describe return values for every action (e.g., subscribe/cancel responses), but it covers the most critical ones. The absence of an output schema raises the bar, but the description covers enough to guide an agent effectively.

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 23 parameters with 0% description coverage, so the description must compensate. It explains the action enum and the core flow (e.g., action=search, describe, invoke) and mentions key params like mcp_id and tool_id implicitly. However, it does not detail parameters like limit, immediate, tier_slug, conversation, or prompt_vars. The description adds meaning over the bare schema by explaining the action semantics, but given the large parameter set, it falls short of fully clarifying each parameter's purpose.

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 this is the official mcp.ai marketplace — the catalog of MCPs/tools and the way to run them. It distinguishes itself from siblings by describing its core flow (search → describe → invoke) and covering actions like install, subscribe, and the prompt library, which no sibling touches. The verb 'marketplace' is specific and unambiguous.

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

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

Explicit guidance is given throughout: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', and list_tools is presented as the way to see what is callable now. It also explains when to use search vs describe vs invoke, and covers alternatives like request_mcp when nothing fits. The 'when-not' is clearly stated for install vs invoke.

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 idempotentHint=true and destructiveHint=false, so the description adds little about safety. The description mentions 'send feedback' but does not explain what happens after reporting (e.g., creates a ticket, sends an email) or any side effects. It also refers to a 'conversation array' while the schema specifies it as a string, creating a slight ambiguity. Overall, the description fails to add meaningful behavioral context beyond the annotations.

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

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

The description is two concise sentences with zero filler. It front-loads the primary action and then gives a specific usage tip, earning every word. Structure is excellent.

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, the description should explain what happens after the report is submitted, but it does not. The parameter semantics are incomplete (context unexplained, conversation type mismatch). The tool's complexity is low, but the description misses critical return-value and parameter details, leaving the agent guessing about the outcome.

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 description coverage at 0%, the description is solely responsible for explaining parameters. It only hints at 'conversation' by saying 'conversation array', but the schema defines it as a string (likely JSON-encoded). It does not explain 'context' at all, and 'message' is only implicitly understood as the main content. The description adds minimal value beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' This is a specific verb+resource construction, and it distinguishes itself from the tiflux siblings by its general reporting nature. It could be more explicit about what makes it unique compared to tiflux_tickets_feedback_report, but the core 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?

The description provides one clear usage instruction: 'Include the conversation array with recent messages for reproduction.' This implies when to use the tool (for bug reports where reproduction is needed) but does not specify when not to use it or mention any alternatives. It lacks explicit exclusions or comparison to sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing the key safety profile. The description adds no behavioral context beyond what annotations state, such as output format or network behavior, but it also does not contradict the annotations.

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

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

The description is a single short sentence that front-loads the key information. Every word contributes meaning, with no filler or redundant detail.

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

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

For a zero-parameter, read-only version-inspection tool, the description conveys the essential purpose and return scope. It could mention the output shape, but the lack of an output schema is not a serious gap given the simplicity of the 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 tool has zero parameters, so the input schema is empty and description coverage is trivially 100%. There is nothing for the description to clarify, and the baseline for zero-parameter tools is therefore met.

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

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

The description uses a specific verb ('Show') and clearly identifies the resource ('current MCP platform and adapter versions'), making the tool's purpose immediately obvious. It is also distinct from any sibling tool, none of which appear to expose version information.

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 checking platform and adapter versions, but it does not explicitly state when to use this tool versus alternatives like toolkit_info. No exclusions or alternative recommendations are provided, so the guidance is only implicit.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the constraint about date pairs being mandatory together, which is behavioral context beyond annotations. It also mentions bulk support. However, it doesn't disclose pagination behavior, default limits, or what happens if no filters are provided.

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) and front-loaded with the main purpose. The date-pair constraint is clearly highlighted. However, it could be slightly more structured (e.g., bullet points) but overall it's efficient.

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

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

Given 11 parameters, no output schema, and 0% schema description coverage, the description is incomplete. It doesn't explain the meaning of most parameters, the behavior of the 'type' filter, or the response format. The date-pair constraint is helpful but insufficient for an agent to correctly construct queries with all available filters.

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 for parameter meaning. The description only mentions date pairs and client_ids for bulk support. It does not explain the 'type' enum (billed, reversed, paid), limit/offset semantics, nfe_number, ticket_number, or client_id vs client_ids relationship. With 11 parameters and zero schema coverage, this is a significant 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 states 'Histórico de faturamentos' (billing history), which clearly indicates the tool retrieves billing history records. It distinguishes from siblings by focusing on billing history, though it doesn't explicitly contrast with other list tools like tiflux_list_tickets or tiflux_get_tickets. The verb is implied (retrieve/list) but the resource is specific.

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

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

The description provides a key usage guideline: date pairs must be used together (billing_start_date with billing_end_date, due_start_date with due_end_date). It also mentions bulk support via client_ids. However, it doesn't explicitly state when to use this tool vs alternatives, nor does it mention any exclusions or prerequisites beyond the date pairing.

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 meaningful behavioral context beyond the annotations: canceled tickets are closed without being treated as resolved and do not count as resolved in reports. It clarifies that the action is a mutation but not destructive; this is useful for 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 description is composed of two short, information-dense sentences. The first sentence names the action and its core distinction, and the second sentence explicitly points to the alternative tool, with no wasted words.

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

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

For a simple one-parameter cancellation tool, the description covers the action, its behavioral effect on reporting, and the appropriate alternative. Without an output schema, the description still gives enough context for an agent to use the tool correctly.

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

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

The description does not go into detail about ticket_number beyond saying 'cancels a chamado', leaving the schema to carry the parameter meaning. The single parameter is self-explanatory, but since schema coverage is 0%, the description does not add extra guidance on format or 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 uses a specific verb and resource ('Cancela um chamado'), defines the closing behavior as not 'atendido', and explicitly differentiates from tiflux_close_ticket. It is unambiguous about what the tool does and avoids confusion with its closest 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?

The description clearly states when the tool should be used (duplicates, mistakenly opened, or out-of-scope tickets) and when it must not be used (effectively resolved tickets, which should go to tiflux_close_ticket). This gives the agent an explicit decision rule.

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=false, but the description adds valuable behavioral context: closing stops the SLA and triggers a satisfaction survey. This goes beyond the structured annotations and provides meaningful side-effect information.

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

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

The description is two sentences, front-loaded with the core action, followed by consequential effects and the alternative. No wasteful words; each sentence adds value.

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

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

For a tool with a single parameter and no output schema, the description covers the purpose, usage context, side effects (SLA stop, survey trigger), and alternative. It is complete and well-rounded, considering the low complexity and existing annotations.

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 only parameter, ticket_number, is self-explanatory from its name and schema (string or number). However, with 0% schema-description coverage, the description does not add any extra meaning about the parameter's format or requiredness. While not critical for this simple case, it fails to compensate for the lack of 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 clearly states the tool closes a ticket and marks it as resolved. It distinguishes from the sibling tiflux_cancel_ticket by explicitly noting the alternative for wrongly opened tickets, providing clear 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?

It explicitly states when to use the tool (closing a resolved ticket) and when not to (if the ticket should not have been opened, use tiflux_cancel_ticket). This is a clear when/when-not with an alternative.

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 communicate that this is a non-read-only, non-idempotent but non-destructive action. The description adds valuable behavioral context beyond the annotations by specifying that the appointment is registered on behalf of the token owner—an important attribution detail. It does not contradict the annotations, and no additional side effects like duplicate creation are described, but the added user-context justifies the score.

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, front-loaded sentence in Portuguese that efficiently conveys the action, resource, and ownership context. There is no filler or redundancy, and every phrase contributes to understanding the tool's 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?

The tool is a straightforward create operation with five required parameters and no output schema. The description covers the key ownership nuance and the action, but lacks details on parameter formats, validation, or what the tool returns. Given the annotations handle safety semantics, the description is minimally adequate but not fully complete for an AI agent.

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

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

With 0% schema description coverage, the description carries the full burden of explaining parameters, but it only implies 'chamado' (ticket) and 'apontamento de horas' (time appointment). It does not explain date/time formats, the meaning of init_time/end_time, or the description field. This is minimal compensation for undocumented parameters.

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

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

The description uses a specific verb ('Lança') and identifies the resource as 'apontamento de horas num chamado' (a time appointment on a ticket), clearly distinguishing this create operation from sibling list tools like tiflux_list_appointments. It also clarifies the acting principal ('em nome do usuário dono do token'), making the purpose unmistakable.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. The usage context is only implied by the verb 'criar/launch' and the mention of 'apontamento de horas', which contrasts with listing siblings, but the description does not explicitly advise on alternatives or prerequisites.

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 communicate that this is not a read-only, not idempotent, and not destructive operation. The description adds meaningful behavioral context beyond that: the note is visible only to the team and the requester is not notified or able to see it. It does not describe return/confirmation behavior, but this is not critical for a simple create-style tool.

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

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

The description is three concise sentences, each with a clear purpose: state the action, define the visibility scope, and mention the alternative tool. There is no filler or redundant information.

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

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

For a small create-operation with a clear schema and annotations, the description is sufficiently complete: it explains the note's audience, visibility behavior, and the correct sibling alternative. The `files` parameter is not discussed, but its shape is already available in the input schema.

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

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

Schema description coverage is 0%, so the description must compensate for missing parameter explanations, but it does not explicitly describe `text`, `ticket_number`, or `files`. 'Nota' and 'num chamado' indirectly hint at `text` and `ticket_number`, but `files` is not semantically explained 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 Portuguese description uses a specific verb and resource: 'Cria uma comunicação interna num chamado' — a team-only internal note on a ticket. It also differentiates from siblings by clarifying that the requester neither sees nor receives it.

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 vs. an alternative: 'Para falar com o solicitante use tiflux_create_ticket_answer.' This is a direct when/when-not decision rule.

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 a non-read-only, non-destructive operation, and the description aligns by saying it creates a new ticket. It adds useful behavioral context: requesters can be created implicitly when supplying name/email, and multiple IDs can be batched. The bulk behavior and requester-creation side effect go beyond the structured annotations.

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

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

The description is compact and front-loaded: a one-line purpose, followed by key prerequisites and bulk support. Every sentence delivers actionable information without fluff or repetition of schema details.

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

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

Given the tool's high complexity (22 params, no output schema), the description covers the most critical operational steps: resolving desk/client, determining the requester, and using bulk mode. However, it does not mention what the API returns, how files/followers/parent ticket should be used, or whether certain fields are mutually exclusive beyond the requester case. It is sufficient for basic correct usage but leaves edge cases open.

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 description coverage and 22 parameters, the description carries a heavy burden. It adds meaningful semantics for desk_id/client_id resolution, requester selection, and bulk plural fields, but it does not explain many other parameters such as followers, parent_ticket_number, files, priority_id, status_id, or responsible_id. The existing explanations are helpful but only partially compensate for the schema 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 opens with 'Abre um novo chamado' (Opens a new ticket), using a specific verb and resource that clearly distinguishes it from siblings like tiflux_create_ticket_answer and tiflux_create_appointment. It immediately identifies the tool's core action without 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 description provides explicit ahead-of-time guidance: resolve desk_id and client_id using tiflux_list_desks and tiflux_list_clients, and identifies the requester via requestor_id or via requestor_name/requestor_email for new requesters. It also explains when to use the plural bulk fields, though it does not explicitly state when not to use the tool versus alternatives.

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

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

The description discloses key behavioral traits beyond the annotations: the answer is visible to the requester and triggers a notification. It does not cover authorization or reversibility, but the annotations already establish readOnlyHint=false, destructiveHint=false, so this additional context is valuable.

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

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

The description is two sentences, front-loaded with the core purpose, and includes a targeted alternative reference. Every sentence adds value with 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?

The tool is a mutation with four parameters and no output schema or parameter descriptions. The description provides strong purpose and usage context, but lacks details on optional parameters like files and with_signature, which an agent needs to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain any of the four parameters. Parameter names like 'text', 'files', and 'with_signature' are somewhat self-explanatory, yet the description provides no additional meaning, defaults, or guidance on how to specify 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 uses a specific verb ('Responde um chamado') and identifies the resource (a ticket). It further distinguishes itself from the sibling tool tiflux_create_internal_communication by stating that the answer is visible to the requester and triggers a notification.

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

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

The description explicitly states when to use this tool versus an alternative: 'Para uma nota que só a equipe vê, use tiflux_create_internal_communication.' 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?

The description discloses a key behavior: partial failure handling ('Um id que falhar não derruba os demais'). This goes beyond the built-in annotations (readOnly, idempotent) and adds transparency about error resilience.

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

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

The description is extremely concise, consisting of two short sentences. It delivers the core purpose and a notable behavioral detail, with no filler or repetition.

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 function and a behavioral nuance, but it lacks details about return format, error handling (beyond partial failures), or any additional context such as required parameters or potential edge cases. Given the simplicity of the tool, this is adequate but not exhaustive.

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

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

The parameter 'client_ids' is mentioned only in the schema with no description. The tool description does not elaborate on the parameter, its format, or constraints beyond the name, leaving the schema's 0% coverage uncompensated.

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 function: 'Detalha um ou vários clientes pelos ids' (details one or several clients by ids), distinguishing it from list operations like tiflux_list_clients. It also emphasizes a single call, which adds specificity.

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

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

No explicit guidance is provided on when to use this tool versus alternatives (e.g., tiflux_list_clients for all clients). The purpose is implied by the name and description, but no usage context or exclusions are given.

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 valuable behavioral context beyond annotations: it explains that multiple tickets are retrieved in a single call and that errors are handled individually (errors returned separately in errors[]). Annotations only state readOnly and idempotent; this error resilience is a unique behavioral trait.

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 only two sentences, front-loaded with the primary purpose, and then adds the critical error-handling detail. There is no fluff or redundancy; every word 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 3 parameters and no output schema. The description covers the core purpose and error behavior, but it omits any explanation of the boolean parameters or what the response structure looks like beyond the errors[] mention. For a simple tool, it's adequate but leaves gaps for the two boolean flags.

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 description coverage, the description must compensate for parameter explanation. It clarifies ticket_numbers (by numbers) but provides no meaning for show_entities or include_filled_entity booleans, which remain opaque. The description adds minimal value beyond the schema for parameters.

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

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

The description clearly states the function: 'Detalha um ou vários chamados pelos números' (details one or more tickets by numbers). This is a specific verb and resource, and it distinguishes from sibling tools like tiflux_list_tickets (which lists all tickets) by focusing on retrieval by specific numbers.

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 when you have specific ticket numbers, but it does not explicitly mention when not to use it or compare with alternatives like tiflux_list_tickets. The error-handling behavior is mentioned, but no explicit guidance on when to prefer this over other tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the output (stage entry times and SLA status) but does not disclose any additional behavioral traits like pagination or authentication requirements. This is adequate given the annotations provide the core safety information.

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 core purpose (history of stages and SLAs) and immediately adds a usage recommendation. There is no fluff, and every word contributes to understanding the tool's 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?

The tool has no output schema, so the description should explain return values; it does explain that it returns stage entry times and SLA outcomes. However, it does not mention pagination (limit/offset) or any error conditions, and it does not describe the parameters beyond the implicit ticket reference. The description is adequate for a simple history endpoint but leaves gaps in parameter usage and pagination 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 for parameter understanding. However, the description only implies the need for a ticket ('de um chamado') but does not explicitly explain ticket_number, and completely omits any mention of limit and offset parameters. It provides insufficient detail beyond what the schema already shows, failing to compensate for the coverage gap.

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

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

The description clearly states it provides the history of stages and SLAs for a single ticket, specifying what data it returns (when each stage was entered and SLA outcome). It explicitly specifies the use case for auditing deadline compliance, which distinguishes it from sibling tools like tiflux_get_tickets that list tickets generally.

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 a clear usage context: 'Use para auditar cumprimento de prazo' (use to audit deadline compliance). It does not explicitly mention when not to use it or alternatives, but the purpose is sufficiently scoped to a specific audit scenario, providing clear context without exclusions.

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 destructiveHint=false, covering safety. The description adds the scope (entire organization) and purpose (basis for reports), but does not discuss pagination, default behavior, or response format. With annotations covering the safety profile, this is adequate but not rich beyond them.

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

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

The description is two sentences, front-loaded with the core action and scope, followed by the purpose. Every word adds value with no redundancy or filler. It is highly concise and well-structured.

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

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

Given the tool has 7 parameters, no output schema, and scant annotations (beyond safety), the description provides the essential purpose and main filters but omits details like pagination behavior (limit/offset) and the meaning of include_valorization. It is sufficient for a simple list operation but could be more complete by noting defaults or response characteristics.

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 0% coverage, so the description must compensate. It names the key filter dimensions (period, attendant, desk) which map to start_date/end_date, user_ids, and desk_ids. However, it ignores limit, offset, and include_valorization, and does not provide format or semantics for the mentioned parameters. This partial compensation justifies a 3.

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

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

The description clearly states it lists time entries for the entire organization, with filters by period, attendant, and desk. It also mentions its role as the basis for worked and billable hours reports. This distinguishes it from the sibling tool tiflux_list_ticket_appointments, which is specific to ticket-related appointments.

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

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

The description provides clear context: it is used for organization-wide time entries and serves as the basis for hours reports. However, it does not explicitly mention when to use this tool instead of alternatives like tiflux_list_ticket_appointments, nor does it state any exclusions. Thus, it meets the 'clear context' level but falls short of explicit alternative 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 annotations already show readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context about partial name matching and the organizational scope, but it does not mention pagination behavior, ordering, authentication requirements, or result trimming, so the added behavioral detail is moderate.

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

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

The description is concise, front-loaded with the main verb and resource, and gives a practical use case in just two short sentences. Every sentence earns its place without unnecessary detail.

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

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

For a simple list/search tool, the description covers the primary context and the reason to call it. However, there is no output schema and no explicit statement about what the response will contain, how pagination works, or which fields match the partial-name filter, leaving some gaps.

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

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

Schema description coverage is 0%, and the description only hints at the 'name' parameter via 'busca parcial por nome'. The remaining parameters—limit, offset, active, and social_revenue—are not explained at all, leaving a significant semantic gap for a 5-parameter 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 says 'Lista clientes da organização' and clarifies the partial-name search behavior, which is a specific verb+resource pairing. However, it does not explicitly differentiate itself from the sibling tool 'tiflux_get_clients', so some possible ambiguity about list vs. get remains.

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 a concrete use case: 'Use para resolver o client_id exigido na abertura de chamado'. This tells the agent when the tool is useful, but it does not provide exclusions or compare itself with alternatives such as tiflux_get_clients.

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, idempotentHint=true, and destructiveHint=false, which clarify that this is a safe read operation. The description adds that filtering by client/type/status is possible, but it does not disclose pagination defaults, response shape, or any limits on returned data.

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 the action and object, then adds the most relevant filtering details. There is no filler, repetition, or unnecessary information, making it highly 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?

For a simple read-only list operation with strong safety annotations, the description is mostly adequate. However, with no output schema, no parameter-level documentation, and no mention of pagination or response details, the description leaves some gaps that an agent would benefit from when invoking the tool accurately.

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%, but the description maps the key filter parameters to their conceptual meanings: cliente maps to client_ids, tipo maps to contract_type_ids, and situação maps to status. It does not explain limit/offset semantics or valid status/type ID values, though those parameter names are relatively 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 begins with the specific verb 'Lista' and clearly identifies the resource being operated on: 'contratos de atendimento' (service contracts). It also names the main filtering dimensions (cliente, tipo, situação), which makes its purpose distinct from sibling list tools targeting other entities.

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 the tool: when the user needs to list service contracts, optionally filtered by client, type, or status. However, it does not explicitly state exclusions, pagination behavior, or when alternative tools should be preferred over this one.

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, destructiveHint=false, and idempotentHint=true, so the safe read-only nature is covered. The description adds a behavioral detail about permission scoping (non-admin sees only own group), which is useful beyond annotations. No contradiction exists.

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

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

The description is two short sentences, front-loaded with the main purpose and a single key behavioral caveat. No wasted words, but it could be slightly longer to explain parameters or usage 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?

The tool is relatively simple (list departments) and annotations cover safety, but the description leaves out parameter details (e.g., pagination, name filtering) and does not specify output format. Given no output schema and 0% schema description coverage, more could be added about what the response contains (e.g., department IDs, names).

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 carries the burden for explaining parameters. However, it provides no detail about name, limit, or offset beyond what the schema's types reveal. For a list tool with pagination parameters, the description does not explain their semantics, but the parameter names are fairly self-explanatory, so a baseline of 3 is appropriate.

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

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

The description clearly states it lists organization departments, with a specific verb and resource. It also adds a scoping detail (non-admin attendants see only their own group's departments), which distinguishes it from generic list tools, though it does not explicitly contrast with sibling list 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 implies when to use this tool (to list departments) but provides no explicit guidance on when not to use it or which alternative to choose. Sibling tools like tiflux_list_desks or tiflux_list_technical_groups are not mentioned, so an agent may not know the distinction.

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 cover the read-only, idempotent, non-destructive behavior, so the description only needs to add non-obvious behavioral context. It does add bulk support and the mention that SLAs are returned, but it leaves unclear how batch results are structured and how pagination behaves.

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

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

Two short sentences: the first front-loads the core purpose and result, the second adds bulk support. There is no fluff or repetition of structured fields.

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 an adequate basic scaffold: it states what the tool lists and that SLAs are included. However, with no output schema and four parameters, it should clarify whether desk_id remains required when desk_ids is passed and how limit and offset affect the listing.

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 0% description coverage, so the description bears the burden of explaining parameters. It mentions desk_ids for bulk execution but does not explain desk_id, limit, or offset, and the mapping from 'mesa' to desk_id is only implicit.

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

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

The description uses a concrete verb and resource: 'Lista as prioridades configuradas numa mesa' and it specifies the result includes SLAs. This clearly separates it from sibling listing tools such as tiflux_list_desk_stages and tiflux_get_ticket_stages_slas.

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 when-to-use guidance or mention of alternatives. The only usage-adjacent note is the bulk support, but it does not explain when to prefer desk_ids over desk_id, nor when this tool should be chosen over other tiflux list tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description does not need to restate safety. It adds the behavior of partial name search, which is useful, but does not disclose pagination, default ordering, or any side effects. Thus it provides some value beyond annotations but not rich behavioral detail.

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

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

The description is extremely concise—two sentences total. The first sentence states the core action and behavior, the second provides domain context. No filler or redundancy, achieving high information density with zero waste.

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

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

The description adequately explains the purpose and domain relationship, but it is incomplete for a listing tool with four undocumented parameters and no output schema. It lacks details on filtering (beyond name), pagination, and defaults. However, given the annotations cover safety, it is minimally viable but not comprehensive.

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

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

With 0% schema description coverage, the description must compensate for all parameters. It only explains the 'name' parameter via 'busca parcial por nome'. The 'limit', 'active', and 'offset' parameters are left undocumented in both schema and description. This is a significant gap for a 4-parameter 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 tool's function: 'Lista as mesas de atendimento' (lists service desks) and adds the search capability ('busca parcial por nome'). It distinguishes itself from sibling tools like tiflux_list_desk_stages and tiflux_list_desk_priorities by explaining that the desk defines those resources, so the purpose is specific and well-scoped.

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 by mentioning that desks define stages, priorities, and service catalogs, which hints that those sub-resources are accessed via other tools. However, it does not explicitly name alternative tools or state when not to use this one, so guidance is implicit rather than 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?

While annotations already indicate read-only and idempotent behavior, the description adds valuable transparency by mentioning bulk support via `desk_ids`. This goes beyond the annotations and informs the agent of an extended execution mode, enhancing understanding of side effects and capabilities.

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

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

The description is extremely concise, using two sentences to convey the core purpose and the bulk support feature. Every word is meaningful, with no redundant phrases or over-explanation. The structure is clean, separating the main functionality from the additional capability.

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?

Since there is no output schema, the description should explain the return value. It says 'list' which implies a collection, but does not describe the structure or content of the returned catalogs. It also omits any mention of possible error conditions or prerequisites, though the tool is relatively simple and these may be implied. Overall, 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?

The schema provides no parameter descriptions, and the description only partially compensates. It implicitly explains that `desk_id` identifies the desk and that `desk_ids` enables bulk operations, but it does not clarify the `limit` and `offset` parameters for pagination. With low schema coverage, the description fails to fully explain all parameters.

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

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

The description clearly states the action: listing service catalogs for a desk, and clarifies that these catalogs represent ticket classification. This is specific and distinguishes it from other list tools that target different resources, such as tickets or clients.

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 provide any guidance on when to use this tool versus alternatives. It only describes what it does, without mentioning conditions, prerequisites, or scenarios where it would be preferred over other listing tools. Given many sibling list tools, this is a significant gap.

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 read-only, idempotent, and non-destructive. The description adds extra context like bulk execution support and the practical use case, going beyond annotations to clarify behavior. No contradictions with annotations.

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

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

The description is two sentences, each carrying distinct information: first states what it lists, second gives usage context and bulk support. No unnecessary words; front-loaded and efficient.

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

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

For a simple listing tool, the description covers the core purpose, usage context, and bulk support. It does not detail return format or pagination behavior, but given the tool's simplicity and annotations, it is sufficiently complete. A slight gap on limit/offset semantics prevents a 5.

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 0%, so the description must compensate. It adds meaning to desk_ids (bulk execution) and implicitly explains desk_id as the single desk identifier, but it does not explain limit and offset parameters at all. This partial coverage warrants a 3.

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

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

The description clearly states the verb (List) and resource (stages of a desk), and distinguishes from sibling tiflux_get_ticket_stages_slas by specifying it lists flow stages for a desk. It also connects to a specific use case (finding stage_id for tiflux_update_ticket), which adds 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 explicitly says to use it to discover stage_id when moving a ticket with tiflux_update_ticket, and mentions bulk support for desk_ids. It provides clear context but does not explicitly mention when not to use it or contrast with alternatives, so a 4 is appropriate.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the important visibility scope (internal vs requester-visible), but does not disclose pagination behavior, ordering, or return format. 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?

A single sentence front-loads the operation and includes the key qualifier about internal visibility. Every word earns its place; there is no filler or repetition.

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 good safety annotations, the description is adequate, but there is no output schema and no parameter documentation. The description does not mention return shape, pagination usage, or default limits, leaving meaningful gaps that the agent must infer.

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 explain ticket_number, limit, or offset beyond implying the ticket context. Parameter names like ticket_number and limit/offset are somewhat self-explanatory, but the description adds no semantics and fails to compensate for the missing schema descriptions, especially for pagination behavior.

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

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

The description states 'Lista as comunicações internas de um chamado' — a specific verb (List) + resource (internal communications) + scope (of a ticket). It also clarifies the visibility boundary ('notas visíveis só para a equipe, nunca para o solicitante'), which distinguishes it from sibling tools like tiflux_list_ticket_answers.

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 parenthetical provides clear context: these are team-only notes, never visible to the requester, so an agent knows when to use this tool to fetch internal notes. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description doesn't need to repeat those. The description adds the use-case context but doesn't disclose any additional behavior like pagination limits or result ordering. Since annotations cover the safety profile, this is adequate but not enriched.

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

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

Two short sentences efficiently convey the tool's purpose and usage. There is no filler or redundancy; every word adds value.

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

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

Given the tool has 4 parameters, no output schema, and only read-only annotations, the description is somewhat minimal. It explains the search functionality but omits details about return format, pagination behavior, or any constraints. For a simple search tool, it is adequate, but more completeness would be expected given the lack of output schema and parameter descriptions.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'por texto e por pasta', which maps to 'search' and 'knowledge_folder_ids', but does not explain 'limit' or 'offset'. This partially clarifies the parameters but leaves the pagination parameters undefined, which is a gap for a low-coverage scenario.

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

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

The description clearly states it searches knowledge base articles by text and folder, which is a specific verb+resource combination. It also differentiates from sibling tools by mentioning 'base de conhecimento' and the use case before answering a ticket, making the purpose 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?

It explicitly says to use this tool to find the procedure before answering a ticket, providing clear context for when to invoke it. However, it doesn't mention any exclusions or alternatives, though none seem needed given the sibling list has no other knowledge base search tool.

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

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

Annotations already indicate this is a read-only, idempotent, non-destructive operation. The description adds valuable context beyond this by stating that no admin privileges are needed and that the result is the requestor_id, which helps the agent understand its behavior and requirements.

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

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

The description is a single, focused sentence that immediately conveys the tool's action and purpose. It is concise with no redundant information, making it easy for an agent to quickly 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 tool has 6 optional parameters and no output schema. The description explains the core behavior (search by criteria, return requestor_id) and notes the no-admin requirement. It does not describe pagination or multiple results, but these are standard expectations for a search tool, so the description is mostly 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?

The schema has 6 parameters with 0% description coverage. The description explicitly mentions name, email, and telephone as search criteria, covering half of the parameters, but does not clarify the purpose of 'limit', 'offset', or 'can_open_ticket'. This partial compensation is adequate 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 clearly states the tool's function: searching for requesters by name, email, or phone, and returning the requestor_id for ticket opening. This distinguishes it from sibling tools like tiflux_list_clients by specifying its exact purpose and output.

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 is used to find the requestor_id needed to open a ticket, and notes that no admin profile is required. However, it does not explicitly mention alternatives or when not to use it, leaving some ambiguity among similar listing tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the organizational scope but does not explain pagination behavior, result size limits, or any other runtime behavior.

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

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

The description is a single concise sentence with no redundant wording. It is easy to parse and front-loads the essential purpose, though it could have included more useful details without becoming bloated.

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 list tool with no output schema and two undocumented pagination parameters, the description is too sparse. It does not mention pagination, return shape, or when this tool should be preferred over similar list tools, leaving meaningful gaps.

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

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

Schema description coverage is 0%, and the description does not explain the limit or offset parameters. The schema only provides types, so the description provides no additional meaning for these parameters.

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

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

The description clearly states the tool's function: 'Lista os grupos de atendentes da organização' (lists the organization's attendant groups). It uses a specific verb and resource, and it differentiates itself from siblings like tiflux_list_technical_users by focusing on groups rather than individual users.

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

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

No guidance is given about when to use this tool vs alternatives. The description does not mention exclusions, use cases, or relationships to sibling tools such as tiflux_list_departments or tiflux_list_technical_users.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds bulk support details (desk_ids, client_ids) and clarifies filtering, but does not disclose pagination behavior or result format. This adds some value beyond annotations without being exhaustive.

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

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

The description is concise, two lines, with front-loaded purpose and usage. It includes bulk support guidance without unnecessary detail. Every sentence adds value.

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

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

Given no output schema, the description need not explain return values. It covers purpose, filters, and bulk support. It lacks explicit mention of pagination parameters (limit/offset), but given the tool's simplicity and the presence of such parameters in the schema, it is reasonably complete for the intended use case.

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 description coverage, the description must compensate. It explains name, email, desk_id, client_id and their plural versions as filters, which adds meaning. However, limit and offset parameters are not described; they are likely pagination but the description doesn't explicitly mention them, reducing completeness for the 8 params.

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 technical users (atendentes) with filters by name, email, desk, or client, and specifically mentions its use case of resolving responsible_id for ticket assignment. This distinguishes it from sibling tools like tiflux_list_technical_groups or tiflux_list_requestors.

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 'Use para resolver o responsible_id ao atribuir um chamado', giving a clear when-to-use scenario. It lacks explicit exclusions or alternatives, but the provided context is sufficient to guide an agent.

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, idempotentHint=true, and destructiveHint=false, covering safety. The description adds the scoping detail that answers are visible to the requester, which helps differentiate from internal communications, but it does not disclose pagination behavior or response characteristics.

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, front-loaded sentence that clearly states the purpose without any filler. It is concise and efficient.

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

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

For a simple read-only list operation, the description captures the core purpose but omits details about optional parameters (limit/offset) and response format. With no output schema and incomplete parameter documentation, the description is somewhat incomplete but adequate for basic usage.

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 explain any of the three parameters. While ticket_number is implied by the tool name and description, limit and offset are not mentioned, leaving their purpose (likely pagination) undocumented.

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 ticket answers (communications visible to the requester), using a specific verb ('Lista') and resource ('respostas de um chamado'). It also distinguishes these from internal communications by specifying visibility to the requester, setting it apart from sibling tools like tiflux_list_internal_communications.

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

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

No explicit when-to-use or alternative guidance is provided. The description implies it is for retrieving requester-visible answers, which offers some context, but it does not state when to prefer this over other list tools or mention any prerequisites.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the bulk support detail (accepts user_ids for batched execution), which is useful beyond annotations. However, it does not disclose pagination behavior, return format, or any other side effects, so it only partially adds value beyond the structured metadata.

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

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

The description is extremely concise: two short sentences that convey the core functionality and one key feature (bulk support). No filler or redundancy, and the most important information is front-loaded. 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?

With 7 parameters, no output schema, and no parameter descriptions, the description is insufficient for an agent to fully understand invocation requirements and expected results. It does not mention the return structure, date filtering semantics, pagination defaults, or how ticket_number is used. The bulk support note is the only additional context, leaving significant gaps in operational understanding.

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

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

Schema description coverage is 0%, so the description must explain parameters. It only mentions user_ids for bulk execution, but does not explain limit, offset, start_date, end_date, user_id, or ticket_number. Parameter names are somewhat self-explanatory, but the description fails to provide necessary semantics for filtering and pagination, which is critical given the lack of schema documentation.

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

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

The description clearly states 'Lista os apontamentos de horas de um chamado' (List the hourly annotations of a ticket), specifying the verb (list) and resource (ticket appointments). It distinguishes from sibling tools like tiflux_list_appointments by scoping to a specific ticket, and mentions bulk support, making the purpose unambiguous.

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

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

The description does not explicitly state when to use this tool versus alternatives such as tiflux_list_appointments or tiflux_create_appointment. While the ticket-specific scope is implicitly clear, there is no guidance on filter options, typical use cases, or exclusions. No alternatives are mentioned, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds little beyond the basic listing behavior, with no mention of pagination, output format, or whether file metadata vs. content is returned.

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, front-loaded sentence that contains no filler or repetition. Every word contributes to defining the tool's purpose.

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

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

For a simple read-only listing tool, the core purpose is understandable, but without an output schema or parameter descriptions, the agent lacks details about pagination behavior and return structure. It is minimally adequate but leaves meaningful 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 schema has no parameter descriptions and the description covers 0% of the parameters. 'Chamado' implies the ticket_number parameter, but limit and offset are completely unexplained, and the anyOf type flexibility for ticket_number is not clarified.

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

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

The description uses a specific verb ('Lista') and a clear resource ('arquivos anexados a um chamado'), and the resource type distinguishes it from sibling tools like tiflux_list_ticket_answers and tiflux_get_tickets. It clearly states what the tool does with no 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 description does not state when this tool should be used over alternatives or mention any prerequisites or conditions. It only implicitly indicates use when ticket attachments need to be listed, without explicit guidance or exclusions.

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, idempotentHint, and non-destructive behavior. The description adds valuable context about total_items reflecting the real filter total, which is important for pagination and counting. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences, front-loaded with the core action, and contains no filler. It efficiently communicates both the purpose and one critical behavioral note.

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 16 parameters and no output schema, the description is insufficient. It only mentions total_items but not the response structure, how filters combine, pagination semantics, or the meaning of obscure parameters like group_by and date_type. Agents are left with many ambiguities.

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 0%, and the description only vaguely lists filter categories like 'situação, mesa, cliente' without mapping them to specific parameter names. Many parameters (limit, offset, group_by, date_type, priority_ids, requestor_email, services_catalogs_item_ids) are entirely unaddressed, leaving significant meaning 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 clearly states 'List tickets with filters' and enumerates the filter dimensions (situação, mesa, cliente, etc.), making the tool's purpose explicit. It does not explicitly distinguish itself from sibling tiflux_get_tickets, but the resource and verb are 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?

It gives a specific usage hint: use the returned total_items before concluding any count. However, it lacks guidance on when to prefer this over similar tools like tiflux_get_tickets or other list tools, and no exclusions are mentioned.

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, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds meaningful context about what the response contains (name, email, profile, feature flags) and the token's permission scope. However, it does not describe output format, potential missing fields, or any authentication nuances beyond what the annotations already imply, so it adds value but remains basic.

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

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

The description is two concise sentences, front-loaded with the key output fields ('nome, e-mail, perfil, feature flags') and followed by a clear use case. Every phrase 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?

This is a low-complexity, parameterless, read-only tool with strong annotations. The description fully covers what data is returned and why an agent would invoke it: to confirm identity and permission scope. No output schema exists, but the listed fields are sufficient for the tool's simple purpose.

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, and schema coverage is 100%, so there is no parameter ambiguity to resolve. The baseline for 0-parameter tools is 4 because the description need not compensate for missing parameter details. The description focuses on return data, which is appropriate for a parameterless introspection endpoint.

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 identifies the tool's purpose: it returns data about the token owner's user (name, email, profile, feature flags). While it lacks a direct verb like 'returns' or 'retrieves,' the noun phrase 'Dados do usuário dono do token' makes the resource unambiguous. It also differentiates itself by adding the use case of confirming whose behalf actions are recorded, which separates it from sibling auth tools like authenticate and connect.

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 it: 'Use para confirmar em nome de quem as ações serão registradas e qual o escopo de permissão da chave.' This gives clear context for invocation, though it does not explicitly name alternatives or exclusion cases. Given the tool's simple self-inspection role, this is adequate and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Relatório' is consistent with a safe read operation. The description adds little beyond that, such as pagination behavior, date requirements, or the meaning of tickets_list, but the annotation coverage lowers the 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 a single, well-structured sentence with no filler. It front-loads the core concept and each phrase adds meaningful scoping or filter 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?

With 8 optional parameters, no output schema, and no parameter descriptions, the one-line overview is sufficient for selecting the tool but not for confidently invoking it. Important gaps remain around pagination parameters, the tickets_list boolean, and what the returned report structure looks like.

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 for the 8 parameters. It partially does by mapping 'período' to start_date/end_date and 'responsável', 'departamento', and 'grupo de atendentes' to the ID array parameters, but it leaves limit, offset, and tickets_list unexplained.

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 defines this as a ticket satisfaction/feedback report scoped by date range and filters by responsible person, department, or attendant group. It distinguishes the tool from sibling ticket list/get tools, though it lacks an explicit verb and is largely a restatement of the tool name.

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 report context is clear: use this for satisfaction feedback reporting over a period, optionally filtered by responsible, department, or technical group. It does not explicitly name alternatives or exclusions, but the described scope is specific enough to imply the intended usage.

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

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

Annotations include readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds context by specifying partial update behavior and bulk support for certain fields. It does not contradict annotations. The description explicitly mentions the bulk fields, which is a behavioral trait beyond what annotations provide. It doesn't mention error conditions or permissions, but for an update tool with no destructive hint, this is adequate.

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. It has a clear main sentence, a key usage tip, and a separate paragraph for bulk support. Every sentence adds value. No 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 tool has 21 parameters, no output schema, and minimal annotations, the description provides essential information: what to update, how to specify stage/responsible, and bulk capability. It could add more about the response format or error handling, but since there's no output schema, the agent would need to infer that from other tools or documentation. The description covers the critical aspects sufficiently for a complex update 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%, so the description must compensate. The description explains the semantics of key parameters: stage_id for moving stages, responsible_id for transferring responsibility, and lists all the bulk fields (client_ids, desk_ids, etc.). It also clarifies that only fields to be changed should be sent, which helps with the 21 parameters. However, it doesn't explain every parameter, but the list of common ones is sufficient for an agent to infer the rest.

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 'Atualiza um chamado existente' (updates an existing ticket), which is a specific verb+resource combination. It distinguishes itself from sibling tools like tiflux_create_ticket, tiflux_close_ticket, and tiflux_cancel_ticket by focusing on updates. The scope is clear: it updates an existing ticket and supports partial updates ('Envie só os campos a alterar').

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 provides clear guidance on when to use this tool: to update an existing ticket, with explicit instructions on how to move stages and transfer responsibility. It implicitly differentiates from creation and lifecycle tools by saying 'existing ticket.' However, it does not explicitly mention when NOT to use it or name alternative tools for cases like closing or canceling, but the context of siblings makes this clear enough.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is known. The description adds context about what the returned state includes (installed MCPs, connection status, accounts, catalog tool counts), which is useful but does not disclose additional behavioral aspects like performance, authentication prerequisites, or possible failures. It 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 a single sentence, front-loaded with the primary action ('Returns the current toolkit state'), and lists the key pieces of returned information concisely. There is no fluff or repetition.

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 zero parameters and no output schema, the description fully covers what the tool does and returns. It enumerates all relevant aspects of the toolkit state and does not omit any obvious details. The tool is simple, and the description is 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 tool has zero parameters, so the schema is fully covered. The description adds no parameter-specific information, but none is needed. Baseline for 0 params is 4, and this is appropriate.

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

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

The description states a specific verb ('Returns') and a clear resource ('current toolkit state') with enumerated details: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes it from all sibling tools (e.g., tiflux_* actions, authenticate, connect) that focus on specific operations rather than overall state.

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: it is a read-only informational tool for inspecting the toolkit state. The context is clear—use it when you need to see installed MCPs and their connectivity—but it does not explicitly mention when not to use it or point to alternatives. Since it is a unique tool in the sibling set, this is adequate.

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