MTE: Relatório de Transparência Salarial

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

The description adds meaningful behavioral context beyond annotations: explains the effect of different calls (permanent vs session), the token usage, and that the tool provides a link when called with no args. Annotations indicate idempotent and non-destructive, which is consistent with the description, so 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, information-dense sentence that front-loads the purpose and then details both usage modes. It earns its length with all useful details, though it could be slightly more concise without losing 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?

For a simple tool with one optional parameter and no output schema, the description covers all necessary aspects: what it does, how to use permanent vs session modes, and when to call with no args. It is complete for an agent to select and 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 description coverage is 0%, but the description completely compensates for the single parameter 'token': it explains that it expects a JWT and how to use it (paste it here), and also explains the no-args variant. This fully covers 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: authenticating to MCP.AI for IDE agents, with specific instructions for two modes (browser login link with no args, or accepting a token). It uses specific verbs ('log in', 'authenticate') and distinguishes from sibling tools by focusing on auth for IDE agents.

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 guidance on two usage modes: best practice (config header for permanent connection) and session-only (passing token), plus when to call with no args to get the link. It doesn't explicitly mention when not to use or alternative tools, but the context is clear enough for selection.

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 read-only nature is covered. The description adds value by explaining what the actual response contains (authenticated field, pending array, connect_urls for toolkit and per-install), which goes beyond the annotations' 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?

Two concise sentences, highly informative with no fluff. Every piece of information is meaningful and contributes to understanding the tool's purpose and behavior. Front-loads the main purpose and then gives specific return details.

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 status-checking tool with no parameters and no output schema, the description fully covers the behavior. It explains both success and failure modes, which is complete for this tool's complexity. No output schema exists, so no need to describe 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?

Since the tool has 0 parameters, the schema is fully covered (100% coverage is trivially true). Per guidelines, 0 params = baseline 4. The description doesn't need to add parameter semantics, and it does a good job explaining what the tool returns, which is the only relevant semantic.

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', specifying verb and resource. It distinguishes itself from siblings by detailing the output format (authenticated:true, pending[], connect_url), though it doesn't explicitly name sibling tools for comparison.

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 this tool: to check if all providers are connected and to get connection URLs. It provides context on what the output looks like in both connected and missing-credentials scenarios, offering clear context without explicitly stating alternatives.

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 annotations, the description discloses key behaviors: invoke runs one-off without installing, returns connect or checkout links when credentials/wallet are needed, writes require workspace owner/admin, and published prompt links open without login. This adds substantial context that the annotations alone do not provide.

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 long but dense and organized: core flow, invoke key behavior, install vs invoke, billing/feedback/request actions, permissions, then prompt library. It front-loads the most important usage guidance, though a bit more structural formatting (e.g., bullets) would improve scannability.

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 multi-action tool with no output schema, the description covers the main flows, auth/billing behavior, permission requirements, and the prompt library. It is missing some details such as the 'resume' action and several advanced parameters, so it is not fully exhaustive but is strong overall.

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 carries the burden and does explain many parameters: action values, mcp_id, tool_id, arguments, prompt_slug, prompt_vars, prompt_body, and prompt_title. However, several parameters like limit, immediate, tier_slug, conversation, cancel_reason, report_context, request_details, and prompt_targets are not semantically described, leaving 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 clearly identifies the tool as the mcp.ai marketplace catalog and execution layer, with a specific core flow: search → describe → invoke. It also distinguishes the prompt-library sub-capabilities from the MCP actions, and the mention of report_bug/request_mcp differentiates it from sibling 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?

