SEFAZ MA DEC: Caixa Postal

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

Annotations already indicate idempotent, non-destructive, and non-read-only behavior. The description adds useful context about the browser flow, the permanent config option, and the session-only paste option. However, it does not disclose what happens when an invalid token is passed, whether the token is stored, or what response the tool returns in success/failure cases.

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 and contains actionable information without fluff. It is dense but slightly cluttered by the embedded code span and multiple conditional instructions; a more structured format (e.g., bullet points) would improve scanability, but it remains acceptably 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?

There is no output schema, so the description must explain return behavior; it only states that calling with no args returns the login link. It does not explain what the tool returns when a token is provided, how errors are surfaced, or the expected success confirmation. For an authentication flow, this is a notable completeness gap, but the core invocation options are covered.

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 only lists an optional 'token' string with no description. The description compensates by explaining that the token is a JWT pasted by the user, that it must be passed as { token: "<jwt>" }, and that omitting the argument triggers the login-link behavior. This adds meaningful semantic context beyond the bare schema.

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

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

The description clearly communicates that the tool authenticates an MCP.AI session for IDE agents: it provides a browser login link, accepts a pasted JWT token, or instructs users to configure a permanent header. It is specific about the resource (MCP.AI authentication) and the available invocation modes, though it does not explicitly name itself as the authentication action beyond 'log in'.

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 practical usage guidance: adding the token to server config for a permanent connection is recommended, while passing the token in this call is for session-only login; calling with no args returns the login link. This clearly distinguishes when to use each invocation pattern, though it does not mention sibling tools or conditions where authentication might not be 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 declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds valuable behavioral context beyond annotations by specifying the exact response shapes in different states (authenticated:true with empty pending[] vs. connect_url), which is not covered by 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 three sentences: the first states the primary function, the second and third explain conditional output. Every sentence earns its place with no redundant or irrelevant information. It is front-loaded with the core 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?

The description explains the two main states (all connected vs. missing credentials) and the return values, which is sufficient for a no-parameter tool with no output schema. However, it doesn't cover intermediate partial-connection states, leaving a minor gap in completeness.

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

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

The tool has zero parameters, so the schema is vacuous. Per the rubric, 0 params gives a baseline of 4. The description doesn't need to add parameter meaning since there are none.

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

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

The description clearly states the tool returns connection status and URLs, with specific verb and resource. It distinguishes itself from siblings like 'authenticate' by focusing on status checking rather than performing auth. The two conditional behaviors (all connected vs. missing credentials) further clarify its 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?

The description implies usage for checking connection status, but lacks explicit guidance on when to use this over alternatives like 'authenticate'. It doesn't mention 'use this when you need to verify connection state' or exclude other scenarios, so the guidance is only implied, not 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?

Even with annotations present (readOnlyHint:false, openWorldHint:true), the description meaningfully extends beyond them. It discloses that invoke runs tools one-off 'without adding the MCP to the toolkit and without bloating the tool list', that writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin, and that invoke returns connect/checkout links requiring user action then retry. No contradiction with annotations 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 information-dense with genuinely useful content, but it is delivered as a single continuous run-on paragraph with no bullet points, sections, or headings. It covers three distinct domains (MCP catalog flow, billing/installs, prompt library) without structural separation. Every sentence earns its place, but the formatting undermines scannability for an agent.

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 very complex tool (23 params, 14-action enum, no output schema), the description covers the primary flows thoroughly: search→describe→invoke, install vs invoke distinction, auth ownership requirements, payment link behavior, and the separate prompt-library sub-flow. Gaps remain in peripheral actions (resume, uninstall details, cancel workflow specifics) and return-value descriptions for search/list_tools, but the core usage is well covered.

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, and it does for the core flow: it maps action enum values to behaviors and explains tool_id/mcp_id/arguments usage in the search→describe→invoke flow. However, many of the 23 parameters (prompt_vars, conversation, tier_slug, cancel_reason, cancel_comment, prompt_targets, request_details, immediate, etc.) receive no semantic explanation, so compensation is only partial.

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, multi-faceted purpose: it is the in-platform MCP catalog and execution tool ('the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them'). It clearly distinguishes itself from siblings (authenticate, show_version, toolkit_info, sefaz_ma_dec_caixa_postal_consultar) by being the catalog/runner rather than a specific capability, and explicitly contrasts install vs invoke vs 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?

