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

Annotations already declare it as readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying the specific fields returned (nome, email, telefone, empresa/customerCode, cargo), which provides beyond-annotation context. No contradictions.

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

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

The description is two concise sentences: first summarizing the data, second giving the endpoint. It is front-loaded with key information and contains no unnecessary words.

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

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

With no parameters, annotations covering safety, and an output schema present, the description sufficiently explains the return fields. It could mention potential conditions or errors, but the output schema likely covers structure. Overall complete for a read-only contact info 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 with 100% schema coverage. The description adds no parameter information, but for a no-parameter tool, baseline is 4 as per guidelines.

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

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

The description clearly states that the tool returns the logged-in contact's data (name, email, phone, company, role) and provides the endpoint. It distinguishes from siblings like totvs_whoami by specifying the fields returned and the context of the logged-in contact.

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 provide when to use this tool versus alternatives. It only describes what it returns. While it is a simple zero-parameter tool, guidance on when to prefer it over similar tools like totvs_whoami is lacking.

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. The description adds the specific return fields and endpoint, which is helpful but does not disclose additional behavioral traits like performance, rate limits, or error handling.

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 no superfluous information. It front-loads the main action and provides necessary details efficiently.

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

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

For a tool with no parameters and no output schema, the description covers the return fields and endpoint. It is mostly complete, but lacks information about output format or potential errors, which would enhance completeness.

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

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

No parameters exist, so the description does not need to explain them. It compensates by specifying the output fields. With 100% schema coverage and 0 parameters, baseline is 4, and the description meets expectations.

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 departments/service areas with specific fields (key, label, nome, tags). It includes the endpoint, making the purpose unambiguous and distinct from sibling tools that focus on tickets or 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?

The description implies usage for retrieving department listings but provides no explicit guidance on when to choose this tool over siblings like totvs_contato or totvs_tickets_listar. Contextual usage hints are absent.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by specifying the exact output (unread count) with an example, and clarifies it is user-specific. No contradictions.

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

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

The description is a single concise sentence with an example, front-loading the key information without any wasted words.

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

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

Given the tool's simplicity (no parameters, straightforward output), the description is complete. It includes an example output and clarifies the scope (user in the portal). The existence of an output schema further supports completeness.

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

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

There are no parameters, and schema coverage is 100%. The description does not need to add parameter semantics, and it appropriately provides an example output to clarify the return format.

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

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

The description clearly states the tool returns the number of unread notifications for the user in the portal, with an example output format. It distinguishes from siblings, none of which relate to notification counts.

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

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

No explicit guidance on when to use this tool versus alternatives. The sibling list implies differentiation (other tools handle tickets, contacts, etc.), but the description does not provide usage context 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, so the main safety profile is covered. The description adds that results include attachments and sort order behavior but does not mention pagination or limits despite the 'page' parameter, leaving some behavioral gaps.

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, compact paragraph that front-loads the main purpose. Backticks for parameters aid readability. It is efficient but lacks explicit structure like bullet points.

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

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

Given the presence of an output schema and annotations, the description does not need to cover return values or safety. However, it misses the 'page' parameter and does not explain pagination behavior. For a simple list tool, the description is nearly complete but has a clear gap.

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

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

With 0% schema description coverage, the description must compensate. It explains 'ticket_id' as the ticket number and 'sort_order' as DESC/ASC with examples, but it omits the 'page' parameter entirely. This partial coverage is adequate for core usage but incomplete.

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 retrieves comments/status updates of a ticket with attachments. It uses specific verbs ('Comentarios/andamentos') and resource ('ticket'), and it distinguishes from siblings like totvs_ticket_detalhe that likely provide ticket details instead of comments.

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

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

The description explains the meaning of 'ticket_id' and 'sort_order' but does not provide explicit guidance on when to use this tool versus alternatives like totvs_ticket_detalhe or totvs_tickets_filtrar. No when-not-to-use or context for selecting among siblings is 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?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds transparency about the returned information (e.g., solicitante, colaboradores, status), which is useful beyond annotations. No contradiction.

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

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

The description is a single sentence plus a parameter clarification, with no wasted words. It is front-loaded with the key information and efficiently communicates 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?

Given the tool's simplicity (1 parameter, idempotent read), the description adequately covers what the tool does. The presence of an output schema means return values don't need elaboration. The description lists enough details to understand the scope.

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

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

The input schema has 0% description coverage for the parameter ticket_id, but the tool description explains what ticket_id is and provides an example format ('ex: '29586485''). This adds semantic meaning beyond the schema's bare property definition.

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 provides 'complete detail of a ticket' and lists specific data fields (requester, collaborators, organization, status, product/module). This distinguishes it from sibling tools like totvs_ticket_comentarios (comments) and totvs_tickets_listar (list) by emphasizing completeness.

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 implicitly suggests use when full ticket details are needed, but it does not explicitly state when to use this tool versus alternatives (e.g., for comments or list of tickets). No exclusions or when-not-to-use guidance is provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds that it returns items with tags and clarifies parameter behavior, but does not reveal additional behavioral traits beyond what annotations convey.

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

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

The description is compact—four bullet points—with the main purpose front-loaded. Every sentence adds value, and there is no extraneous or redundant content.

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

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

Given the tool has four parameters, no output schema, and annotations providing safety hints, the description sufficiently covers what the tool does and its return type (items with tags). It could mention pagination details more explicitly, but it's largely 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?

With 0% schema coverage, the description fully explains all parameters: tipo as 'product/module/routine', filtro as search text (empty = defaults), and pagination via page/page_size. This adds substantial meaning beyond the schema.

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

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

