FGTS: Guia de Arrecadação

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

The description discloses behavioral traits beyond annotations: it explains the two login modes (permanent via config header, session-only via token), that calling with no args returns a link, and that the token is a JWT. It does not contradict the annotations (idempotentHint=true, readOnlyHint=false), and adds useful context about the persistence of the connection.

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 front-loaded with purpose. It is generally concise, though slightly dense and could be tightened (e.g., 'MCP.AI for IDE agents' adds audience context but could be seen as extraneous). Overall it is efficient with little waste.

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 tool with one optional parameter and no output schema, the description covers both usage paths, the token format, and the permanent vs session distinction. It does not explain return values (e.g., success message) but that is a minor gap given the tool's simplicity and existing annotations.

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 fully compensates by explaining the only parameter 'token' as a JWT, that it is optional (can omit to get a link), and how to use it. This goes beyond the bare schema property to give complete semantic context.

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 indicates the tool is for authentication, specifying the process (login in browser, copy token) and the two methods (config header or session token). It distinguishes itself from sibling tools (connect, marketplace, etc.) which are not authentication-related, though it could be more explicit in stating 'this tool authenticates the user'.

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 usage guidance, explaining when to add the token to config (permanent connection) versus pasting it for session-only login, and when to call with a token versus no args to get the link. This clearly tells the agent how and when to invoke 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?

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable return-state details beyond those annotations, such as authenticated:true with empty pending[] and connect_url fallback, which helps set expectations without contradicting the 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 two sentences and front-loads the core purpose ('Returns connection status and URLs') before adding conditional details. Every sentence conveys essential behavior with 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?

With no parameters and no output schema, the description covers the key return scenarios: connected state and missing-credentials state. It could theoretically elaborate on partially connected states or the exact shape of pending[], but for a zero-argument status tool this is adequately 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?

