MPT AP e PA: Certidão Negativa de Feitos

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds valuable context: the login flow, token types, permanent vs session-only connection, and the behavior when called with no arguments. No contradictions 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 a single, somewhat long run-on sentence, but every clause carries essential information. It is slightly dense but not bloated, and the structure could be improved with clearer separation of the two modes, but it remains 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 the simplicity (one optional parameter, no output schema), the description fully covers all usage paths: permanent config, session token, and no-args. It also explains the meaning of the returned link and the token. No gaps remain 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?

The schema only defines token as an optional string with no description. The description fully compensates by explaining that token is the JWT to paste for session-only login, and that omitting it returns the login link. This is complete semantic coverage for the single parameter.

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 IDE agents by logging in via browser and copying an access token. It provides two distinct usage modes (permanent via config header, session-only via token), which thoroughly differentiates it from siblings like '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 gives explicit instructions on how and when to use it: for permanent use add to config, for session-only pass token, and with no args to get the link. It does not explicitly mention when not to use it or name alternatives, but the context is clear for most usage 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, idempotentHint=true, and destructiveHint=false, covering safety traits. The description adds useful behavioral detail about output conditions (when authenticated:true vs. when connect_url is provided), which goes beyond annotations and helps the agent set expectations. There is 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 two sentences, front-loaded with the core function ('Returns connection status and URLs'), and provides conditional detail efficiently. Every word adds value—no fluff or redundancy.

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 zero parameters, no output schema, and good annotations, the description is complete for its purpose. It explains the primary return conditions, but could be slightly richer (e.g., mentioning that it also returns pending[] details or what 'per-install URLs' are for). Still, it's adequate for a low-complexity 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 schema has zero parameters, so the description doesn't need to explain parameters. The baseline for 0 params is 4, and the description does not add redundant parameter information. It focuses on output semantics, so a 4 is appropriate.

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, distinguishing it from sibling tools like authenticate and marketplace. It specifies the output behavior ('authenticated:true' and empty pending[] when all providers are connected) and mentions per-install URLs, making the purpose 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?

The description provides clear context on when to use this tool: to check connection status, particularly when credentials are missing. It implies this is a diagnostic tool rather than an action tool, but it doesn't explicitly compare to siblings like 'authenticate' or mention when not to use it. The context is clear but excludes explicit 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?

With only four sparse boolean annotations, the description carries the full burden and delivers: it discloses that invoke runs tools one-off even when NOT installed (key side-effect), that auth and payment follow an interactive link-and-retry pattern, that writes require workspace owner/admin, and that published prompts share via a no-login slug URL. This goes well beyond anything inferable from readOnlyHint=false or openWorldHint=true.

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 text is long (~280 words) but earned its length by covering 14 actions and 23 parameters. It is well-front-loaded (purpose → core flow → key nuances → lesser features), and the 'KEY:' marker usefully flags the most critical behavioral nuance. Minor deductions for density that demands careful reading and the stray Portuguese word 'pontualmente' in an otherwise English description.

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 extreme complexity (14 distinct actions spanning marketplace search, installation, billing, bug reports, and a prompt library), the description covers the high-frequency decision tree exceptionally well but leaves the long tail under-specified: the semantics of `resume`, the cancel/billing flow details, and any output or error contract are absent. Considering the absence of an output schema and required parameters, the description wisely focuses on the 80% case but cannot be called 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?

With 0% schema coverage and 23 parameters, the description earns credit for explaining the semantics of the core data-bearing parameters (action, query, mcp_id, tool_id, arguments, prompt_slug, prompt_vars) through the narrated flow. However, several action-to-parameter mappings remain opaque: `immediate`, `resume`, `conversation`, `message`, `cancel_reason`/`cancel_comment`, and the report_bug/request_mcp parameter sets are never connected to their actions.

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 opening line is a model of clarity: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It names a specific resource (the mcp.ai marketplace), a covering verb/scope (catalog AND execution), and immediately distinguishes itself from siblings like authenticate, connect, and report_bug by establishing itself as the main entry point for discovery and invocation. The core flow (search → describe → invoke) is clearly articulated in one dense sentence.

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 decision criteria for every significant branch: when to choose install vs invoke ('prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT'), when to use list_tools ('lists what is callable right now'), when to use search_prompts vs search, and how to handle credential/wallet-edge cases (return connect/checkout link, user opens, then retry). This is the gold standard for guiding an agent's decision-making.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns by clarifying the tool only reads public data and does not expose confidential information. It adds context about the platform hosting and the prepaid credit model, which goes beyond typical uses. However, it doesn't explain what the response looks like or if there are rate limits, slightly missing the opportunity to fully complement 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 a single paragraph that's packed with information, but it's dense and includes legal jargon (LGPD) not immediately relevant to function. The crucial detail about the tool's purpose is buried mid-sentence. It could be reorganized for 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?

