AdvBox

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

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description does not need to restate those. It adds useful context about following the official API and using 'extra' for unspecified fields, but it does not disclose side effects, validation behavior, or error conditions.

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 states the purpose and then provides essential field guidance. Every word contributes value, with no repetition 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?

There is no output schema, so the description should clarify return values or expected behavior, but it does not. It also leaves out required fields, validation rules, and concrete examples, relying on 'official API' without providing those details. The 'extra' catch-all helps but is not enough for a create operation.

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

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

Schema description coverage is 0%, so the description must compensate. It lists example fields (name, type, cpf/cnpj, email, phone) and mentions sending the rest via 'extra', which adds some meaning. However, it does not explain formats, requiredness, mutual exclusivity of cpf/cnpj, or how 'extra' should be structured.

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 'Cria um novo contato/cliente' (creates a new contact/customer), using a specific verb and resource. It is easily distinguished from sibling tools like advbox_get_customer, advbox_list_customers, and other create_* 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 usage is implied by the verb 'Cria' and the resource 'contato/cliente', but there is no explicit guidance about when to choose this over alternatives or any exclusions. It does not mention when not to use it or compare with sibling create 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 indicate readOnlyHint=false and destructiveHint=false, implying a non-read operation without destructive effects. The description adds that fields follow the official API and that settings are needed for IDs, but it does not disclose side effects, reversibility, or authentication requirements beyond what annotations imply. It adds minimal context beyond annotations.

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

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

The description is a single sentence with no fluff, front-loading the action. It efficiently includes a pointer to settings and a note about named fields and extra. However, it lacks structured breakdown, but given its brevity, it earns a high score.

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

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

For a lawsuit creation tool with nested objects and no output schema, the description is insufficient. It does not explain required fields beyond referencing the official API, nor does it mention response format or potential pitfalls. It relies heavily on external settings without detailing how to use them 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?

Schema description coverage is 0%, so the description carries the burden. It mentions 'campos nomeados + extra' and points to settings for IDs, but it does not explain the meaning of 'number' or the structure of 'extra'. The guidance is too vague to compensate for the lack of schema descriptions.

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

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

The description clearly states the action: 'Cria um processo' (Creates a lawsuit), using a specific verb and resource. It distinguishes from sibling create tools by focusing on 'processo' (lawsuit) and references the official API and settings for IDs.

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

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

The description instructs to use advbox_settings to discover type/responsible IDs, providing a clear preparatory step. It implies create vs. update context through the tool name and sibling list, though it doesn't explicitly mention when not to use it. The guidance to send via named fields plus extra is actionable but could be more explicit about 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 annotations already indicate readOnlyHint=false, and the description's 'Adiciona' merely confirms a write operation without adding new behavioral context. Missing details include whether duplicate movements are allowed, what side effects occur, authorization requirements, or what response 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 concise and front-loaded, with no filler words. Its brevity is partly responsible for leaving important details unstated, but the structure itself is efficient for a simple creation tool.

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

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

With no output schema, no parameter descriptions, and a vague reference to the official API for the process link, the description is insufficient for reliable invocation. The tool is one of many similar create_* siblings, so more detail about required fields and expected behavior is needed.

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 only vaguely says to link the process via an official API field and use 'extra' for remaining fields. It does not name the concrete field names or specify the required shape of 'extra', leaving the agent unable to construct a correct invocation confidently.

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 adds a manual movement to a process ('Adiciona uma movimentação manual a um processo'), which distinguishes it from sibling create tools like advbox_create_customer or advbox_create_lawsuit. However, the critical process-link field is only referenced as 'campo conforme a API oficial', leaving the exact binding mechanism underspecified.

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 given about when to use this tool versus alternatives, nor are any exclusions or prerequisites mentioned. Sibling tools such as advbox_lawsuit_movements or advbox_last_movements could serve as read/alternative paths, but no comparisons or usage context are 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 indicate a non-read-only, non-destructive operation, and the description aligns by saying 'Cria um novo post/anotação'. It adds a small hint about official API field mapping via named fields + `extra`, but does not disclose side effects, permissions, error behavior, or what the response contains.

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 short sentences and front-loads the primary action first. Every phrase earns its place, though it is slightly underspecified for parameter-rich contexts.

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

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

