Microvix

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

Annotations already mark idempotentHint=true and destructiveHint=false. The description adds context about the link generation and session-only vs. permanent connection, without contradicting annotations. It does not detail error handling or output, but annotations reduce the burden.

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

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

The description is three sentences, front-loaded with the target audience and purpose. It efficiently covers two usage modes without unnecessary detail, though it could be slightly more structured with 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?

Despite lacking output schema, the description covers essential behavior for a simple authentication tool: how to obtain a token, two usage paths, and the difference between permanent and session login. It could mention error cases, but the core usage is well-specified.

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

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

Schema coverage is 0%, so the description must compensate. It explains that the 'token' parameter is optional: passing it sets a session token, omitting it returns a login link. This adds significant meaning beyond the schema's empty description.

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 authenticates IDE agents (Cursor, etc.), explaining two distinct methods: permanent via config header or session via token argument. It is a specific verb-resource combination that stands out from sibling tools like 'connect' or 'marketplace'.

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 on when to use each method: 'Best: add it to this server's config... Or paste it here for a session-only login.' It also explains calling with no args to get the link, but does not explicitly exclude alternative tools, though no alternative is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining the return structure (authenticated:true with empty pending[] or connect_url) and the conditions for each state. No contradictions.

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

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

Two clear, front-loaded sentences without wasted words. Every sentence provides essential behavioral information.

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

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

Given no parameters and no output schema, the description is fairly complete. It covers the purpose and two return scenarios. Minor gap: could mention that it is a read-only check, but annotations already cover that.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to add parameter information, and it does not.

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 'Returns connection status and URLs' and explains the different return states (all connected vs missing credentials). This is a specific verb+resource that distinguishes from sibling tools like 'authenticate'.

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

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

The description implies usage for checking connection status but does not explicitly state when to use this tool versus alternatives like 'authenticate' or when not to use it. There is no guidance on prerequisites or fallback 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?

Beyond the annotations (readOnlyHint false, destructiveHint false), the description reveals that invoke works even when an MCP isn't installed, runs one-off without bloating the toolkit, and returns connect/checkout links when auth or payment is needed. It also discloses that writes require workspace owner/admin, adding critical permission context annotations don't provide.

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

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

The description is dense but every sentence adds value, covering the core flow, invoke semantics, install implications, permissions, and the prompt library. It lacks section breaks or bullet formatting, making it a wall of text, but remains readable and well-organized.

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 14 actions, 23 parameters, and no output schema, the description covers the primary user journeys (discover, describe, invoke, install) and edge cases (auth, payment retry, permissions). It touches on report_bug, request_mcp, and prompt library functions, though a few secondary actions like resume and cancel get no detail.

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 explains core parameters like action (search/describe/invoke/install), tool_id, mcp_id, and arguments as part of the workflow. However, many parameters such as immediate, tier_slug, cancel_reason, and prompt_category are only listed in the schema without any description-level explanation, so the description only partially compensates.

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 the tool is 'the official mcp.ai marketplace' and immediately explains the core flow (search → describe → invoke). It distinguishes its role as both catalog and execution layer, clearly differentiating it from sibling tools that are specific microvix operations or support utilities.

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 guidance: 'prefer invoke for a single/occasional use' and 'use install only to make an MCP PERMANENT in the active toolkit'. It also clarifies when to use list_tools, request_mcp, and report_bug, providing clear decision context for the agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the filtering behavior (by data_inicial/fim, doc_cliente, cnpj_emp), which is useful context, but does not disclose details like default limit, sorting, or response format. Given the annotations, the description adds moderate value beyond them.

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

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

