TCE SP: Certidão de Apenados

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

Discloses behavior: returns a link when called with no args, accepts a token for session login. Also mentions permanent config. Annotations indicate idempotent and non-destructive, which aligns; however, no mention of what happens after successful auth (e.g., response format) but given idempotentHint and no output schema, this is sufficient.

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 but front-loaded with the main purpose. It's structured with clear instructions and alternatives, but could be condensed slightly without losing critical 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?

Given a simple tool with one optional parameter and no output schema, the description is complete enough: it covers the two invocation modes and permanent config. It doesn't describe the output, but that's acceptable given no output schema and the tool's role.

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 explains the token parameter meaning: optional JWT for session-only login. That is useful explanation for the single parameter, even though it could be more detailed about format requirements. Baseline 3 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 it authenticates the user for MCP.AI in IDE agents, explaining the login flow. It distinguishes from siblings like 'connect' by specifying browser-based login and token 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?

Provides explicit when-to-use guidance: call with no args to get the link, or with token after user pastes. Also explains alternative permanent config option, which is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context about the response shape: it returns authenticated:true with empty pending[] when all providers are connected, and connect_url with per-install URLs when credentials are missing. This goes beyond the annotations and helps the agent anticipate outcomes without needing to call the tool.

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 concise, two sentences, with the main purpose front-loaded. It avoids redundancy and wastes no words. Each clause adds necessary information about behavior and response conditions.

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 zero parameters and strong annotations, the description is quite complete. It explains the two primary states and the returned fields (authenticated, pending, connect_url). Without an output schema, it provides sufficient detail for an agent to understand what to expect. It could mention the exact structure of pending array or URLs, but the current level is adequate for typical use.

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 is 4 per the rubric. The description does not need to document parameters, and it doesn't. It correctly focuses on the return behavior instead. No parameter semantics are required.

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 the tool returns connection status and URLs, which is a specific verb+resource. It distinguishes from siblings like authenticate (which likely performs auth) and toolkit_info (which gives general info) by focusing on connection state. It clearly explains the two outcome states, making the purpose unambiguous.

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 it: to check connection status before or after authentication. It doesn't explicitly mention alternatives or when-not-to-use, but the context is clear because it contrasts with authenticate. It gives conditional behavior, which aids in usage scenarios. However, it could explicitly say 'use this to verify credentials before calling authenticate' to be more directive.

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 sparse annotations (readOnlyHint=false, openWorldHint=true), the description enriches behavioral context: it explains that invoke runs MCPs without permanent installation, that writes require workspace owner/admin, that paid/credential cases return actionable links, and that search/describe flag installation status. No contradictions; it adds substantial value over 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 long but densely packed with essential information for a very complex tool (14 actions, 23 params). It front-loads the core flow and key distinctions, and each sentence contributes new operational knowledge. It could be improved with structured lists or headers, but it remains readable and efficient for the scope.

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 no output schema and many actions, the description covers the primary workflow, alternative usage, permissions, and the prompt library thoroughly. It omits detailed behaviors for some actions (e.g., resume, subscribe/cancel specifics) and does not explain the return format, but given the breadth, it is sufficiently complete for an agent to decide when and how to invoke the 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?

With 0% schema description coverage, the description must compensate for parameter meaning. It explains the critical action parameter (with all enum values), and contextualizes mcp_id, tool_id, arguments, and prompt-related parameters. However, it leaves some parameters unaddressed (e.g., limit, conversation, report_context, request_details) and does not detail the arguments JSON schema. Despite gaps, it covers the pivotal parameters sufficiently.

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 dual role as a marketplace catalog and executor of MCPs, with a specific verb and resource. It distinguishes itself from sibling tools (authenticate, connect, etc.) by framing itself as the unified platform for searching, describing, installing, and running MCPs, while also covering the prompt library functionality.

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 when-to-use guidance with a core flow (search → describe → invoke) and contrasts permanent install vs one-off invoke. It also details fallback behaviors for auth/payment (connect/checkout links) and clarifies when to use list_tools, subscribe/cancel, report_bug, and request_mcp. This is exemplary usage 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 signal readOnlyHint=false and destructiveHint=false. The description adds the useful context that the conversation array is used for reproduction, but it does not disclose outcomes such as whether feedback is persisted, sent externally, or whether a confirmation is returned. 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?