With no output schema and sparse parameter semantics, the description should clarify return values, required fields, or failure modes; it does none of that. The tool is simple, but the description still leaves too much unspecified for confident invocation.

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

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

Schema description coverage is 0%, so the description must compensate; it only says fields are 'conforme a API oficial via campos nomeados + `extra`' without explaining what `text` means or how to populate `extra`. This leaves the agent with almost no guidance beyond the raw property names.

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 'Cria um novo post/anotação' clearly states the action (create) and the resource (post/note), which directly distinguishes it from sibling create_* tools for customers, lawsuits, movements, and transactions. It is specific and unambiguous about the tool's core purpose.

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

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

Usage is implied by the creation verb and resource name, but the description does not explicitly state when to prefer this tool over alternatives or mention any prerequisites/exclusions. It is minimally sufficient, not more.

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

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

Annotations only provide readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description adds no behavioral context such as authentication requirements, persistence side effects, validation behavior, or response handling. 'Campos conforme a API oficial' is parameter-related, not a behavioral disclosure.

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

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

The description is a single concise sentence that front-loads the core purpose and then adds field mapping context. Every phrase adds value 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 create operation with no output schema and sparse annotations. The description leaves significant gaps: no required fields, no field value constraints, no creation-side effects, and no guidance on handling API-specific extra fields. It is minimally viable but incomplete for reliable invocation.

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

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

The schema has 0% description coverage and no enums or required fields. The description mentions example fields (type, value, due_date) and hints that `extra` holds additional official API fields, and 'receita ou despesa' gives a clue about type values. However, it does not explain formats for value/due_date, constraints, or how extra merges with named fields.

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

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

The description clearly states 'Cria um lançamento financeiro (receita ou despesa)' – a specific create action on a financial entry/transaction. This distinguishes it from sibling create tools like advbox_create_customer or advbox_create_lawsuit, and from advbox_get_transaction/advbox_list_transactions.

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

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

Usage is implied by the verb 'Cria' and the resource, and siblings include update/get/list variations, but the description does not explicitly say when to use this tool versus alternatives or when not to use it. There is no mention of prerequisites, exclusions, or preferred 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 covered. The description adds no additional behavioral details such as pagination, filtering behavior, or return format, but it 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, front-loaded sentence with no filler. Every word adds value: 'Lista aniversariantes' states the action and resource, and the parenthetical clarifies the 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?

There is no output schema, and the tool has three undocumented parameters including a nested 'query' object. The description does not explain pagination, filtering, or what data is returned, leaving meaningful gaps for an agent trying 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 carries the burden of explaining parameters, but it does not mention 'page', 'page_size', or 'query' at all. 'page' and 'page_size' are somewhat inferable by name, but the 'query' object is completely opaque and may accept arbitrary filters.

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' (lists) and identifies the resource as 'aniversariantes' (birthday celebrants), clearly distinguishing this from sibling tools like advbox_list_customers or advbox_get_customer. The parenthetical 'para campanhas de relacionamento' adds useful purpose context.

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

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

The phrase 'para campanhas de relacionamento' indicates the intended use case for relationship campaigns, which is clear contextual guidance. It does not explicitly mention when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing bulk execution capability ('accepts ids for batched execution'), which is not captured in annotations and is useful for the agent. 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 extremely concise: two sentences, front-loaded with the main purpose and then the bulk note. Every word earns its place, with no redundancy or filler. Ideal structure for quick parsing.

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

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

