Remuneração de Servidores (Transparência)

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

Annotations only indicate non-read-only and idempotent; description adds that token can be configured as permanent or ephemeral session, and explains user must log in via browser and copy the JWT. It clarifies that calling with no args returns a login link, which is useful behavioral context beyond 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 a bit long (multiple clauses) but every sentence serves a purpose: purpose, best practice, and two invocation modes. It's reasonably structured, though could be tightened.

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 simple one-param tool with no output schema, the description covers how to invoke it, what happens with/without token, and the persistence options. It doesn't mention error handling or output format beyond 'link', but that's acceptable for this simple 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 has a single 'token' with no description (0% coverage). The description fully explains the token parameter: it's an optional JWT that, when provided, authenticates the session; when omitted, the tool returns a login link. This compensates completely for 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 states the tool handles authentication for MCP.AI IDE agents: user logs in via browser, copies an access token, and either configures it as a permanent header or passes it to this tool for a session. It explains the tool's role (obtaining a login link or accepting a token) and distinguishes itself by focusing on auth, unlike siblings like 'connect' or '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?

Provides explicit invocation patterns: no args to get a link, or with a token for session-only login. It also gives a best-practice alternative (config header) for permanent connections. However, it does not explicitly contrast with sibling tools or state when not to use 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, which cover safety. The description adds value by explaining exactly what is returned in different scenarios (authenticated:true vs. connect_url), providing behavioral detail beyond annotations. No contradictions.

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 consists of two concise sentences that front-load the purpose and then provide conditional behaviors. Every word earns its place, with no fluff or repetition.

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 tool without an output schema, the description covers the key return values and states adequately. However, it does not specify the overall response format (e.g., JSON structure), leaving some ambiguity for the agent.

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 schema coverage is trivially 100%. The description adds no parameter-specific semantics, but none are needed. Baseline for 0 params is 4, which is appropriate here.

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: 'Returns connection status and URLs.' It distinguishes from siblings like authenticate by focusing on status rather than performing authentication. Specific conditions are provided for different states.

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 context is implied through the description of states (all connected vs. credentials missing), but no explicit guidance on when to use this tool vs. alternatives like authenticate or toolkit_info. It does not state exclusions or name alternative tools.

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 only say non-read-only, non-idempotent, and open-world, the description adds critical behavioral context: invoke runs a one-off tool even if not installed, may trigger a hidden install, returns connect/checkout links for auth or payment and requires retry, and writes require workspace owner/admin. It also clarifies search/describe flag installation state and the prompt library's shareable links without login. This goes far beyond the structured 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 dense and informative but runs long as a single paragraph. It front-loads the core purpose and then elaborates on each action group, which is efficient given the tool's complexity. A more structured format (bullets or section breaks) would improve readability, but every sentence is substantive and 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 23 parameters, no output schema, and sparse annotations, the description still covers the full action inventory, auth/permission requirements, edge cases (connect link, checkout/top-up, one-off install), and the separate prompt library. It gives the agent everything needed to decide which action to invoke and what to expect, making it highly complete for this complex 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 effectively explains the core parameters (action, query, mcp_id, tool_id, arguments) and the prompt-related params via the prompt library explanation. However, it does not individually document all 23 parameters (e.g., tier_slug, cancel_reason, conversation, prompt_targets), leaving some ambiguity for less common fields. Still, it successfully maps the primary flows to the relevant 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 opens with a precise definition: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It explicitly states it covers capability requests and distinguishes from siblings by detailing the search→describe→invoke core flow, which sets it apart from simpler 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 provides explicit guidance on when to use each action: prefer invoke for single/occasional use, use install only to make an MCP permanent, use list_tools to see what is callable now, subscribe/cancel for billing, report_bug for feedback, request_mcp for new MCPs. It also contrasts with alternatives and gives concrete conditions (e.g., 'if the MCP needs a credential/login, invoke returns a connect link').

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. Description adds context about using the conversation for reproduction, which is helpful. However, it doesn't disclose side effects (e.g., where the report goes, if a ticket is created) or permission requirements. With annotations present, a neutral score 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?

