SEFAZ MT DEC: Caixa Postal

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

Annotations already mark the tool as idempotent and non-destructive; the description adds meaningful context about token persistence (permanent via config header vs session-only via paste) and explains that calling with no args yields a browser login link. It does not mention invalid-token behavior or response details, but it adds 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?

Three dense sentences, front-loaded with the tool's purpose and user workflow. Every clause adds info: audience, browser login, token source, permanent vs session persistence, and call forms.

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

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

For a simple one-parameter optional-token tool, the description covers the main invocation modes and user workflow well. The main gap is the lack of any mention of the response/return value or failure cases, though no output schema exists to fill that 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?

Schema coverage is 0%, but the description compensates by explaining that `token` is an optional JWT used for session-only login and that omitting it triggers the login-link flow. This gives the agent clear functional meaning for the single parameter.

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

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

The description clearly identifies the tool as the MCP.AI authentication entry point for IDE agents, with a specific flow: log in via browser, copy token, then use it. It is clear enough to distinguish from siblings like `show_version` or `report_bug`, though it does not explicitly contrast itself with the `connect` sibling.

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

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

The description gives explicit invocation patterns: call with `{ token: "<jwt>" }` to paste a session token, or call with no args to get a login link. It also contrasts a permanent config-header approach with a session-only token approach, providing practical usage context.

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

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

Annotations already declare readOnlyHint:true, idempotentHint:true, and destructiveHint:false. The description adds valuable context beyond that, specifying exact output conditions (authenticated:true and empty pending[] when connected, connect_url when credentials missing), which is not derivable from annotations.

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

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

The description is two sentences, front-loaded with the purpose, and every sentence earns its place. It avoids redundancy and provides necessary details on two distinct states.

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 0 parameters and no output schema, the description fully covers the tool's behavior: what it returns in different scenarios. It is complete for a status-checking tool, and the description adequately explains the return values.

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 0 parameters, and per the baseline the score is 4. The description correctly adds no parameter details since none exist. It explains the output sufficiently without needing parameter semantics.

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

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

The description clearly states the tool's purpose: 'Returns connection status and URLs.' It uses a specific verb (returns) and resource (connection status, URLs), and it distinguishes from siblings like authenticate or marketplace by focusing solely on status retrieval.

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 clear context on when the tool is relevant (checking connection status) and describes behavior under different conditions (connected vs missing credentials). It does not explicitly name alternatives or state 'use this when...', but the context is sufficient for a simple status tool.

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

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

The description adds valuable behavioral context beyond annotations: invoke runs MCPs even without installing them, returns connect links when credentials are missing, returns checkout/top-up links when paid capabilities need payment, and install/uninstall/subscribe/cancel require owner/admin. It also explains that publish_prompt returns a shareable short link. 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 dense and somewhat run-on, but given the tool's complexity (23 parameters, many sub-actions, prompt category additions), the length is largely justified and every sentence adds useful context. It is front-loaded with the core purpose and flow, though it could benefit from a more structured bullets/list format.

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 must cover meaningful return/traffic values. It does for the important cases: describe returns tool profiles with id/params/pricing/auth, invoke can return connect or checkout links, and publish_prompt returns a shareable slug. However, it stays vague on the exact output shape for search, list_tools, cancel/resume/report_bug, and leaves some reader inference 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 schema has 23 parameters and 0% description coverage, so this description must compensate. It explains the high-level meaning of the central action field and key orchestrations (search, describe, invoke, install, etc.), but it leaves many parameters—such as limit, immediate, tier_slug, conversation, prompt_vars details, and report_context—uncovered. It is far better than nothing, but not enough to fully scaffold correct invocation for every sub-action.

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

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

The description clearly defines the tool as "the official mcp.ai marketplace" and the central place to discover and run MCPs, with a concrete core flow (search → describe → invoke). It is reasonably specific, but it does not explicitly distinguish itself from the sibling report_bug or toolkit_info tools, and it bundles many sub-capabilities inside one dispatcher, so it lacks sharp sibling differentiation.

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

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

The description gives explicit use guidance: prefer invoke for one-off use, use install only to make the MCP permanent, use search/describe for discovery, list_tools for currently-callable tools, and request_mcp when nothing fits. It also clarifies that writes require workspace owner/admin, which is a strong usage constraint.

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 establish it is non-destructive, non-read-only, and idempotent. The description adds useful behavioral context by instructing the agent to include the conversation array for reproduction, which is more than the annotations provide. It does not contradict any annotation and gives a key usage detail.

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

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