Despite being a get-by-ID tool, the presence of a 'query' parameter adds complexity that the description does not address. There is no output schema, so the agent does not know what 'dados completos' includes. The bulk support note lacks details (e.g., limits, format of ids). The description is too sparse for a tool with three parameters including an object.

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 the parameters. It partially explains 'id' (single lookup) and 'ids' (bulk), but completely ignores the 'query' object parameter, which is a significant gap. The agent cannot infer what 'query' expects or how it relates to the other 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 retrieves complete contact data by ID, with a specific verb ('Busca') and resource ('dados completos de um contato por ID'). It distinguishes itself from sibling tools like advbox_list_customers (which likely lists many) and advbox_customers_birthdays, making its 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 implies usage for fetching a contact by ID, and the mention of bulk support suggests using it when multiple IDs are available. However, it does not explicitly state when to prefer this over alternatives like advbox_list_customers or exclude cases (e.g., when only partial data is needed). Guidance is present but not fully articulated.

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 idempotentHint=true, so description doesn't need to restate that. The description adds the bulk support behavior ('accepts ids for batched execution'), which is beyond annotations. It doesn't contradict annotations. However, it doesn't disclose details like error handling or return format, but with read-only annotation already provided, the bar is lower. So 4 is justified.

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 short: two sentences. It is front-loaded with the main purpose. The bulk support is added as a second sentence. No unnecessary words. It earns its place. Slightly under-specified, but for its length, it's concise. Score 4.

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 3 parameters, one required, and one parameter is a nested object (query) with zero explanation, the description is incomplete. It doesn't mention what the query object does, nor does it provide details about the response (no output schema). For a 'get' tool with batch support and a query object, the agent would need more info. Also, the bulk support is mentioned but not elaborated (e.g., how errors are handled). So completeness is low. Score 2.

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%, meaning the description provides no parameter explanation. The description only mentions 'id' and 'ids' for bulk support, but the schema shows a 'query' parameter as an object, which is completely unexplained. With zero coverage, the description should compensate, but it only covers id/ids, not query. This is a significant gap because the query object likely allows complex filtering, which the agent needs to know. So score 2.

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 tool fetches a lawsuit by ID and returns complete data. It also mentions bulk support. The purpose is clear and distinct from sibling tools like advbox_list_lawsuits (which lists multiple) and advbox_get_customer (different resource). Slight deduction for not explicitly contrasting with sibling list/get tools, but the verb 'Busca' (searches/fetches) and 'por ID' specify the operation.

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: use this tool to fetch a single lawsuit by ID, with option for batch via 'ids'. It does not explicitly say 'when not to use' or mention alternatives, but within the sibling set, it's clear that this is the get-by-ID tool. Sibling names like advbox_list_lawsuits suggest alternatives, but not explicitly stated in the description. So guidance is implied 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's burden is lightened. It adds useful context about batched execution, but does not disclose return format, error behavior, or any rate/access limits.

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 short sentences, front-loads the core purpose, and adds bulk support as a second item. No redundant content is present.

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 three parameters including an unexplained 'query' object and no output schema. The description covers only the basic ID lookup path, leaving the semantics of the 'query' parameter and expected return behavior unstated, which is incomplete for a full 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?

The description adds meaning for 'id' and 'ids' ('by ID', 'batch execution'), but the schema has 0% description coverage and the 'query' object parameter is completely undocumented. The description does not adequately compensate for the low schema coverage across all three 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 with a specific verb and resource: 'Detalha uma transação por ID' (details a transaction by ID). It also distinguishes this from sibling list operations by focusing on retrieval by specific ID, and explicitly mentions bulk support via 'ids'.

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

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

The description clearly implies when to use this tool: when you have a transaction ID and need its details, especially with batch support. It does not explicitly mention alternatives or exclusions, but the purpose wording makes the context obvious relative 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 and destructiveHint=false, so the safety profile is covered. The description adds that it provides a recent summary ('resumo recente'), which gives some insight into the response content but not into behaviors like pagination or query handling. Minimal added value beyond annotations.

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

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

Single clear sentence, no redundancy, front-loaded. Efficiently states purpose.

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

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