The description is extremely concise, consisting of two sentences with no fluff. It front-loads the core purpose and immediately lists the key filters. Every word earns its place, making it an excellent example of brevity.

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 query tool with 7 parameters and no output schema, the description provides only partial context. It explains the main filters but omits pagination parameters (limit/offset) and the account parameter, as well as any details about the returned data structure. While the read-only nature is covered by annotations, an agent lacks full information to invoke it correctly without guessing on those unexplained parameters.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It names three filter parameters (data_inicial/fim, doc_cliente, cnpj_emp) and clearly indicates they are used for filtering, which adds meaning. However, it ignores limit, offset, and account, leaving those parameters unexplained. Thus, it partially compensates but is 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 identifies the resource as 'Cadastro de clientes e fornecedores' (customer and supplier registry) and mentions the underlying object LinxClientesFornec. It conveys a read-oriented purpose (filterable query). However, it does not explicitly differentiate from sibling tools like microvix_lojas or microvix_produtos, though the entity type is distinct enough to avoid confusion.

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 querying customer/supplier data by mentioning filter fields, but it does not explicitly state when to use this tool versus alternatives, nor any exclusions. An agent can infer from the resource name, but there is no direct guidance on selecting this over other microvix tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds that it lists CNPJs of a group, which is the expected behavior, but does not mention pagination, error conditions, or the exact structure of results. Since annotations cover the important behavioral traits, the description adds minimal extra context, warranting a 3.

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

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

The description is extremely concise: two short sentences that effectively communicate the purpose and a usage tip. It is front-loaded with the core action and avoids unnecessary details. Every part of the text serves a purpose, so it earns a perfect 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?

The tool has no output schema, and the description does not mention the return format (e.g., array of CNPJs, pagination handling) or clarify the optional parameters. While the purpose is clear, the lack of parameter explanations and response details makes it incomplete for an agent to invoke correctly without extra context, especially given the 0% schema coverage.

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

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

Schema description coverage is 0%, and the description does not explain any of the four parameters (grupo, limit, offset, account). It only implies that 'grupo' is relevant by mentioning a group, but offers no details on syntax, defaults, or the meaning of limit/offset/account. With zero schema coverage, the description fails to compensate, resulting in a low score.

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: listing CNPJs of stores belonging to a group (LinxGrupoLojas). It uses a specific verb ('Lista') and a resource ('CNPJs das lojas'), making it easy to understand what is returned. It does not explicitly differentiate from sibling microvix_lojas, but the group context provides enough distinction for an agent.

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 includes a usage hint: 'Use pra descobrir os cnpj_emp antes de iterar' (use to discover the cnpj_emp before iterating). This suggests when to use it in a workflow but does not mention when not to use it or compare it to alternatives like microvix_lojas. It gives partial guidance, so it earns a 3.

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, covering safety. The description adds that it returns id and label, providing further clarity on behavior. 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 sentence, front-loaded with the main action, and contains no redundant words. It is concise but could be more structured.

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

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

For a simple list tool with an optional parameter and no output schema, the description provides the output fields but omits parameter usage. This is adequate but leaves a 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?

The sole parameter 'account' is not explained in the description. With 0% schema description coverage, the description should clarify its purpose (e.g., filtering), but it does not.

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 Microvix portals connected to the install, with id and label. This distinguishes it from sibling tools like microvix_clientes_fornec or microvix_produtos.

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 microvix_clientes_fornec or other listing tools. It simply states what it does.

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 the safety profile is covered. The description adds no behavioral context such as pagination behavior, ordering, or implicit filters. It only describes data content, not how the tool behaves, so it falls short of the lowered bar.

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 sentence that front-loads the core topic and lists key return fields. It is efficient, though slightly terse, earning a 4 for structure without being overlong.

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 four parameters and no output schema, the description is incomplete. It does not explain the parameters (limit, offset, account, cnpj_emp) or how they filter results. While annotations confirm read-only and idempotent behavior, the agent lacks the information needed to construct valid calls, such as which account or CNPJ to pass.

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%, with four parameters (limit, offset, account, cnpj_emp) completely undocumented. The description mentions CNPJ in a return-field context but does not explain any parameter's meaning or usage. The description fails to compensate for the lack of schema documentation.

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

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

The description identifies the resource (lojas/empresas do portal) and some fields (CNPJ, endereço, regime tributário), but lacks a verb like 'list' or 'fetch', making the operation implicit. It distinguishes from siblings by focusing on store data, but the absence of an explicit action lowers clarity from a 4 to a 3.

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

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