The description is two sentences with no filler. It front-loads the purpose and follows with a single practical instruction. Every word earns its place, making it highly concise and well-structured.

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

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

For a tool with 3 parameters and no output schema, the description covers the main purpose and one parameter clearly, but it does not explain the 'context' parameter or emphasize that 'message' is required. Given the 0% schema coverage, the description should provide more complete parameter guidance to be fully self-sufficient.

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

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

Schema coverage is 0%, so the description must compensate for parameter meaning. It explicitly mentions the 'conversation' parameter and clearly implies the 'message' parameter (the bug/feedback content). However, the 'context' parameter is left undefined, so the description only partially clarifies parameter semantics.

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

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

The description states a clear, specific purpose: 'Report a bug, missing feature, or send feedback.' This is a specific verb+resource combination that distinguishes it from unrelated sibling tools. It also provides an actionable instruction about including the conversation array, further clarifying its role.

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

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

The description clearly indicates when to use the tool: when reporting a bug, missing feature, or feedback. It does not explicitly state exclusions or alternatives, but the sibling tools are unrelated, so the context is sufficient. A full 'use this instead of X' is not necessary given the tool's unique purpose.

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 read-only, idempotent, and non-destructive, which are consistent with the description's 'consulta' (query) nature. The description adds useful context about data governance (LGPD), control, and the fact that it is not confidential data, beyond what annotations cover.

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 paragraph but compact and front-loaded with the core purpose. It includes necessary legal and commercial disclaimers, which are relevant, though it could be slightly 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?

With 7 parameters and no schema descriptions, the description leaves much unexplained: what each parameter is for, how they combine (e.g., do ie/cpf/cnpj select the mailbox?), and what the response contains. It also lacks any mention of authentication flow, which is crucial given the pkcs12 credentials.

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 needed to explain parameters. While it lists some parameters indirectly (e.g., 'ie', 'cpf', 'cnpj' could be identifiers for the mailbox), it does not explain any parameter's purpose or format. The description mentions credentials are not platform credentials but does not explain the pkcs12_cert and pkcs12_pass parameters beyond that.

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 queries SEFAZ MT's official mailbox ('Caixa Postal') and is a consultation tool, which distinguishes it from siblings like authenticate or marketplace. However, the exact resource being queried (e.g., DEC mailbox) is somewhat implicit and could be clarified.

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 explains this is a paid per-query service using prepaid credits and that it accesses official Brazilian data available to citizens, implying use for legitimate public data queries. It does not provide explicit when-to-use vs alternatives, but given sibling tools are unrelated, the context is adequate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds no extra behavioral context beyond restating the action, but it does not contradict annotations. With annotation coverage, a neutral score 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 with no redundant wording. It efficiently conveys the tool's function without any fluff.

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

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

For a zero-parameter, read-only version tool with no output schema, the description is complete. It fully explains what the tool does, and no additional context is necessary.

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 there are no parameter semantics to clarify. The description is sufficient since schema coverage is 100% with no parameters, warranting the baseline 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 action (show) and the resource (current MCP platform and adapter versions). It is specific and distinct from sibling tools like authenticate or connect, 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 description does not explicitly state when to use versus alternatives, but the purpose is unambiguous—a simple version info tool that naturally fits its use case. No exclusions are needed given its trivial nature.

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 content about what the return includes, which goes beyond annotations, but it does not disclose any additional behaviors such as performance, caching, or authentication requirements. With annotations covering the main aspects, this is satisfactory 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, well-structured sentence that front-loads the tool's purpose ('Returns the current toolkit state') and then lists the concrete components. Every word adds value, and there is no redundancy or unnecessary detail.

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

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

Given there is no output schema, the description carries the full burden of explaining what the tool returns. It does so effectively by listing the key elements: installed MCPs, connection status, connected accounts, and catalog tool counts. This completes the picture for a status tool, especially with the safety annotations already present.

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 no parameters (0 params, schema coverage 100%), so the baseline score is 4 per the rubric. The description need not explain any parameters since there are none. It effectively communicates that the tool takes no input and returns a state summary.

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: 'Returns the current toolkit state' and enumerates its components (installed MCPs, connection status, accounts, catalog tool counts). This uses a specific verb ('returns') and a resource ('toolkit state'), and distinguishes it from sibling tools like authenticate or connect, which perform actions rather than report state.

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

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

The description implies usage: if you need toolkit state, this tool provides it. However, it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or conditions. For a status tool, the usage context is fairly obvious, but the lack of explicit guidance keeps it at an adequate level.

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