With a nested object parameter and no output schema, the description is too sparse. It doesn't explain the query object structure or expected response format, and given multiple related tools, more context is needed for correct 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 mention any parameters (page, query, page_size). The query object is completely unexplained, leaving the agent without guidance on how to construct valid inputs.

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 states 'Última atualização de cada processo (resumo recente).' which clearly indicates it retrieves the last update for each process. However, it does not explicitly distinguish from sibling tools like advbox_lawsuit_movements which might also provide movement data, so it's clear but not fully differentiated.

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

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

No guidance on when to use this tool versus alternatives such as advbox_lawsuit_history or advbox_lawsuit_movements. The description simply states what it does without context on prioritization 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'complete history' scope and bulk execution behavior, but says nothing about pagination, filtering, or return shape beyond the schema fields.

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

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

The description is two short sentences, front-loaded with the primary purpose and followed by a key capability. There is no filler or repetition, making it highly concise and 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?

Despite having pagination parameters, a nested query object, bulk mode, and no output schema, the description does not explain return values, query filter usage, pagination behavior, or how bulk results are structured. Annotations cover safety only, leaving the description incomplete for effective tool selection.

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. It only clarifies lawsuit_ids for bulk execution and implies lawsuit_id is the key identifier; page, page_size, and query remain unexplained and their semantics are not compensated for.

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

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

The description identifies the resource ('processo') and scope ('Histórico completo'), making it clear this tool retrieves the full history of a lawsuit. 'Bulk support' further distinguishes it from single-item getters. However, it lacks an explicit verb like 'get' or 'list', and does not clearly differentiate from sibling tools such as advbox_lawsuit_movements or advbox_last_movements.

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 bulk support mention provides some usage context: the tool can handle multiple lawsuit_ids in one call. There is no explicit guidance on when to prefer this over the movement-specific siblings, and no exclusion criteria or alternatives are named.

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 safe read nature is established. The description adds the bulk execution behavior via lawsuit_ids, which is useful context. However, it does not disclose pagination behavior or output format, so value beyond annotations is limited.

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 consists of two concise sentences, front-loading the primary purpose. Every phrase contributes, and the bulk support note is valuable without adding noise.

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 5 parameters and nested objects, yet the description omits details on filtering (query), pagination (page/page_size), and the return structure. Without an output schema, this leaves the agent guessing about expected results. The description does not adequately support the tool's complexity.

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

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

With 0% schema description coverage, the description must compensate but only mentions lawsuit_ids for bulk support. It leaves page, query, page_size, and lawsuit_id semantics unexplained, including the nested query object. This is insufficient for an agent to construct correct calls.

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

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

The description clearly states 'Lista todas as movimentações de um processo' (lists all movements of a lawsuit), using a specific verb and resource. The scope ('todas') distinguishes it from siblings like advbox_last_movements, which implies a limited set. The bulk support note adds further 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 provides no guidance on when to choose this tool over siblings like advbox_last_movements or advbox_lawsuit_history. It only mentions bulk execution capability, which is a feature, not a usage criterion. No exclusions or alternatives are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds little behavioral context beyond the basic listing behavior; it does not mention pagination behavior, query semantics, or result shape. There is no contradiction with annotations, but minimal added value.

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 with no filler; the examples are useful and the syntax is clean. It is slightly under-specified for the number of parameters, but the conciseness itself is strong.

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, a nested `query` object, no output schema, and zero schema param descriptions, the tool needs richer contextual guidance. The description only covers rough filter intent and omits pagination behavior and query object structure, making it only minimally complete.

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

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

Schema description coverage is 0%, so the description needed to compensate. It does name some filter fields (name, cpf, cnpj, email) and points to `query`, which provides partial clarity, but it leaves page/page_size and the structure of the `query` object 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 uses a specific verb 'Lista' with a clear resource 'clientes/contatos' and mentions advanced filtering, which makes the tool's purpose immediately obvious. It is naturally distinguished from single-record siblings like advbox_get_customer and from other 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 usage for listing/filtering customers, but it does not explicitly state when to use this tool versus alternatives, nor does it explain the relationship between the separate filter params and the `query` object. 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, and destructiveHint=false, covering the behavior those hints describe. The description adds useful context about the 22+ filters and common query keys, but it does not disclose pagination behavior, result limits, or how multiple filters combine.

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 with no filler or repetition. It efficiently communicates what the tool does and the main filtering mechanism.

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

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