No guidance is given on when to use this tool versus alternatives like microvix_grupo_lojas or microvix_clientes_fornec. The description provides no context for selection, leaving the agent to infer based on the name alone.

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=true, destructiveHint=false, idempotentHint=true), the description discloses rich behavior: the resumo mode sweeps the whole window via multiple deduplicated calls, returns deterministic sums of raw columns, is subject to a 5,000-row cap, filters by data_lancamento rather than data_documento, and can return PARTIAL numbers when the provider truncates. No contradiction with annotations — the deterministic-totals wording reinforces idempotentHint.

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?

Long but every sentence earns its place — the tool genuinely needs the two-mode explanation, the 5,000-row cap, and truncation handling. Purpose is front-loaded. Slightly dense, but the information-to-length ratio is justified by complexity rather than padding.

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 this complex (7 params, two output formats, pagination, truncation) with no output schema, the description is remarkably self-contained: it explains both modes, the row cap, the truncation flags to check, the recommended calling pattern, performance expectations, and the output semantics (116 columns, sums of same-name raw columns). Nothing an agent needs to call it safely is missing.

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

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

With 0% schema coverage, the description carries the full burden and explains most parameters well: formato (two enum values with distinct semantics), data_inicial/data_fim (window semantics on data_lancamento), cnpj_emp (filter), and limit/offset (pagination in linhas mode). However, the 'account' parameter is never explained and no date string format is given, so a minor gap remains for a tool with zero schema help.

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?

States a specific subject and scope — 'Movimento de vendas/fiscal (LinxMovimento): transações, chave da NF, impostos (ICMS/PIS/COFINS/IPI), formas de pagamento' — and identifies itself as 'a base do faturamento'. This clearly distinguishes it from siblings like microvix_pedidos_venda (orders) and microvix_produtos (products) without needing to open schemas.

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

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

Explicit, scenario-driven guidance: use formato:"resumo" for month-end closing with one call per (cnpj_emp, período), use formato:"linhas" only for line-level work, reframe into smaller chunks when truncated, and always verify truncado_pelo_provedor. It even quotes expected latency (~20s per store). The when-to-use vs when-not-to guidance is unusually complete.

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 that the tool filters by date, client document, and company CNPJ, which is useful context. However, it does not disclose pagination behavior (limit/offset), response format, or any rate limits. Given the annotations, this is acceptable but not exceptional.

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, which is concise. However, it is so sparse that it barely adds value beyond the name. It front-loads the resource name but does not structure the filter information in a way that helps the agent quickly understand usage. It is appropriately sized for a trivial tool, but here it is under-specified.

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

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

With 7 parameters, no output schema, and zero parameter descriptions, the description is far from complete. It does not explain how the filters interact, whether the tool returns a list or a single object, or how pagination works. An agent would need to guess parameter formats and the response structure. The description fails to cover essential details for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explicitly names three of the seven parameters (data_inicial, data_fim, doc_cliente, cnpj_emp) as filters, adding some meaning. However, it completely omits limit, offset, and account, leaving the agent unsure of their purpose. The information is partial and lacks details like date formats or requiredness.

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

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

The description identifies the tool's resource as 'Pedidos de venda' (sales orders) and specifies the underlying entity 'LinxPedidosVenda'. It also lists the primary filter fields, which distinguishes it from sibling tools like microvix_produtos or microvix_movimento. The verb is implied (list/retrieve), but the context makes the purpose clear.

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 the many sibling microvix_* tools. It does not mention scenarios, prerequisites, or alternative tools. The agent must infer that it is for sales orders based solely on the name, which is risky given the large tool family.

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 agent knows it's a safe, non-mutating operation. The description adds that it supports filtering by update window and cnpj_emp, which is useful behavioral context about the query scope. However, it does not mention return format, pagination behavior, or how results are ordered. With annotations covering the safety profile, the description provides moderate 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 sentence that front-loads the core purpose, lists key fields, and mentions filtering. There is zero fluff or redundancy. Every word contributes meaning.

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 tool with 8 optional parameters and no output schema, the description is incomplete. It does not state the shape of the response, whether pagination is used, or how to retrieve all products. It also fails to point to related product tools, which would help an agent navigate the toolset. While safety is covered by annotations, the operational details are insufficient.

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

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