Two short sentences with no filler. The first sentence states the purpose, and the second provides essential invocation guidance. 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 three-parameter tool, the description covers purpose and one parameter's role. However, with no output schema, it fails to explain what happens after reporting (e.g., response, confirmation, or success/failure), and the 'message' and 'context' parameters remain undefined.

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 must compensate, but it only clarifies the purpose of the 'conversation' parameter ('with recent messages for reproduction'). The required 'message' parameter and the optional 'context' parameter are left unexplained, leaving a significant gap.

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 specific verb and resource: 'Report a bug, missing feature, or send feedback.' This clearly differentiates the tool from its siblings (authenticate, connect, marketplace, etc.) and leaves no ambiguity about its 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 purpose implicitly indicates when to use the tool, but no explicit when-to-use or when-not-to-use guidance is given. The instruction to 'Include the conversation array...' is a how-to detail, not a usage guideline for choosing this tool over 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, so the agent knows this is a safe read operation. The description adds the specific scope (platform and adapter versions) but doesn't disclose additional behavioral traits like whether it requires network access or returns specific formats. Given annotations cover the safety profile, 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?

Single, clear sentence that is front-loaded with the action and object. No 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?

The tool is simple: no parameters, no output schema. The description adequately conveys what it returns (versions) without needing further details. It is complete enough for its trivial functionality.

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, and the schema has 100% coverage. The description mentions no parameter details, but there are none to document. Baseline of 3 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 specifies a clear verb ('Show') and resource ('current MCP platform and adapter versions'), which is distinct from siblings like authenticate or connect. However, it does not explicitly differentiate from toolkit_info, which might also provide version information, so it loses a point for lack of explicit sibling differentiation.

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 guidance on when to use this tool versus alternatives. With sibling tools like toolkit_info, it would be helpful to mention that this tool is specifically for version checking, but no such guidance is provided. The description simply states what it does without context on when to invoke 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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds genuinely valuable traits: pay-per-query cost implications, no-auth-required hosting, official-source-only data provenance, and LGPD data-controller responsibilities.

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?

A dense but efficient single paragraph where every clause carries meaning—purpose, hosting, auth, pricing, data source, and legal context all in four sentences. Slight deduction for being an unstructured wall of text with no bullets or parameter callouts.

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?

Strong on business and compliance context (prepaid credit, no credentials, official sources, LGPD ownership) and no output schema exists to document. However, for a 3-parameter tool with 0% schema coverage, the absence of parameter semantics leaves a real usage gap.

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% (no parameter descriptions, no enums), and the description provides zero information about cpf/cnpj format (mask, digits) or valid values for tipo_certidao. With low schema coverage, the description needed to compensate but doesn't.

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 'Certidão de Apenados' via 'consulta em fonte oficial,' giving a specific verb+resource. It's readily distinguishable from infrastructure siblings like authenticate or report_bug, though the differentiation is implicit rather than explicit.

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?

Useful contextual guidance is present: 'sem credenciais da plataforma,' 'pague por consulta com crédito pré-pago,' and data-source scope (official Brazilian sources, not confidential). However, there's no explicit when-to-use or when-not-to-use guidance against alternatives, and no exclusions.

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 safety profile is covered by structured data. The description adds value by specifying exactly what state is returned (MCPs, statuses, accounts, catalog counts), but does not disclose additional behavioral details such as whether account information is masked, whether network calls are made, or staleness of the reported state. It doesn't contradict the annotations, but it could add depth.

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?

A single sentence front-loads the action ('Returns the current toolkit state') followed by a colon and a tight enumeration of the four state components. Every word earns its place — no fluff, no 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 zero parameters, no output schema, and a fully-annotated safety profile (read-only, idempotent, non-destructive), the description's enumeration of the returned state fully satisfies the information need. There are no remaining gaps for a state-inspection tool of this complexity; the sibling set (connect, authenticate, marketplace) further contextualizes its role.

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 exist and schema coverage is trivially 100%, so the rubric baseline is 4. The description properly focuses on return semantics rather than parameters, which is exactly right for a parameterless introspection tool.

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?

Uses a specific verb ('Returns') plus a clearly defined resource ('the current toolkit state') followed by a colon-delimited list of exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This level of specificity clearly differentiates it from action-oriented siblings like 'connect' and 'authenticate'.

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 when to invoke this tool — any time you need visibility into the current toolkit state including MCP installations and connection status — and effectively implies it pairs with action-oriented siblings like 'connect' and 'authenticate'. However, it never explicitly states 'use this instead of X' or spells out exclusions, though for a state-inspection tool the context is self-evident.

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