Despite the low schema coverage, the description thoroughly explains the tool's context: it queries official sources, is not for sensitive data, and clarifies data controller responsibilities. It provides enough non-exhaustive context for an agent to decide when to use it. The trade-off between a rich description and absent parameter documentation makes it a bit imbalanced.

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 the two parameters (cpf, cnpj) at all. With no hints in the description, the agent must rely on the parameter names alone. This is a significant miss since the tool's core purpose (making a query) is only implied.

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 query 'Certidão Negativa de Feitos' for MPT AP e PA in an official source. It names the resource (official Brazilian sources), includes specific details like 'CNF' and jurisdiction, and differentiates from siblings by specifying the source's official nature. However, it is verbose with legal/LGPD text that doesn't directly clarify the tool's core function.

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 the tool is used for querying official Brazilian records and is not for confidential data, but it doesn't explicitly state when to use it over alternatives. It includes some context about credential access and payment method but lacks a direct recommendation or comparison to sibling tools. The phrase 'mesma disponível ao cidadão' hints at proper use but isn't a clear usage 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?

The description adds context beyond annotations by advising the inclusion of the conversation array for reproduction, which is useful behavioral guidance. Annotations already declare idempotency and non-destructiveness, and the description does not contradict 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?

Two sentences, front-loaded with the core purpose, no filler. 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 simple reporting tool without an output schema, the description adequately covers what to include (conversation) and the tool's purpose. It is sufficient for an agent to decide when and how to invoke it.

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 zero parameter descriptions, so the description must compensate. It mentions the conversation parameter but does not explain 'message' or 'context'. This adds partial value but leaves the required 'message' parameter under-specified.

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 with specific verbs (report, send) and resources (bug, missing feature, feedback). It distinguishes from siblings like authenticate and marketplace, which are unrelated.

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 clearly implies usage for reporting issues or feedback, which is distinct from the sibling tools. However, it does not explicitly mention when not to use it or alternatives, so it lacks a full exclusion clause.

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 annotations already declare readOnlyHint=true and idempotentHint=true, covering behavioral aspects. The description's use of 'Show' aligns with these annotations, adding no contradiction. It modestly clarifies that it is a read operation.

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 fully conveys the purpose without redundancy.

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 no parameters and no output schema, the description fully satisfies the need for context. It tells the user exactly what will be returned (version info) and implies a read-only operation.

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 no parameters, so semantics are trivially clear. The description does not need to explain any inputs.

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: showing current MCP platform and adapter versions. It is specific and distinguishes from sibling tools like authenticate 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?

While no explicit 'when to use' is given, the purpose is self-evident for a version-info tool. The description implies it is for retrieving version information without side effects, which is sufficient given the simple 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds the content returned (installed MCPs, connection status, accounts, catalog counts). No contradiction. It provides extra context beyond the hints, but not much more.

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?

One concise sentence, front-loaded with purpose, no unnecessary 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?

For a zero-parameter, read-only info tool with clear annotations, the description is sufficient to understand what it returns. It covers installed MCPs, status, accounts, and tool counts. No output schema, but the description explains return content.

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?

Zero parameters, so baseline is 4. No parameter descriptions 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 returns the current toolkit state, listing specific components (installed MCPs, connection status, accounts, catalog tool counts). It distinguishes from siblings like authenticate (action) and marketplace (browsing) by focusing on state introspection.

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?

Does not explicitly state when to use this tool versus alternatives serious. Implied usage: you'd call it to see toolkit overview, but no 'when not to use' or alternative guidance. Sibling list suggests others are for actions, but no explicit context provided.

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