Receita Federal: SIMEI (Declaração Anual)

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

The description discloses behavioral aspects such as the non-expiring nature of the header-based approach versus the session-only nature of pasting a token. It also indicates that calling without a token returns a link, which clarifies expected behavior. Annotations confirm idempotency, which the description does not contradict.

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 somewhat verbose and mixes instructional steps with tool purpose, making it less concise than ideal. However, it is still structured and not overly long.

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

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

The description covers the two primary use cases and the token parameter, but lacks explicit details on what the tool actually does upon successful authentication and potential error cases. It is adequate for the tool's purpose, but not fully comprehensive.

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 token parameter is described as an optional JWT, with the explanation that passing it authenticates, while omitting it yields a login link. This provides meaningful context beyond the schema, which only specifies type and optionality.

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 implies the tool is for authentication, instructing the user on how to log in and obtain an access token. It differentiates between permanent and session-based methods, making the purpose evident, though it could be more 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 provides distinct usage scenarios: adding a header for permanent access or pasting a token for a session, and explains when to call with or without the token parameter. This gives clear guidance on when and how to use the 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?

Given annotations already declare readOnlyHint=true and destructiveHint=false, the description adds extra context by explaining the response shape (authenticated:true, pending[], connect_url) and how it behaves when credentials are missingcars. It also implies the tool may provide per-install URLs, which is useful. No contradiction.

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

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

The description is a single sentence that is moderately concise but includes some redundancy (e.g., 'when all providers are connected' and 'when credentials are missing' are somewhat redundant with 'pending[]'). It is front-loaded with the main action, but the sentence could be tightened without losing 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?

The tool is relatively simple with no parameters and no output schema, so the description covers the key behavioral aspects. However, it doesn't specify the exact format of URLs or how to handle partial connections (e.g., some providers connected, others not), which might be a gap for complete understanding.

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

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

The tool has zero parameterscars, so the parameter semantic burden is minimal. The description clarifies the response semantics (like what authenticated and pending mean) even though it doesn't need to explain parameters. Since schema coverage is 100% (vacuously), baseline of 3 is set; the description adds value by explaining conditions, earning a 4.

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, with specific details about behavior (authenticated:true, pending[], connect_url). While it distinguishes itself implicitly as a status/connect tool, it doesn't explicitly contrast with 'authenticate', but its purpose is clear and specific.

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

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

The description explains what happens in different conditions (all providers connected vs. missing credentials), which implicitly suggests when to use it—to check status or get connection URLs. However, it does not explicitly state when to use it versus alternatives like 'authenticate' or provide any exclusions, leaving room for confusion about when to call this versus initiating authentication.

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 goes well beyond the sparse annotations by disclosing that writes require workspace owner/admin, invoke runs tools one-off without installing them, install makes MCPs permanent, and credential/payment failures return actionable links. There is no contradiction with readOnlyHint=false or openWorldHint=true. This is thorough behavioral disclosure for a complex tool.

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 informative, front-loads the core purpose and flow, and nearly every sentence adds value. It is long and written as a single wall of text, which hurts scannability, but the length is largely justified given the tool's 14 actions and 23 parameters. Minor structure improvements would make it excellent.

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

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

For a complex tool with 14 actions, 23 parameters, and no output schema, the description covers the core decision flow, installation vs. one-off invocation, auth/payment handling, permissions, and the prompt library. It does not specify return shapes for every action, but it provides enough context for an agent to select the right action and understand side effects.

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 23 parameters and 0% schema description coverage, the description must compensate, and it does substantially: it explains the action enum, mcp_id/tool_id flow, arguments, prompt_slug/prompt_vars, and the meaning of the install/invoke distinction. However, several parameters like limit, immediate, tier_slug, conversation, cancel_reason, prompt_targets, and report_context are not explicitly described, leaving some gap.

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

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

The description clearly states this is the official mcp.ai marketplace: the in-platform catalog of every MCP/tool and the way to run them. It establishes a specific core flow (search → describe → invoke) and distinguishes itself from sibling tools such as connect, report_bug, and toolkit_info. It also covers the separate prompt-library capability without confusing it with the MCP catalog.

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

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

The description gives explicit when-to-use guidance: prefer invoke for single/occasional use, use install only to make an MCP permanent, use list_tools for what is callable right now, use request_mcp when nothing fits, and use subscribe/cancel for billing. It also explains when invoke will return connect or checkout links and how to handle them. This is exemplary alternative-selection 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?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context: per-query cost with prepaid credit, absence of platform credentials, official/non-confidential data status, and LGPD data-controller responsibilities. It does not cover response behavior, rate limits, or pagination, but it goes well beyond the annotations.

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

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