The description clearly states the tool provides 'Opcoes do catalogo para os filtros de totvs_tickets_listar', specifying the verb (options) and resource (catalog for filters). It also explains that it returns items with tags, distinguishing it from sibling tools like totvs_ticket_detalhe or totvs_contato.

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 in conjunction with totvs_tickets_listar for filtering, but does not explicitly state when to use or avoid this tool versus alternatives. No when-not or alternative tool guidance is provided.

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

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

Beyond annotations (readOnlyHint, etc.), the description adds key behavioral traits: ticket_views are disjoint sets, organization_ids default behavior with caveats, keywords search across multiple fields, and status treatment of empty/null. 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 well-structured with a summary line followed by bullet points for each parameter. It front-loads the main purpose. While somewhat long due to 15 parameters, every sentence adds value. Minor redundancy could be trimmed but overall efficient.

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

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

Given the high complexity (15 parameters, 0% schema coverage, no enums) and existence of output schema, this description is remarkably complete. It covers parameter semantics, behavioral nuances, caveats, and sibling references. The only missing detail is exact date format, which is noted as to be confirmed.

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 fully compensates by explaining each parameter's meaning, default behavior, and cross-references to other tools. For example, keywords matches number/title/content, status uses values from totvs_tickets_status, tags from catalog, and ticket_views semantics are detailed. Only minor gap is date format (noted as to confirm).

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

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

The description explicitly states it 'Busca/lista tickets de suporte TOTVS por ORGANIZACAO' with filters and pagination. This clearly identifies the tool's function and distinguishes it from siblings like totvs_ticket_detalhe or totvs_ticket_comentarios.

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

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

The description provides explicit guidance: it searches across organizations, not just owned tickets; explains how organization_ids work and warns about primary org being empty; details ticket_views as disjoint sets requiring union for full coverage; and references sibling tools for filter values (totvs_tickets_status, totvs_tickets_filtros, totvs_whoami).

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 clear. However, the description adds no additional behavioral context such as ordering, caching, or authentication requirements, which would be useful 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 a single sentence of 10 words, frontloaded with the key action and resource. Every word is necessary; there is no redundancy or extraneous information.

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

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

Given the tool's simplicity (no parameters, no output schema, and annotations covering safety), the description is minimally complete. It states what the tool returns ('motivos de priorizacao'), but lacks details on the return format or whether the list is static, limiting an agent's ability to fully anticipate the output.

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% (vacuously). The baseline score for 0 parameters is 4, and the description adds no parameter-specific info since none exist. It is adequate for a parameterless 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 that the tool lists priority reasons (motivos de priorizacao) used in the portal, using a specific verb ('Lista') and resource. It is easily distinguishable from sibling tools like totvs_tickets_listar or totvs_tickets_status.

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

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

The description provides no guidance on when to use this tool versus alternatives, such as when filling a priority field in a ticket or filtering. No when-not-to-use or context is 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?

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds that the output is a set of value+label pairs, which is key behavioral information beyond annotations.

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

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

A single sentence with an example, front-loaded with the core purpose. No unnecessary words.

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

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

Given no parameters and a simple output format, the description fully explains the tool's functionality and how to use its result. It is complete for an enumeration list tool.

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

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

No parameters exist, so baseline 4 applies. The description does not need to add param info, and the schema is fully covered (100%).

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 official statuses (value+label) for use in the `status` filter of `totvs_tickets_listar`, with an example. It distinguishes from siblings like `totvs_tickets_filtros` by specifying the exact filter and providing sample data.

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

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

The description explicitly tells the tool's purpose: to provide valid status values for filtering in another tool. It does not include when-not-to-use or alternatives, but for a simple list, the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context beyond annotations, such as the minimum 3-character requirement for 'termo' and the default behavior of 'organization_ids' (None/[] means all visible orgs). This compensates well.

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

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

The description is very concise: one sentence stating purpose followed by two bullet points for parameter details. Every sentence adds value, and the structure is front-loaded with the main 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?

Given the tool has only 2 parameters and no output schema, the description adequately covers input constraints and purpose. However, it does not mention response format or pagination, which might be helpful but is not critical for a simple search tool.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters: 'termo' has a 3-character minimum, and 'organization_ids' can be None/[] for all visible organizations. This provides essential meaning beyond the raw schema.

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

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

The description clearly states the tool searches for Zendesk users/contacts by name/email, optionally scoped by organization, and is useful for finding a requester_id. It distinguishes itself from sibling tools that deal with tickets, departments, etc., though it doesn't explicitly differentiate from the very similar sibling 'totvs_contato'.

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 specific use case ('Util pra descobrir o requester_id de alguem') and explains the optional organization scoping. It lacks explicit when-not-to-use or alternatives, but the context provided is clear enough for an agent to decide when to invoke it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety profile is clear. Description adds behavioral context: the tool derives data from the token and returns specific fields (userId, customerCode, organizations, token validity), which goes beyond annotations but does not contradict 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?

Two short sentences in Portuguese: first states the tool's function, second provides usage guidance. Every word earns its place; no redundancy.

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

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

Given no parameters and the presence of an output schema, the description sufficiently covers the tool's purpose and output (enumerating key fields) and provides actionable use guidance. It is complete for a simple identity retrieval tool.

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

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

Tool has zero parameters, so baseline is 4. No parameter semantics needed; description adds no parameter info but that is acceptable.

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

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

Description clearly states the tool retrieves the logged-in user's identity (userId, customerCode, organizations, token validity) from the TOTVS portal token. It explicitly directs to use it for discovering available organization_ids and customerCode, which distinguishes it from sibling tools dealing with contacts, departments, tickets, etc.

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

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

Description explicitly tells when to use: to discover organization_ids/customerCode. It provides clear context for an identity lookup tool, and no alternative is needed given its specific purpose.

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