For a read-only list/search tool with annotations and 7 parameters, the description gives a reasonable overview but omits pagination details, the full filter list, and any expected output shape. The presence of page and page_size parameters makes the absence of pagination guidance more noticeable.

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 partially compensates by listing common fields inside the query object: numero, parte, cpf, cnpj, responsavel, status, comarca, uf, datas. However, it does not explain top-level parameters cpf, cnpj, number, status, page, page_size, or how they relate to the query object.

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/busca processos' (lists/searches lawsuits) and mentions the resource and filtering capability, distinguishing it from siblings like advbox_get_lawsuit, create tools, and movement/history tools. It lacks an explicit comparison to alternatives, so it does not reach the highest bar.

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

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

The phrase 'Filtros comuns via query' implies the intended use for searching/filtering lawsuits by number, party, CPF, CNPJ, status, etc. However, it does not provide explicit when-to-use guidance, exclusions, or a pointer to advbox_get_lawsuit for retrieving a single known lawsuit.

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 readOnly, idempotent, and non-destructive, so the description doesn't need to repeat these. It adds the clarification that 'annotations' means 'tasks/notes,' which is helpful, but it doesn't disclose other behaviors like pagination 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?

The description is one short, front-loaded sentence that states the purpose directly. No wasted words and all content is relevant. It earns its place.

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

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

The tool has 3 parameters and no output schema, yet the description only states the general purpose. It omits details about pagination, the query object's structure, and what the response contains. With annotations covering safety but not usage details, the description is insufficient for effective use.

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

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

The schema description coverage is 0%, and the description provides no explanation of the parameters (page, query, page_size). With zero coverage, the description must compensate but fails entirely to explain what these parameters do or how the query object should be structured.

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 posts and annotations (tasks/notes), using a specific verb ('List') and a distinct resource. This distinguishes it from sibling list tools for customers, lawsuits, and transactions.

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

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

The description provides no guidance on when to use this tool versus alternatives. It merely states what it does without mentioning contexts, exclusions, or alternatives. For a tool among many list operations, explicit usage context is missing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds the filter scope (date/type/status) but does not disclose pagination behavior, result shape, or any other runtime characteristics beyond what annotations 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 a single, front-loaded sentence with no redundant words or filler. It efficiently communicates the core purpose and a key feature.

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 7 parameters, no output schema, no enum constraints, and no schema-level descriptions, the one-line description is not sufficient. It omits pagination semantics, query object structure, return value expectations, and further filter details, leaving the agent with significant ambiguity for correct invocation.

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

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

With schema description coverage at 0%, the description needed to compensate, but it only mentions that the 'query' object holds filters. It does not clarify the meaning of the other six parameters, such as page, page_size, start_date, end_date, type, and status, and may even confuse by implying filters are only inside 'query' when several top-level fields also represent filters.

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 a specific action (list) on a specific resource (financial transactions) and mentions the available filter dimensions (date/type/status). This distinguishes it from sibling tools like advbox_get_transaction (singular retrieval) and advbox_list_customers/advbox_list_lawsuits/advbox_list_posts (different resource types).

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 multiple financial transactions with optional filters, and contrasts implicitly with get_transaction. However, it provides no explicit guidance on when to prefer this tool over alternatives, no pagination notes, and no exclusions 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the useful behavioral detail about bulk execution through lawsuit_ids. It does not, however, describe pagination behavior, result shape, or how the listing behaves when no parameters other than the required one 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 extremely concise: two sentences, the first stating the core purpose and the second highlighting bulk support. It is front-loaded and contains no redundant wording, making it easy to parse quickly.

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

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

