Receita Federal: Simples (Listagem de Períodos para Emissão de DAS)

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

The description adds behavioral context beyond annotations: it discloses that calling with no args returns a login link, and that the token enables session vs. permanent authentication. It aligns with annotations (idempotentHint=true, destructiveHint=false) and doesn't contradict them. However, it doesn't mention error handling or security implications, which would be useful but not required given annotation coverage.

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 bit verbose but well-structured: it front-loads the tool's audience, then presents two usage paths clearly. Every sentence contributes practical value, and the semicolons and parentheses keep it organized. It's longer than necessary but not bloated.

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 one optional parameter and no output schema, the description is quite complete: covers authentication flow, both usage modes, and parameter semantics. It could mention what happens after successful authentication (e.g., session state), but this is implied. Overall, it provides sufficient context for an agent to invoke 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 coverage is 0%, but the description fully compensates: it explains the token parameter is a JWT from the browser and that it's optional (omitting it yields a login link). This adds meaning far beyond the bare schema, making the parameter's purpose and usage clear.

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: to authenticate a user via browser login and token exchange. It specifies the action (log in, obtain token, authenticate) and the resource (the MCP server). It also distinguishes itself implicitly from siblings like 'connect' and 'marketplace' by focusing on authentication credentials.

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 explicitly explains when and how to use the tool: two distinct methods (permanent config via Authorization header or session-only via token parameter), with clear instructions for calling with or without the token argument. It also provides context about when one method is better than the other, offering practical 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read-only nature is covered. The description adds value by explaining the response format (authenticated flag, pending array, connect_url) and the distinction between toolkit-level and per-install URLs, which goes beyond the annotations. However, it doesn't disclose behavior like potential rate limiting or complexity, but given the safe and idempotent hints, a 3 is appropriate.

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

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

The description is two sentences long, front-loaded with the primary purpose, and provides specific details about the output in different scenarios. It is efficient, with no wasted words, though it could be slightly more structured with bullet points, but for a short description it is appropriately 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?

Given the tool's simplicity (no parameters, no output schema) and the annotations clearly defining its safe read-only nature, the description provides sufficient context for an agent to understand the tool's function and expected output. It could mention that the output is a JSON object, but that is implied. It doesn't need to explain return values deeply since there is no output schema, but the description covers the main scenarios.

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)Skip this. The parameter count is 0; the description doesn't need to explain parameters. The schema coverage is 100% trivially, so the description adds value by clarifying the output semantics rather than parameters. According to the rubric, 0 parameters means baseline 4, and the description effectively explains what the tool returns, which supports that 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 returns connection status and URLs, including specifics about the 'authenticated:true' state and missing credentials behavior. Though it doesn't explicitly differentiate from siblings, the purpose is unambiguous and actionable, and the sibling 'authenticate' implies this tool is for status checking rather than initiating auth.

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 a usage context: to check if all providers are connected and obtain connection URLs when credentials are missing. It does not explicitly state when to avoid using this tool or mention alternatives, but the context is clear enough for an agent to decide when a status check 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?

The description adds substantial behavioral context beyond the annotations. It discloses that invoke works even when the MCP is not installed (one-off, 'runs the tool pontualmente'), that it returns a connect link if credentials are needed and a checkout/top-up link if paid and the wallet is empty (with a retry instruction), and that writes require workspace owner/admin. No contradiction with annotations found; readOnlyHint=false aligns with the disclosed write operations.

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 dense single-paragraph wall of text containing valuable information with a front-loaded purpose statement. It is not 'concise' in the structural sense — there is no use of bullets, sections, or lists to organize the 14 actions and their relationships. However, most sentences do earn their place given the tool's complexity, so it avoids bloat while lacking structural clarity.

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 23 parameters, 14 action enum values, no output schema, and sparse annotations, the description covers the high-level flow (search/describe/invoke/install, prompts, billing, reporting) well. But it leaves significant gaps: most parameter specifics (prompt_*, cancel_*, request_* fields) are only implied, not defined, and the description does not clarify what the invoke response shape looks like or how pagination via 'limit' works.

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%, placing the full burden on the description. It explains the action enum values and the roles of mcp_id and tool_id within the search→describe→invoke flow, but leaves roughly 17 parameters undocumented (prompt_body, prompt_slug, prompt_vars, cancel_reason, cancel_comment, report_context, request_details, conversation, prompt_targets, prompt_category, etc.). Only brief mentions of the prompt library (search_prompts/get_prompt/publish_prompt) touch a few of these, which is insufficient compensation for zero schema coverage.

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 purpose: "The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them." This is a specific resource (catalog/execution platform) with clear verb+resource framing. It naturally distinguishes from siblings like authenticate, connect, and toolkit_info, though the tool bundles 14 distinct actions, making the purpose somewhat diffuse and multi-faceted.

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

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