The description is compact and front-loads the main purpose before adding operational and compliance details. Each sentence contributes useful context, though the legal/operational phrasing could be tightened. Overall it is appropriately sized.

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 six required parameters, no output schema, and no parameter descriptions, the tool demands more explanation than this description provides. The operational and LGPD context is useful, but the absence of parameter details and return-value description means an agent cannot confidently invoke it correctly.

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

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

Schema description coverage is 0% and the description does not explain any of the six required parameters (cnpj, tipo_declaracao, ano_calendario, receita_bruta_comercio, receita_bruta_servicos, possui_empregado). The SIMEI context only indirectly hints at their meaning, which is insufficient for an agent to know expected formats or valid values.

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 a consult operation on official Receita Federal SIMEI annual declaration data ('SIMEI (Declaração Anual), consulta em fonte oficial'). It gives a specific verb and resource, and it is distinct from generic platform siblings. However, it does not specify exactly what data is returned or fully explain the DASN relationship beyond the name.

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 operational prerequisites: no platform credentials are needed, prepaid credit is required per query, and the data is non-confidential. This implies when the tool can be used, but there is no explicit comparison with alternatives or when-not-to-use guidance. Sibling tools are unrelated, so the usage context is only implied.

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=false, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds the context that a conversation array is needed for reproduction, which is useful but not a deep behavioral disclosure. It does not contradict annotations, but also does not add significant behavioral context beyond what is already structured.

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

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

The description is only two sentences, front-loaded with the purpose, and gives one key directive. There is zero fluff; every word earns its place. It is appropriately sized for a simple tool.

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

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

For a tool with 3 parameters, no output schema, and no nested objects, the description covers the core purpose and a critical usage detail (conversation array). It doesn't explain return behavior, but with no output schema that is not required. It could mention context, but overall it is complete enough for a simple 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?

With schema description coverage at 0%, the description must compensate. It explicitly mentions the 'conversation' parameter and implies the 'message' parameter (the bug/feature content), but does not explain the 'context' parameter at all. This partial clarification helps but leaves a gap for one of the three parameters.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' This is a specific verb+resource combo that distinguishes it from sibling tools like authenticate or connect, which have entirely different functions. No ambiguity exists about what this tool does.

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

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

It explicitly instructs users to 'Include the conversation array with recent messages for reproduction,' which is a practical usage guideline. While it doesn't name alternative tools or state when not to use it, the context implies this is the go-to for bug/feedback reporting, and the conversation array guidance is valuable and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety properties. It adds 'current' to suggest live data, but provides no other behavioral context (e.g., network access, caching). With annotations covering safety, the description is adequate but contributes little 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 a single, well-structured sentence that front-loads the main purpose. No wasted words, perfectly concise for a simple tool.

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

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

For a zero-parameter, read-only version query, the description is complete. It covers what the tool does and implies the return is version information. With no output schema and simple usage, no additional details are 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?

No parameters exist, so the baseline is 4. The description does not need to add parameter explanations; the schema is empty and fully covered. The description correctly focuses on the tool's purpose rather than parameter details.

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

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

The description states a specific verb ('Show') and resource ('current MCP platform and adapter versions'), clearly distinguishing it from sibling tools like authenticate, marketplace, or report_bug. It is concise and unambiguous.

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

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

No explicit guidance on when to use this tool versus alternatives, but given that it is the only tool for version inspection and has zero parameters, its usage is self-evident. The description implies use when version information is needed, but does not actively address exclusions or alternative scenarios.

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 valuable context about the return contents (MCPs, statuses, accounts, catalog counts), going beyond what annotations provide. No contradiction.

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

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

A single, well-structured sentence that front-loads the action and resource, then enumerates the specific details returned. No superfluous content; every word earns its place.

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

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

The tool is simple with no parameters and no output schema, but the description fully explains what it returns and its read-only nature. The annotations cover behavior, and the description adds enough detail for an agent to know exactly what information is provided. Complete for its scope.

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

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

The tool has zero parameters, so the baseline is 4 per the rubric. The description does not need to explain parameters, and the schema is empty, so nothing is missing.

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

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

The description uses a specific verb 'Returns' with a clear resource 'the current toolkit state' and elaborates on the specific contents (installed MCPs, connection status, accounts, catalog tools). This clearly distinguishes it from siblings like show_version and 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 context is clear: this is for checking the toolkit state. However, it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions. Since the purpose is obvious and no alternatives are needed, it meets the 'clear context, no exclusions' criterion.

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