Schema coverage is 0%, so the description carries full responsibility for parameter meaning. It explains that dt_update_inicio/fim and cnpj_emp can be used as filters, and it lists product attributes (nome, NCM, etc.) that are not even parameters. It does not explain limit, offset, account, cod_produto, or referencia. The description only partially compensates for the missing schema documentation, leaving several parameters unexplained.

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

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

The description clearly states it is a product registration (Cadastro de produtos) and lists the fields it covers (nome, NCM, CEST, referência, cor/tamanho, marca/linha/setor). This gives a solid understanding of the resource. However, it does not differentiate from sibling tools like microvix_produtos_detalhes or microvix_produtos_inventario, so an agent might not know which tool to pick for detailed vs inventory 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?

There is no guidance on when to use this tool versus its siblings. The description mentions filtering by update window and cnpj_emp, which hints at usage scenarios, but it never states when to select this specific tool over others. No exclusions or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds context about the scope ('por loja') and the returned fields, but does not go beyond that to disclose any additional behavior such as pagination limits, authentication requirements, or what happens with missing filters. Since annotations exist, a 3 is appropriate—the description adds minimal behavioral context beyond what structured data provides.

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

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

The description is a single, concise sentence that front-loads the primary purpose and lists key output fields, followed by a filter hint. There is no wasted wording. It could be slightly more structured (e.g., separating purpose and parameters), but it is efficient and to the point.

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

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

With 8 parameters, no output schema, and only minimal annotations, the description is far from complete for an agent to call this tool correctly. It does not explain the format of date strings, the meaning of referencia/cod_produto, pagination behavior, default behavior with no filters, or the exact response structure. An agent would be guessing on many aspects of 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 input schema has 8 parameters with 0% description coverage, so the description must compensate. It only mentions three parameters (data_mov_ini, data_mov_fim, cnpj_emp) as filters, and implicitly references some output fields that are not parameters. It does not explain the purpose of limit, offset, account, referencia, or cod_produto. Coverage is far below what is needed, leaving most parameters undocumented in both schema and description.

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 product details per store ('Detalhe de produto por loja') and lists the specific fields returned (código de barras, quantidade, preco_custo, preco_venda, custo_medio). It is specific about the resource and action, but does not explicitly contrast with sibling tools like microvix_produtos or microvix_produtos_inventario, so it misses the differentiation that would earn a 5.

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 mentions filters (date and CNPJ) but gives no guidance on when to use this tool versus alternatives. There is no indication of when a user should pick this over microvix_produtos, microvix_produtos_inventario, or microvix_movimento. It only implies usage through the filter statement, which is insufficient for an agent to correctly select among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it queries by barcode and expects specific parameters, but doesn't disclose pagination, return format, or any side effects beyond what annotations imply. Given the low bar set by comprehensive annotations, this is adequate but not rich.

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 immediately states the purpose and the key parameters to provide. It is efficient with no wasted words. The only downside is that it is so terse it sacrifices necessary detail, but as a conciseness and structure score, it is well-organized.

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 5 parameters, no output schema, and no required fields, the description is inadequate. It mentions 'por código de barras' but no parameter exists for a barcode, creating a mismatch between description and schema. It also lacks any explanation of return values, pagination, or the role of account/limit/offset. The agent cannot confidently call this tool without additional research.

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%. The description names two parameters (data_inventario and cnpj_emp) but does not explain their format, purpose, or why they are needed, and completely omits limit, offset, and account. This is insufficient for a 5-parameter tool with no other documentation.

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

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

The description clearly states the tool provides inventory/stock balance by barcode, which is a specific resource and action. It distinguishes it from sibling tools like microvix_produtos (products) and microvix_movimento (movements) by the 'saldo de estoque' and 'por código de barras' phrasing. However, it doesn't explicitly state what data is returned, so a perfect score is not warranted.

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 no guidance on when to use this tool versus alternatives like microvix_produtos or microvix_produtos_detalhes. It only instructs to 'Informe data_inventario e cnpj_emp', which is parameter guidance, not usage context. No conditions, exclusions, or alternative tool mentions are present.

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 (readOnlyHint=true, destructiveHint=false, idempotentHint=true), lowering the burden. The description adds the concrete table name (LinxVendedores) and filter scope, which is useful. It doesn't contradict the annotations, but it adds no detail on pagination, return format, or per-account behavior beyond what annotations imply — a modest but non-trivial contribution.

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 tight sentences with the resource identified up front and filters following. No filler or redundant restatement of the name. Could be marginally improved by ordering the most-used filters first, but the structure is efficient and front-loaded.

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 7-parameter tool with 0% schema coverage and no output schema, the description is under-specified. It omits the account semantics (critical given the multi-account sibling microvix_list_accounts), the date format for the data_upd_* filters, and pagination behavior. While annotations cover the safety profile, the operational details an agent needs to call it correctly are missing.

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

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

