Tribunal TST: Validação de CNDT

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

Annotations already mark the tool as idempotent and non-destructive; the description adds context about permanence and session behavior, and clarifies the different ways the tool can be invoked. 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?

At roughly 50 words, the description is somewhat verbose but all sentences serve a purpose, covering both usage modes and configuration steps. It is front-loaded with the tool's purpose, making the structure logical.

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 invocation scenarios and the distinction between permanent and session logins. It lacks explicit error-handling information, but that is not essential for 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 only parameter, token, is not described in the schema (0% coverage), but the description explains it is a JWT to be pasted, and that omitting it returns a link. This fully compensates for the schema gap, though it does not specify validation rules.

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: logging into MCP.AI by obtaining and providing an access token. It uses verbs like 'log in' and 'paste' and explains the two invocation modes, though it does not explicitly differentiate from the sibling tool '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?

Provides explicit guidance on when to use each method: adding the token to config for a permanent non-expiring connection versus passing a token for session-only login. Also instructs to call with no args to get the link, leaving no ambiguity about usage.

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 and idempotentHint, and the description adds specific behavioral details: the exact response when all providers are connected versus when credentials are missing. It provides meaningful context beyond annotations, though it doesn't cover partial connection states.

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, then elaborates with conditional outcomes. No redundant or tangential information.

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 output schema, the description must convey return values. It explains the two main scenarios but doesn't mention partial connections or error cases. Given the tool's simplicity and no parameters, this is largely sufficient, though slightly incomplete.

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. The description appropriately focuses on output semantics instead, providing clarity on response fields without needing to explain input 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 clearly states it returns connection status and URLs, and distinguishes from sibling 'authenticate' by focusing on status rather than action. It specifies exact return fields (authenticated, pending, connect_url), 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 (checking connection status) by describing the two outcome scenarios. It doesn't explicitly exclude alternatives like 'authenticate', but the context is sufficient for an agent to infer the appropriate usage.

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 provide readOnlyHint:false and sparse hints, so the description carries full burden. It discloses extensive behavioral details: 'invoke works even when the MCP is NOT installed', the auth-handling flow ('returns a connect link'), billing edge cases ('returns a checkout/top-up link... then you retry'), permission requirements for writes, and the prompt library's no-login sharing. This goes far beyond the annotations and is exactly the kind of context agents need.

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 dense, single-paragraph wall of text with no bullet points, headers, or visual separation. While every sentence carries meaningful information, its length (300+ words) makes it hard to scan. It could be structured with a short flow explanation, action list, and prompt-library section to improve readability. Functional but not concise.

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 enormous surface area (23 params, 14 actions, prompt library, multiple auth/billing/permission edge cases), the description is remarkably complete. It covers the primary flows, prerequisites (owner/admin), error scenarios (auth/checkout links), and even the shareable link behavior. Minor gaps remain for secondary parameters and no detailed return/error schema, but it is well above minimum viable.

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 explains the core `action` values, the role of `tool_id`, and the prompt-library parameters (e.g., prompt_slug, publish_prompt). However, with 23 parameters, many (e.g., `tier_slug`, `immediate`, `conversation`) are never explicitly documented. It does a great job with the most critical ones but leaves some gaps for less common 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?

Opens with a clear, specific statement: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It explains the tool's role with concrete capability examples ('find an MCP that does X', 'consulta um CPF') and outlines the core flow (search → describe → invoke). This clearly distinguishes it from sibling tools like authenticate or report_bug by defining its meta-catalog and execution scope.

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?

Explicitly contrasts usage patterns: 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use.' It also covers when to use each action ('list_tools lists what is callable right now', 'subscribe/cancel handle per-MCP billing', 'report_bug sends feedback', 'request_mcp asks us to build a NEW MCP'). It even disambiguates the prompt library from MCP tools. This is textbook when/why 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?

The description mentions including conversation data but does not elaborate on side effects or data handling. The annotations (idempotent, non-destructive) are present, but the description adds limited transparency beyond those.

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 succinct, with no unnecessary words, and directly conveys the core purpose and a key usage detail.

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?