Usage guidance is explicit and thorough. It states the core flow (search discovers MCPs → describe returns profile → invoke runs the tool), and gives clear when-to vs when-not: "prefer invoke for a single/occasional use" vs "Use install only to make an MCP PERMANENT in the active toolkit." It also names alternatives (list_tools, subscribe/cancel, report_bug, request_mcp) and gives an exclusion ('without adding the MCP to the toolkit').

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

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

Annotations already establish read-only, idempotent, and non-destructive behavior, and the description adds non-redundant detail: no credentials required, prepaid billing model, data is openly available to citizens, and LGPD controller responsibility falls on the customer. This goes beyond the structured annotations without contradicting 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 compact and front-loaded with the core functionality in the first clause, followed by practical billing, access, and legal context. There is minor redundancy around official sources and citizen-accessible data, but the overall size is acceptable and informative.

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 2-parameter read-only lookup, the description is mostly sufficient: it explains the data domain, official source, billing, and legal responsibility. However, it leaves undefined what the returned periods look like, any input format expectations, and possible error or empty-result behavior, which matters because no output schema exists.

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 0% description coverage, and names like 'ano' and 'cnpj' are only minimally descriptive. The description mentions DAS period listing but does not explain the exact role of each parameter, expected formats, or how the year is used, so it fails to compensate for the absent schema descriptions.

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

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

The description clearly identifies the tool as a Receita Federal Simples DAS-period listing feature and states it is a query against an official source. It uses a specific resource ('Listagem de Períodos para Emissão de DAS') and a clear consult operation, easily distinguishing it from the unrelated sibling tools such as authenticate and 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 practical usage context: the tool is hosted on the platform, requires no platform credentials, charges prepaid credits per query, and targets official Brazilian public data available to citizens. It does not explicitly discuss exclusions or alternatives, but enough guidance is present to understand when this tool is applicable.

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 idempotentHint=true and destructiveHint=false, so safety is covered. The description adds that the conversation array is needed for reproduction, which is useful behavioral context. However, it does not explain what happens after calling (e.g., whether it creates a ticket or sends data), so gaps remain.

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

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

Two concise sentences, front-loaded with purpose and a practical hint. No wasted words.

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 core purpose and one param's role, but lacks details on the full parameter set (context, message format) and post-call effects. Given no output schema and low parameter documentation, it is minimally viable but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It only explicitly explains 'conversation' (as an array for reproduction), but does not clarify the format (JSON string) or the meaning of 'context' and 'message'. This is insufficient given zero schema descriptions.

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

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

The description clearly states the tool's verb and resource: 'Report a bug, missing feature, or send feedback.' It distinguishes from siblings (authenticate, connect, etc.) which serve different purposes. The purpose is unambiguous 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?

It names the scenarios (bug, missing feature, feedback) and instructs to include the conversation array for reproduction. It does not explicitly exclude alternatives, but the sibling tools are clearly unrelated. The guidance is adequate for selecting this 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context by specifying exactly what is returned (platform and adapter versions), which is valuable given there is no output 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 sentence that conveys the full purpose without any filler or redundant information. It is front-loaded and 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?

For a zero-parameter, read-only version query tool with rich annotations, the description is complete. It explains what the tool returns and requires no additional behavioral or parameter 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 parameter semantics are not applicable. Per the baseline for zero-parameter tools, a score of 4 is appropriate since there is no parameter ambiguity to resolve.

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 ('Show') and clearly identifies the resource ('current MCP platform and adapter versions'). It is unambiguous and distinct from sibling tools like authenticate or report_bug.

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 when version information is needed, but it does not explicitly state when to prefer this tool over alternatives such as toolkit_info. For a simple zero-parameter version tool, the implied usage is sufficient but not fully explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds meaningful behavioral context by specifying the exact return contents (installed MCPs, connection status, accounts, tool counts), going beyond the generic annotation hints. This is useful for an agent deciding if this tool provides the needed information.

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 ('Returns the current toolkit state') and then lists specific data points. Every phrase earns its place with no filler or repetition of the tool name.

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 informational tool, the description fully specifies what the tool returns: installed MCPs, connection status, accounts, and tool counts. There is no output schema, so this descriptive list serves as the complete contract. No additional caveats or behavior seem necessary for an agent to invoke this tool correctly.

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

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

The tool has zero parameters, so the input schema is trivially complete (100% coverage). The description correctly makes no mention of parameters because none exist. Per the rubric, a baseline of 4 applies for zero-parameter tools, and no extra semantic info is needed.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('current toolkit state'), then enumerates exactly what it reports: installed MCPs, connection status, connected accounts, and count of catalog tools. This distinguishes it clearly from sibling tools like authenticate or connect.

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

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

The description makes it obvious this is a read-only status/info tool, which implies when one would use it (e.g., before connecting or troubleshooting). However, there is no explicit statement about when to use it versus alternatives, no exclusions, or 'use X instead' guidance.

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