Schema description coverage is 0%, so the description must compensate across 7 parameters. It names four filter fields (data_upd_inicial, data_upd_fim, cod_vendedor, cnpj_emp) and marks them as filters, adding some meaning. But it says nothing about limit/offset, the account parameter, or the date format expected — a material gap given zero structured documentation for all 7 params.

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

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

The description names the resource explicitly (Cadastro de vendedores / LinxVendedores) and distinguishes it from siblings like microvix_clientes_fornec and microvix_produtos. However, it lacks an explicit action verb (e.g., 'list', 'query', 'get') — the noun 'Cadastro' plus the filter instruction implies a listing operation, leaving the exact behavior slightly implicit.

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 tells the agent which parameters to filter by (data_upd_inicial/fim, cod_vendedor, cnpj_emp) but gives no guidance on when to select this tool over its siblings, no prerequisites (e.g., whether an account must be connected first, given the account parameter and microvix_list_accounts sibling), and no exclusions. Sibling differentiation is 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 provide idempotentHint=true and destructiveHint=false, which are consistent. Description adds no new behavioral context (e.g., side effects, authentication, rate limits) beyond what annotations already indicate.

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 efficient sentences front-load purpose and a key usage hint, no extraneous 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?

Tool is simple but lacks output schema and parameter descriptions. Description covers core purpose and one parameter, but is adequate for a feedback tool given idempotentHint.

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 has 0% description coverage. Description clarifies the 'conversation' parameter meaning but leaves 'context' undocumented, so only partial value added.

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 verb 'Report' and resource 'bug, missing feature, or send feedback', distinguishing it from sibling tools which are unrelated Microvix operations.

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 including conversation array for reproduction, giving clear context. No when-not-to-use or alternative tools mentioned, but sibling set doesn't overlap.

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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the specific output details (platform and adapter versions) beyond the annotations, which is useful but not extensive. 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 sentence with no wasted words, perfectly front-loaded and concise.

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 info tool with no output schema and minimal complexity, the description fully explains what the tool does without needing additional details.

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

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

The tool has zero parameters, so the schema covers everything. The description does not need to add parameter semantics. Score 4 as baseline for no 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 'Show the current MCP platform and adapter versions', specifying the verb 'show' and the exact resource (version info). It is distinct from sibling tools like authenticate or microvix tools, which have different purposes.

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 purpose is self-evident for a version-checking tool; no explicit guidance on when to use is needed, but no alternatives are mentioned. Score 4 for clear but lacking 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 mark it as read-only, idempotent, and non-destructive. The description adds value by disclosing that it returns not just connection status but also account associations and catalog tool counts, which is behavior not visible in annotations or schema.

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

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

The description is a single, well-structured sentence that front-loads the action ('Returns the current toolkit state') and then lists the key content groups. No filler or redundant wording.

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 absence of an output schema, the description fully enumerates what the agent can expect to receive. It is complete for a simple status tool, covering all relevant aspects (MCPs, connection status, accounts, tool counts) without needing additional context.

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

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

The tool has zero parameters, so the schema provides complete coverage (100%). The baseline of 4 applies because there are no parameters to document and the description adequately explains the operation without needing to reference 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?

The description uses the specific verb 'Returns' and clearly identifies the resource as 'current toolkit state', then enumerates its contents (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from siblings like show_version 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 for inspecting toolkit state, implying use when you need an overview of MCP connections and accounts. It does not explicitly mention alternatives, but the uniqueness of the described output makes the use case obvious.

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