Although the annotations mitigate safety concerns, the tool has 5 parameters, a nested object, and no output schema. The description does not explain the query object, pagination, expected response structure, or how these publications differ from other legal-case listing tools. An agent would lack sufficient context to invoke the tool with meaningful 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%, meaning the description must carry the burden of explaining parameters. The only parameter semantics explicitly mentioned is that lawsuit_ids supports batched execution. The required lawsuit_id, the intentionally generic query object, page, and page_size are not explained at all, leaving the agent guessing about filtering, pagination, and request formatting.

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 'Lista as publicações oficiais de um processo', a specific verb and resource, clearly indicating what the tool does. It is easily distinguishable from sibling tools such as advbox_list_customers or advbox_lawsuit_movements because it focuses specifically on official publications of a legal process.

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 core use case is clear: list official publications for a lawsuit. The additional sentence 'Bulk support: accepts lawsuit_ids for batched execution' provides practical guidance for choosing this tool for batch operations. However, there is no explicit guidance about when not to use it or how it compares to alternative list/history 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 mark as readOnly, idempotent, non-destructive. The description adds value by specifying exactly what data is retrieved (all IDs and settings categories), expanding beyond annotation metadata with useful behavioral context.

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

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

Two concise sentences, front-loaded with purpose and usage, no filler or repetition. Highly 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?

The description covers purpose and content adequately, but lacks clarity on the query parameter and return format (no output schema). For a config lookup with one optional filter, it is minimally viable but leaves the agent unsure about filtering or result structure.

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 mention the optional 'query' parameter at all. With 0 params required and a flexible object type, the agent receives no guidance on how to use the query filter, creating 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 clearly states the tool fetches all account IDs and settings, listing specific categories (users, sources, task types, phases, process types). This specific verb+resource+scope distinguishes it from sibling list tools that return individual 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?

Explicitly advises usage to 'discover the IDs required by create/update', giving clear when-to-use guidance. It does not state exclusions, but the context of sibling tools makes its purpose 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 indicate this is not read-only, but the description adds valuable behavior beyond that: partial update semantics ('Envie só os campos a alterar') and batched execution via 'ids'. It does not fully explain batch failure behavior or return/error details, but it goes beyond what the annotations 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?

Two sentences, front-loaded with the core action, no filler. The bulk support detail is separated cleanly and 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 description covers the main update and bulk scenarios, but it leaves ambiguity about how id and ids interact, especially since id is required in the schema. It also does not enumerate the accepted named fields or describe the output/return behavior, despite there being no output schema to compensate.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies id for single update, ids for batch, and extra for changed/custom fields, but the phrase 'nomeados + extra' implies named updatable fields that are not actually present in the schema. The structure of extra is also left undefined, which is a meaningful gap.

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

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

The description uses a specific verb and resource: 'Atualiza um processo existente por ID' (updates an existing lawsuit by ID). It clearly distinguishes itself from sibling create/get/list lawsuit tools, and the bulk note is still clearly about the same update operation.

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 context: use this tool to update an existing lawsuit by ID and send only the fields to change. It also hints at batch usage via 'ids'. However, it does not explicitly name alternatives or say when not to use this tool, so it stops short of a 5.

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

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

Annotations declare readOnlyHint:false, idempotentHint:false, and destructiveHint:false, so the agent already knows this is a non-idempotent write operation. The description adds valuable context about partial updates (only changed fields) and batch execution via ids. No contradictions found.

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 primary action, and includes the critical usage note about partial updates. The bulk support is a separate, concise sentence. There is no fluff or redundancy, and every element 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's complexity (6 parameters, nested object, no output schema), the description covers the essential aspects: what updates can be performed, the partial update pattern, and batch support. It explains the id requirement implicitly and covers all parameter groups. It is complete for a straightforward update operation with no output schema or additional constraints.

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 full responsibility for parameter meaning. It maps 'valor' to value, 'vencimento' to due_date, and 'status' to status, explicitly names 'extra' for additional fields, and mentions 'ids' for bulk. It also implies that id is the required identifier. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states the verb 'Atualiza' (updates), the resource 'transação' (transaction), and the specific fields it can modify (valor, vencimento, status de pagamento). It also clarifies the operation is by ID. This distinguishes it from sibling tools like create_transaction and get_transaction, and from update_lawsuit which targets a different resource.

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

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