The tool has zero parameters and 100% schema coverage, so there is no parameter ambiguity to resolve. The baseline for zero-parameter tools applies, and the description correctly avoids inventing 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 clearly states the tool's function: it returns connection status and URLs. It specifies exact return values for connected versus missing-credentials states, which distinguishes it from siblings like authenticate and provides a specific verb+resource.

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 contextual guidance by explaining the two relevant conditions (all providers connected vs. credentials missing) and what the tool returns in each. It doesn't explicitly name alternatives or when-not-to-use, but the behavior is clear enough for an agent to decide when to call it.

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 readOnly/idempotent annotations, the description adds valuable behavioral context: payment is per query with prepaid credit, no platform credentials are needed, the data is the same as available to citizens and is not confidential, and the client is the data controller under LGPD. This is exactly the kind of extra operational and legal context annotations do not convey.

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 front-loaded with the key resource and official-source qualifier, then adds concise context about hosting, payment, data sensitivity, and LGPD. Every sentence contributes useful information, and the length is reasonable for the tool's complexity.

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 no parameter descriptions, the tool requires more operational detail than this description provides. It explains billing and data governance but omits what the returned guide contains, how login works, and what optional parameters like periodo or representado control.

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 7 parameters, including the required login_cpf and login_senha. The note about 'no platform credentials' is potentially confusing because required credential-like fields exist, and optional fields like pkcs12_cert, representado, pagina, and periodo are completely 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 identifies the tool as a query for FGTS Collection Guide (Guia de Arrecadação) from official Brazilian sources, using a specific verb (consultar/consulta) and resource. It distinguishes itself from generic sibling tools like authenticate or marketplace by naming the exact domain and official-source nature.

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 clear context for use: no platform credentials are required, usage is charged from prepaid credit, and data comes from official Brazilian sources. It does not explicitly list when-not-to-use or name alternatives, but the context is sufficient for selecting this tool over unrelated 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 only give readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes far beyond by detailing write behavior (install/uninstall/subscribe/cancel require owner/admin), the one-off execution behavior of invoke even when not installed, and the handling of authentication (connect link) and payment (checkout link) scenarios. It also explains that search/describe flag installation state, which adds valuable context not in 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 lengthy but appropriately so for a tool with 14 distinct actions and 23 parameters. It is front-loaded with the core purpose and flow, then elaborates on key distinctions (install vs invoke) and additional features. While some redundancy exists (e.g., restating that invoke runs one-off), it remains organized and each sentence adds substantial value.

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 complexity—no output schema, minimal annotations, 23 parameters—the description is exceptionally complete. It covers every action, the execution model (including when credentials/payment are needed), auth requirements, the distinction between installed and one-off tools, and the prompt library functionality. It fully equips an agent to select and correctly invoke any of the documented actions.

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 the burden. It explains the primary 'action' parameter thoroughly by detailing each action's purpose (search, describe, invoke, install, etc.) and how they relate. It also gives context for tool_id, arguments, mcp_id, and the prompt_* parameters by describing the prompt library workflow. However, parameters like limit, query, immediate, and tier_slug are not explicitly addressed, though the overall flow makes their purpose inferable. This is strong compensation but not exhaustive.

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 is the official mcp.ai marketplace, serving as both a catalog and execution engine for MCPs. It explicitly defines the resource (marketplace) and the verbs (search, describe, invoke, install, etc.), and distinguishes itself from sibling tools like authenticate and toolkit_info by covering the full discovery-to-run flow.

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 usage guidance: it explains the core flow (search→describe→invoke), distinguishes between invoke for one-off use and install for permanent additions, and lists when to use request_mcp, list_tools, and the prompt library actions. It also notes when to prefer alternative actions, giving clear when/when-not 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 indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that the tool is for reporting and should include recent conversation, which implies data is submitted for reproduction, but it does not explain permissions, submission side effects, or expected response. This adds some value without contradicting 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 short sentences with no filler. It front-loads the purpose and then adds a practical reproduction instruction, so every clause 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 relatively simple and annotations cover safety traits, but the description fails to clarify all parameters, especially the required message and the optional context. The conversation guidance is partially misleading since the schema expects a string, and there is no output schema to compensate. A little more parameter detail would round it out.

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 had to explain the parameters itself. It only mentions the conversation field and describes it as an array, while the schema defines it as a string with default '[]'. The required 'message' field and optional 'context' field are left 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 the tool's action and scope: 'Report a bug, missing feature, or send feedback.' This makes the purpose obvious and distinguishes it from the sibling tools, none of which handle reports or feedback.

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 gives explicit use cases ('Report a bug, missing feature, or send feedback') and instructs the caller to include the conversation for reproduction. There are no obvious sibling alternatives for this task, so no exclusions are 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 the tool as read-only (readOnlyHint: true), idempotent (idempotentHint: true), and non-destructive (destructiveHint: false). The description adds the qualifier 'current' to indicate live data retrieval, but does not disclose other potential behaviors like output format or response content, earning a baseline score with marginal added 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 is direct and front-loaded with the action and target, containing no superfluous information. It perfectly matches the conciseness criteria.

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 simple nature with no parameters, no output schema, and clear annotations covering safety, the description fully communicates its purpose and expected behavior. It adequately informs the agent that the tool returns version information without requiring further 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?

The tool has zero parameters, and the schema coverage is 100% (no parameters to document). Per the rubric, a baseline of 4 is appropriate for tools with no parameters, as the description need not compensate for any schema gaps.

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 'Show the current MCP platform and adapter versions' clearly identifies the tool's function with a specific verb ('show') and resource ('versions'), and it distinguishes itself from siblings like 'connect' or 'authenticate' by focusing on version 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 provides no guidance on when to use this tool versus alternatives like 'toolkit_info' or 'report_bug'. Although it is a simple version-query tool, there is no explicit context or exclusions, leaving the agent with minimal direction.

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 established. The description adds useful context by enumerating exactly what state is included (installed MCPs, connection status, accounts, tool counts), going beyond bare 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 single, well-structured sentence that front-loads the purpose ('Returns the current toolkit state') and then provides a concise list of details. Every word earns its place, with no redundant or 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?

For a simple no-parameter read-only tool with no output schema, the description sufficiently explains what information is returned. It covers all major categories the agent would need to know, though it doesn't detail the exact output structure or potential caveats, leaving minor room for improvement.

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 the schema coverage is 100% (vacuously). With no parameters to describe, the baseline of 4 applies, and the description correctly focuses on the output 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 uses a specific verb ('Returns') and resource ('the current toolkit state'), and lists concrete components (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes it from sibling tools like connect or authenticate, 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 clearly implies when to use this tool: whenever the agent needs the current toolkit state. However, it does not explicitly name alternatives or state when not to use it, so it lacks the exclusionary guidance that would merit a 5.

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