Single sentence, front-loaded with the action, and no unnecessary words. Clearly communicates the core purpose and the one important parameter.

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 3 params and no output schema, so the description is mostly adequate. However, the missing explanation for the required 'message' parameter and the conversation string/array ambiguity leave gaps for correct invocation. It's minimal but not fully 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 has 0% description coverage, so the description must compensate. It mentions the conversation parameter and its purpose ('recent messages for reproduction'), but does not explain the required 'message' parameter or the optional 'context'. Also, the description calls conversation an 'array' while the schema defines it as a string, creating ambiguity.

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's purpose: 'Report a bug, missing feature, or send feedback.' Uses specific verb 'report' and resource (bug/feedback). Distinct from sibling tools like authenticate or marketplace, so no ambiguity.

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 is implied by the purpose ('if you have a bug, report it') but there are no explicit when-to-use or when-not-to-use instructions, nor alternatives mentioned. The instruction to include the conversation array is a practical guideline for reproduction, but not a full usage policy.

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 cover safety with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the nuance that versions are 'current,' but discloses no further behavioral traits such as network calls or authentication. Given the simple nature of the tool and annotation coverage, this is acceptable yet minimal.

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 concise sentence that is front-loaded with the verb. Every word contributes meaning, with no fluff or redundant qualifiers.

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 fully complete. It states exactly what versions are shown, and the lack of output schema or return format explanation is acceptable given the trivial nature of the tool and the strong annotation coverage.

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?

There are zero parameters, and the schema properties are empty. Per the baseline for 0-param tools, the description does not need to explain parameters. The schema description coverage is 100%, so no gaps exist for the description to fill.

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: 'the current MCP platform and adapter versions.' This unambiguously distinguishes it from sibling tools like authenticate or marketplace, which serve different 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 purpose clearly implies when to use this tool (checking versions), but there is no explicit statement about when to prefer it over alternatives or any exclusions. The context is obvious given the sibling tools, but the description itself provides no explicit 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 and destructiveHint=false, providing the safety profile. The description adds concrete detail about the returned state (installed MCPs, connection status, accounts, catalog tool counts), going beyond the annotations. However, it does not mention potential behavior like network calls or data freshness, leaving a small gap.

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 core purpose ('Returns the current toolkit state') and then efficiently enumerates the components. Every phrase earns its place with no fluff.

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 fully specifies what the tool returns and is operationally complete. It provides all necessary context for an agent to decide when to invoke this 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?

The tool has zero parameters, so the baseline score is 4. The description needs no parameter-specific semantics because there are no parameters to explain.

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 clear verb 'Returns' and specifies the resource 'current toolkit state' with four distinct data components (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like authenticate or 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 clearly implies usage for inspecting the toolkit's current state, but it does not explicitly state when to use it versus alternatives or list exclusions. The context is strong enough for a state-read tool, yet lacks explicit 'when to use' 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 readOnly, idempotent, and non-destructive hints. The description adds meaningful behavior beyond these: it explains the cost model (prepaid per-query) and clarifies that the data is public, not private or confidential, with LGPD compliance responsibilities. This is valuable context 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 front-loaded with the primary purpose, followed by four sentences of relevant contextual information (hosting, cost, data accessibility, LGPD). While the legal sentence could be condensed, every sentence serves a purpose and there is no redundancy or filler.

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 query tool with strong annotations, the description covers the core intent, data accessibility, and compliance context. It omits the return format and details of the optional parameter, but given the simplicity and the explicit purpose, it is reasonably 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 mentions CPF and month/year as input criteria, adding some semantic meaning for two required parameters. However, it does not explain the format of CPF/MesAno nor the optional 'completo' boolean, leaving gaps in parameter understanding.

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: querying remuneration of a federal executive branch public servant using CPF and month/year. This specific verb-resource combination ('Remuneração de um servidor... no Portal da Transparência') distinguishes it from the unrelated sibling tools (authenticate, marketplace, etc.).

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 useful context: the tool is hosted by the platform, requires no credentials, and is paid per query with prepaid credit. It does not explicitly state exclusions or alternatives, but the sibling tools are functionally unrelated, so the context is sufficient to guide appropriate use.

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