The description provides explicit usage guidance: 'Envie só os campos a alterar' explains the partial update pattern, and it notes bulk support via ids. It does not explicitly mention when not to use it or compare against alternatives, but the context is clear that this is for updating existing transactions.

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 useful behavior beyond the annotations: config header yields a permanent connection, while passing a token yields a session-only login, and no args returns a link. It does not fully spell out side effects or success/failure return values, but annotations already cover idempotency and non-destructiveness.

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

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

The description is dense and front-loaded, with no fluff, but the long single sentence with parenthetical clauses and multiple alternatives could be structured into clearer separate instructions. Still, every part adds necessary 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 one-parameter auth tool with no output schema, it covers the no-arg return (the link), the token-paste path, and the persistent-config alternative. It doesn't state the response on a token success/failure, but the invocation guidance is sufficient for an agent to call it correctly.

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

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

With 0% schema coverage, the description carries the full burden for the optional `token` parameter. It explains that token is a JWT/access token pasted by the user and how to pass it, compensating well for 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 identifies the tool as MCP.AI authentication for IDE agents, with a concrete browser-login + access-token flow and two invocation paths (no args for a link, token for login). This specific verb+resource is unambiguous and easily distinguished from the unrelated calculo_* sibling tools.

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

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

It explicitly differentiates the persistent config-header approach ('best... permanent, non-expiring') from the session-only paste/login path, and states exactly when to call with no args versus with { token }. This gives the agent clear selection criteria for both setup and invocation.

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 this is read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that by specifying the two main response states: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This helps an agent predict what to expect.

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

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

The description is compact, front-loads the core purpose, and then adds only the essential conditional details. Every sentence contributes meaningful information, and there is no 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?

For a zero-parameter read-only status tool with no output schema, the description is complete enough. It tells the agent what information will be returned, what the success condition looks like, and what happens when credentials are missing. The low complexity means no additional guidance is required.

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 description does not need to explain any input semantics. The baseline of 4 applies because there is no parameter burden at all.

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

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

The description clearly states the tool's purpose: returning connection status and URLs. It distinguishes connect from its sibling authenticate by framing it as a status/read operation rather than an action, and the conditional output descriptions reinforce this.

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 makes clear that this is the tool to call when checking connection state or getting URLs. It does not explicitly mention alternatives like authenticate, but the context strongly implies connect is for status checking rather than initiating authentication, so usage is clear without being fully 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?

Beyond the annotations, the description discloses important behaviors: invoke runs an MCP even when it is not installed, does a one-off run without adding the MCP to the toolkit, returns a connect link when credentials are needed, returns a checkout/top-up link when payment is needed, and requires workspace owner/admin for write operations. The description enriches the annotations and 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?

The description is front-loaded with identity and the core flow, and nearly every sentence carries useful guidance. However, it is one dense, wall-of-text paragraph with mixed language ("pontualmente") and heavy inline emphasis, which makes the many action alternatives hard to scan and 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?