While the description gives the tool's purpose and a hint about conversation, it fails to cover all parameters and does not provide enough context for users to correctly utilize the tool without external knowledge.

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 description only mentions the 'conversation' parameter, while leaving 'context' and 'message' completely unexplained. Since the schema has no descriptions, this is a major gap for a 3-parameter 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?

The description clearly states the tool's function: reporting bugs, missing features, or sending feedback, with a specific instruction to include conversation for reproduction. It is distinct from sibling tools like authenticate or 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?

It provides guidance on what to include (the conversation array) but does not explicitly state when to use this tool versus alternatives, nor any prerequisites or typical 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 indicate read-only, idempotent, and non-destructive behavior, so the description need not repeat that. It adds the specific output scope (platform and adapter versions), which is useful but limited. No contradictions are present.

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, focused sentence with no filler. It is immediately understandable and front-loads the primary action and target.

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-argument, read-only version tool, the description is sufficient: users know what the tool does and what it returns. There is no destructive or complex behavior requiring additional context. A slightly richer note about why this info might be used could warrant a 5, but the basic need is met.

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, so the description need not explain parameter meaning. The baseline of 4 applies because parameter semantics are not relevant; the schema is empty and the tool action is self-contained.

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 identifies the exact resources ('current MCP platform and adapter versions'). This clearly distinguishes the tool from siblings like authenticate, connect, and marketplace, as it is uniquely about version information.

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 is given about when to use this versus sibling tools. However, the intended use is strongly implied by the name and description: call it when version infomation about the MCP platform or adapters is needed. It does not mention alternatives or exclusion cases.

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 well covered. The description adds value by specifying exactly what information is returned (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the annotations. It doesn't mention any side effects, but none are expected given the read-only nature.

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 and lists the key output components. Every element is informative, with no filler or redundancy. It is concise and easy to parse.

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 (no parameters, no output schema, read-only), the description is complete enough. It covers what the tool does and what it returns. It could potentially mention that it's a snapshot or that it might require prior authentication, but that's not necessary for a basic info tool. The annotations and zero-parameter schema make this adequate.

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 doesn't need to explain parameter semantics. The schema coverage is 100% (trivially, since there are no properties). The description adds value by explaining what the tool returns, which is the main semantic content. A baseline of 4 is appropriate for a no-parameter 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?

The description clearly states the tool's purpose: it returns the current toolkit state, listing installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific and distinguishes it from sibling tools like authenticate or connect, which handle setup rather than 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?

The description implies this is a read-only informational tool for checking the toolkit's state, which is clear from the context. It doesn't explicitly state when to use it versus alternatives, but given the sibling tools are action-oriented (authenticate, connect, marketplace), the usage context is reasonably clear. No exclusions are mentioned, but the purpose is self-evident.

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 read-only and idempotent behavior. The description adds billing model (prepaid credit), access method (no platform credentials), and LGPD compliance responsibilities, which provide valuable operational context beyond the booleans.

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, front-loading the purpose before legal and billing details. It's relatively concise, though the hosting/credential phrase could be tightened without losing meaning.

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 read-only query tool with four self-explanatory parameters and no output schema, the description covers purpose, source, costs, and legal responsibilities well. The only gap is the lack of parameter usage details, but overall it's sufficient for a 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?

With 0% schema description coverage and no parameter explanations in the description, it fails to compensate for the missing parameter documentation. Though parameter names like 'numero_certidao' and 'ano' are self-explanatory to Portuguese speakers, the description provides zero elaboration on expected formats or relationships.

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 this tool validates/consults CNDT from an official TST source, using specific verb 'consulta' and resource 'CNDT'. It distinguishes itself from generic sibling tools like 'authenticate' and 'connect' by covering a concrete, domain-specific operation.

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 clarifies when to use the tool by mentioning no platform credentials are needed and that it's pay-per-query with prepaid credit, setting practical usage context. However, it doesn't explicitly name alternatives or exclusion criteria, though no competing data-query tool exists among siblings.

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