The description gives explicit when-to-use guidance: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', 'list_tools lists what is callable right now', and 'request_mcp asks us to build a NEW MCP when nothing fits'. This clearly steers the agent between marketplace actions and alternatives.

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, which cover the safety profile. The description adds transparency about the business model (payment per query with prepaid credit) and data governance (customer is data controller under LGPD), which are valuable behavioral traits beyond the annotations. It also clarifies the data is not confidential. However, it doesn't mention rate limits or response format, so it doesn't go beyond what annotations provide in terms of operation behavior.

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 that is concise, but it packs several pieces of information (source, payment model, data nature, LGPD responsibility) without clear structure or front-loaded key details. It is not overly long, but the purpose could be stated more directly upfront. The information is relevant but could be better organized into sentences with clearer focus on the main action.

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 has only one parameter and no output schema, the description should explain what the tool returns and what the query entails. The description covers the data source and legal aspects, but it omits details on the return format, possible errors (e.g., if CNPJ is invalid), and any limitations. With a single required parameter, the description is decent, but it could be more complete by stating that it returns the salary transparency report data for the given CNPJ.

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 one parameter 'cnpj' with no description, and schema description coverage is 0%. The description does not explain the format, length, or expected value of CNPJ (e.g., with/without punctuation, leading zeros). This is a critical gap because a wrong format could cause errors in querying the official source. The description should have provided at least a hint about the CNPJ format.

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 it is a query tool for the MTE Salary Transparency Report ('Relatório de Transparência Salarial, consulta em fonte oficial'), which is a specific verb+resource. It also clarifies the data source (official Brazilian sources) and that it is not confidential, distinguishing it from other tools in the marketplace context. The sibling tools are general platform utilities, so this stands out as a specific data consultation tool.

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 indicates the tool is for querying official data and mentions payment per query with prepaid credit, which implies usage context (paid consultation). However, it does not provide explicit when-to-use vs. alternatives or when not to use it, and the sibling tools are not alternatives for this data lookup. It lacks explicit guidance on prerequisites or scenarios where this tool should be preferred or avoided.

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 idempotentHint=true and destructiveHint=false, so the tool is safe to call multiple times. The description adds that it sends feedback and includes conversation for reproduction, but does not disclose what happens after submission (e.g., confirmation, storage). 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 two sentences, front-loaded with the purpose, and includes a key usage 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?

Given the tool's simplicity (3 params, no output schema, no nested objects), the description covers the main purpose and the important 'conversation' parameter. However, it lacks details on expected format for 'message' or 'context', and does not clarify what happens after submission. Adequate but not 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?

Schema description coverage is 0%, so the description must compensate. It mentions 'conversation array' and 'recent messages' for reproduction, which adds meaning to the 'conversation' parameter. However, it does not explain 'context' or 'message' beyond what the schema provides. The description partially compensates but not fully.

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: reporting bugs, missing features, or sending feedback. It distinguishes itself from sibling tools by focusing on user feedback rather than authentication, connection, or information 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 implies when to use the tool (when reporting issues or feedback) but does not explicitly state when not to use it or mention alternatives. It provides a hint about including conversation context for reproduction, which is useful but not a full guideline.

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 and side effects. The description adds specific context (platform and adapter versions) but does not go beyond this, offering minimal additional behavioral detail like output format or error scenarios.

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, front-loaded with the core purpose, and contains zero extraneous words. It is perfectly concise and directly communicates the tool's function.

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 extremely simple (no parameters, no output schema). The description fully conveys its purpose and scope (platform and adapter versions). No additional details are necessary for an agent to correctly select and invoke this tool, especially with annotations covering safety.

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 description does not need to explain parameter semantics. The schema coverage is 100% (no properties), and the baseline score of 4 is appropriate given there is nothing to clarify.

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 a specific verb ('Show') and resource ('current MCP platform and adapter versions'), fully distinguishing it from sibling tools like authenticate, connect, or marketplace. It unambiguously identifies what the 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?

No explicit guidance on when to use this tool vs alternatives is provided. However, the purpose is straightforward and there are no competing version-checking tools among siblings, so usage is implied rather than 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, which clearly communicate that it is a safe read operation. The description adds what information is returned (installed MCPs, status, accounts, counts), which is somewhat repetitive but adds a bit of context. It doesn't mention any potential latency or need for previous authentication, but the low complexity and annotation coverage keep this acceptable.

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, compact sentence that packs all necessary information without fluff. It is front-loaded and efficient.

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 that the tool takes no parameters and has no output schema, the description is quite complete as it enumerates the key outputs. It could perhaps mention that some data may be missing if not connected, but that is a minor nuance. Overall, it provides a clear expectation of what the tool returns.

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, so the schema is trivially covered (100%). The description doesn't need to explain parameters. A baseline 4 is appropriate because no parameters require clarification and the description focuses on the return content instead.

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?

Description clearly states the tool returns the current toolkit state, listing specific elements (installed MCPs, connection status, accounts, catalog tool counts). It is a specific verb+resource that distinguishes it from siblings like authenticate, connect, marketplace, and show_version.

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 as an overview/diagnostic tool given its informational nature. It doesn't explicitly state when not to use it or contrast with alternatives, but the context of being a read-only informational tool and the sibling names make it a likely go-to for checking state before other operations. Minor gap in explicit guidance.

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