Provides explicit when-to-use guidance: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT in the active toolkit', and spells out the core flow 'search discovers MCPs by intent → describe returns one MCP's full profile... so you pick the right tool_id → invoke RUNS that tool'. Also covers the retry pattern (connect/checkout link then retry) and the prompt-library sub-flow, naming search_prompts/get_prompt/publish_prompt with distinct roles.

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 safety cues (readOnlyHint=false, destructiveHint=false, idempotentHint=true). The description adds the instruction to include the conversation array for reproduction, which is useful context about expected input. However, it does not disclose what happens after submission (e.g., ticket creation, error handling), though the annotation coverage lowers the burden.

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

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

The description is concise, using a single sentence with two clauses. It front-loads the purpose and provides one actionable hint. No unnecessary text, though it could be slightly more structured (e.g., separating purpose and parameter guidance).

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, no output schema, and no description of return values or error behavior. The description covers the basic purpose and one parameter hint but omits details on the other parameters, expected format for the conversation (likely JSON string), and post-submission effects, making it incomplete for a reporting tool.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions the conversation parameter ('Include the conversation array') but does not clarify the required 'message' parameter or optional 'context' parameter. This leaves the agent unsure about what to supply beyond conversation.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' The verb 'report' and resource (bug/feature/feedback) are specific and distinguish it from sibling tools like authenticate, connect, or toolkit_info, which serve 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 implies when to use the tool (when encountering a bug, missing feature, or providing feedback) but does not explicitly mention when not to use it or contrast with alternative tools. Since siblings are unrelated, the usage context is understood but not formally 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=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: hosted by the platform, no platform credentials required, pay-per-query with prepaid credit, and LGPD responsibilities. These details go beyond the annotations and help set agent expectations about cost and legal 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?

The description is a concise four-sentence paragraph that front-loads the primary purpose ('consulta em fonte oficial') before covering hosting, payment, and LGPD. Each sentence adds meaningful context, though the legal boilerplate could be trimmed for an agent-focused description.

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 five parameters, no output schema, and no description of return values or mailbox specifics, the tool feels incomplete. The description focuses on commercial and legal aspects but lacks functional details about what the query does, what inputs are required, and what the agent should expect in the response.

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 five parameters (ie, filtro, pkcs12_cert, pkcs12_pass, ignora_nao_lidas). It only vaguely mentions official data and credentials in general. The agent cannot infer what filters or flags mean, making the tool hard to use correctly.

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 'consulta em fonte oficial' for 'Caixa Postal' from SEFAZ MA, providing a specific verb and resource. It is distinct from the generic sibling tools (authenticate, marketplace). However, it does not explain what 'caixa postal' contains beyond being an official source, so it is not perfectly explicit.

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 use for querying official Brazilian tax/regulatory data, noting it's the same info available to citizens and not confidential. There is no explicit statement of when to use this instead of alternatives or when not to use it, but the context provides enough implied guidance.

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

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

The annotations already state read-only, non-destructive, and idempotent behavior, and the description is consistent with them. It adds useful context by specifying that both the MCP platform and adapter versions are included, though it does not describe output shape or edge cases.

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

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

The description is a single, well-structured sentence with no waste. Every word adds 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?

Given the tool's simplicity, zero parameters, and read-only annotations, the description is largely sufficient for an agent to select and invoke it. It briefly explains what output to expect, though a sentence naming toolkit_info as the alternative for broader environment details would improve completeness.

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

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

This tool has zero parameters and 100% schema coverage, so there is no parameter ambiguity for the agent to resolve. A no-parameter tool baseline of 4 is appropriate.

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

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

The description clearly names the action ('Show') and the resource ('current MCP platform and adapter versions'), so an agent can tell what the tool returns. It is specific, but it does not explicitly differentiate itself from sibling tools like toolkit_info.

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 this tool should be used when an agent needs version information, but it gives no explicit guidance about when to choose it over toolkit_info or other sibling tools. For a zero-parameter informational tool, this implied usage is enough.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the description only adds the specific data returned. It does not contradict annotations. Given the high-quality annotations, the description does not need to repeat them, but could mention that no state changes occur; however, the annotation covers this adequately.

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 uses a colon to enumerate the returned components. It is concise and to the point, with no wasted words or redundancy.

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

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

No output schema is provided, so the description must explain what is returned. It does so comprehensively by listing the exact data points (installed MCPs, connection status, accounts, catalog tool counts), fully meeting the context needs.

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, so schema coverage is effectively 100%. The description provides no parameter information, which is acceptable since there are none. Per the rubric, baseline is 3 when coverage is high.

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

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

The description clearly states the tool returns the current toolkit state, listing specific elements (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like authenticate or connect, which have action-oriented 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 implicitly indicates this is a read-only status check, suitable when needing an overview of the toolkit. It does not explicitly mention alternatives, but the action-oriented siblings (authenticate, connect) are distinct enough that usage is clear. A brief note on when to use it versus other tools would earn a 5.

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