For a complex 23-parameter, 14-action facade with no output schema, the description is remarkably complete: it covers the core flow, one-off invoke semantics, auth/credential/payment behavior, permission requirements, installed flags, the prompt library, and most action outcomes. The main gaps are the resume action and return-shape details for a few actions, but the overall guidance is sufficient for correct invocation in most cases.

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 does a lot of compensating work: it maps action values such as search, describe, invoke, install, list_tools, publish_prompt, and explains tool_id, arguments, and prompt-related intent. However, several parameters and enum actions remain unexplained, including resume, limit, immediate, tier_slug, cancel_reason, report_context, conversation, request_name, and request_details, leaving agents under-specified for those paths.

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 as the official mcp.ai marketplace: the in-platform catalog of MCPs/tools and the way to run them. It states the core discovery→describe→invoke flow, distinguishes the prompt-library subdomain from the MCP flow, and makes it clear this is a marketplace orchestrator rather than one of the sibling calculator/authenticate 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 gives explicit when-to-use guidance: use install only to make an MCP permanent, prefer invoke for one-off use, use list_tools to see what is callable now, use subscribe/cancel for billing, and use request_mcp when nothing fits. It also explains what to do when invoke returns a connect link or checkout link, including retry behavior.

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 carry the safety profile with idempotentHint=true and destructiveHint=false. The description adds that conversation data is needed for reproduction, which is useful context. However, it does not disclose what happens after submission, such as whether a ticket is created or whether the report is asynchronous, though the annotations lower 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 consists of two tight sentences: the first states the purpose, the second gives the key usage instruction. There is no filler, repetition, or irrelevant 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 three-parameter reporting tool with annotations already covering idempotency and destructiveness, the description is mostly sufficient. The main gaps are the unexplained `context` parameter and the absence of any indication of what the response or outcome will be, though no output schema is expected.

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 undocumented parameters. It only clarifies the `conversation` parameter via 'conversation array with recent messages,' leaving the required `message` and optional `context` undefined. The agent must guess at their intended content.

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 the verb 'Report' and explicitly enumerates three targets: 'bug, missing feature, or send feedback'. This makes the tool's purpose unmistakable and easily distinguishable from the sibling calculo_* and authentication tools, which serve entirely different functions.

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 establishes a clear context: use when a user reports a problem or wants to provide feedback. It also adds practical guidance to 'Include the conversation array with recent messages for reproduction.' It does not name alternatives, but none of the sibling tools overlap with bug reporting, so exclusions are unnecessary.

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 declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating call. The description adds little beyond that—it names the output as versions but doesn't specify the format (e.g., semver strings, JSON object) or whether the output is human-readable. Since the annotations carry the safety profile, a 3 is appropriate.

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

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

The description is a single sentence of 9 words, front-loading the action ('Show') and the object ('version'). There is zero waste, and it fully conveys the tool's purpose within its scope. This is a model of conciseness.

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, idempotent tool with no output schema, the description is nearly complete. An agent can confidently invoke it without additional context. The only minor gap is that the return format is unspecified, but since there is no output schema, a brief note on the output structure (e.g., 'returns a plain-text summary') would elevate completeness. Still, the description is sufficient for correct invocation.

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

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

The tool has zero parameters, and the schema coverage is 100% (no properties). The description doesn't need to explain parameters. The baseline for zero-parameter tools is 4, and the description is consistent with that—it correctly implies that no input is required.

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: 'Show the current MCP platform and adapter versions.' This is a specific verb-resource pair that distinguishes it from sibling tools, which are all calculation or authentication tools. It could be slightly more explicit about what 'show' returns (e.g., a text summary vs. structured data), but the resource 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 implies that this tool is for checking version information, which makes sense in contexts where an agent needs to confirm platform/adapter versions before proceeding. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention whether version information is needed for authentication or compatibility checks. Given the sibling tools are all calculations, the usage context is reasonably clear, but not explicitly delineated.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by detailing what kind of state is returned, including connection status and account bindings, which helps the agent understand the tool's informational scope.

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 tightly packed sentence with the main action front-loaded, followed by a colon-delimited list of return contents. Every phrase earns its place with no repetition or filler.

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

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

For a zero-parameter, read-only introspection tool, the description fully covers what the agent needs to know before calling: what information it will receive. No output schema exists, but the description essentially provides a light output contract by enumerating the returned components.

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 is empty with zero parameters, and schema description coverage is 100%, so the description has no parameter burden. Per calibration, zero-parameter tools receive a baseline of 4; the description's output-focused content is more than sufficient.

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 resource ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific enough to distinguish it from computational siblings like calculo_* and action tools like authenticate or 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 clearly conveys that this is the tool to call when an agent needs an overview or snapshot of the toolkit's current state. It does not explicitly list exclusion criteria or name alternatives such as show_version, but the context is clear enough for routine selection.

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