Registradores (ARISP) Certidão: Novo Pedido de Certidão Digital

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

The description adds meaningful behavioral context beyond the annotations: it explains the permanent/non-expiring config approach, session-only login, and the no-args link retrieval behavior. This aligns with the idempotentHint and does not contradict any annotation.

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 relatively concise across three sentences and front-loads the audience and purpose. Minor awkwardness in the colon-heavy structure, but every sentence contributes useful 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?

The description covers the login flow, permanent vs. session token options, and no-args behavior. However, there is no output schema and the description does not clearly state what the tool returns beyond 'get the link', nor does it explain error cases or session outcome details.

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 compensates well by explaining that 'token' should be a JWT pasted for session-only login, and that omitting it returns the login link.

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 authenticates to MCP.AI for IDE agents, requiring browser login and token handling. The verb+resource is specific, though it does not explicitly differentiate from sibling tools 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 context: it is for IDE agents (Cursor, etc.) and explains when to use the config header vs. session-only token, and when to call with no arguments. It lacks explicit exclusions or alternative-tool comparisons, but the usage context is strong.

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 (readOnly, idempotent, non-destructive). The description adds value by explaining the two possible response states (authenticated true vs connect_url), which is useful behavioral context not present in 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 main purpose, and contains no fluff. Every sentence provides useful information about the tool's behavior.

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 description covers the two main states (all connected vs missing credentials) but does not explicitly address partial connection scenarios. Since it's a simple status check and the return values are described, it is largely complete, but a note on partial states would improve completeness.

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 schema coverage is 100% trivially. The description doesn't need to explain any parameters, and the baseline for zero params is 4. No additional param info 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's purpose: to return connection status and URLs homespot. It distinguishes between the all-connected scenario and the missing-credentials scenario, which makes it unambiguous compared to 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?

It provides clear context about when the tool is used (to check connection status) but does not explicitly mention alternative tools for specific cases. Given the sibling names, it is inferable, but not explicit.

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?

Description discloses that invoke works even when MCP not installed, returns connect links, and handles payment/credential flows. However, it doesn't explicitly mention destructive effects of uninstall or cancel, and there's a slight mismatch with the destructiveHint annotation.

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?

Description is a long run-on paragraph with no structure, making it hard to scan. It could be broken into bullet points or shorter sentences.

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 complexity, the description covers high-level flows and edge cases (payment, credential) but lacks detailed parameter explanations and output expectations, though no output schema is provided.

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?

Description explains the action enum and some behaviors, but doesn't define most of the 23 parameters like prompt_body, conversation, etc., leaving users to infer from names.

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 it's the official marketplace for MCPs and prompts, covering search/describe/invoke and more. It distinguishes from siblings like authenticate and report_bug as separate concerns, though it's not a single verb but a comprehensive 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?

Description provides explicit guidance on when to use invoke vs install, and mentions alternatives like report_bug and request_mcp. It clearly says 'prefer invoke for single use' and 'use install only to make permanent'.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context beyond this: the query is pay-per-query with prepaid credits, credentials are not shared to the platform, and LGPD compliance responsibilities fall on the client. However, notable gaps exist — it doesn't explain what happens if credentials are missing between email/senha vs pkcs12, or whether the query mutates state (a new 'Pedido' implies creation).

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, dense paragraph that covers the essential context — host, data source, payment model, legality, and compliance — without redundancy. It earns high marks for not padding, though it could be restructured to separate the core 'what it does' from the legal and billing context, which 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 tool with 10 parameters, key security implications, and a pay-per-query model, the description captures the most critical operational context (cost, LGPD compliance, source legitimacy). However, it omits important details like how authentication is chosen between the two credential types, what the output format looks like, and how the credit deduction works in practice. It's complete for the 'why' but incomplete for the 'how' of a complex, high-stakes 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 coverage is 0%, so the description carried the full burden to explain the 10 parameters — none of which are described in the schema itself. The description adds the payment/credits model, which is helpful for parameter semantics context, and mentions credentials are not the platform's. However, critical questions remain unanswered: which parameters are for credential type (email/senha vs pkcs12), what 'tipo_certidao' values qualify, or how to interpret 'uf' and 'municipio' formats. Given zero schema coverage and a high-stakes payment requirement, this is 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 clearly identifies the verb+resource: consulting certificates (certidão) from Registradores/ARISP. It adds meaningful context about the data source (official Brazilian sources) and nature of the query. However, some ambiguity exists between 'Novo Pedido' (new request) and 'consulta' (query), and it doesn't explicitly differentiate from the sibling tools, though context implies distinction from generic tools 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?

The description implies usage context: this is for querying official Brazilian registry data with a pay-per-query model and LGPD responsibilities, which suggests when this would be appropriate. However, it doesn't explicitly state when to use this tool versus alternatives or what the alternatives are in contrast. The LGPD data-controller framing implies a compliance use case but never explicitly states 'use this when you need certificate data from ARISP registrars.'

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 non-read-only, idempotent, and non-destructive behavior. The description adds that conversation data is needed for reproduction, but does not disclose side effects such as ticket creation or external submission. 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, front-loaded with purpose and a concrete usage instruction. Every word earns its place with no 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 3-parameter tool with annotations, the description is adequate but has gaps: it omits semantics for the required message and context parameters and does not mention what happens after reporting. It is not as complete as it could be, but it is not misleading.

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 'conversation' parameter as an array of recent messages, but leaves the required 'message' parameter and optional 'context' parameter undefined. It also calls conversation an 'array' while the schema types it as a string, adding slight 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?

The description uses a specific verb ('Report') and clearly names the resource types: bug, missing feature, or feedback. This distinguishes it from unrelated siblings 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?

It states when to use the tool (bug, missing feature, feedback) and gives a concrete instruction to include the conversation array for reproduction. It does not mention exclusions or alternatives, but no sibling tool competes for this purpose.

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 behavior, and the description ('Show') aligns perfectly. No additional behavioral disclosure needed.

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 tool's purpose without any extraneous content.

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 no output schema, the description sufficiently covers what the tool does. No caveats or additional context are needed.

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 there is nothing to describe. The baseline score of 4 applies, as the description does not need to explain non-existent 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 the tool's function with a specific verb ('Show') and resource ('MCP platform and adapter versions'), distinguishing it 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?

The description implies when to use the tool (when version information is needed) but does not explicitly mention alternatives or exclusions. It is clear enough for a straightforward info-retrieval tool.

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 it's a safe read operation. The description adds value by specifying what the read includes (installed MCPs, connection status, accounts, catalog tool counts) and how many catalog tools each exposes. The openWorldHint=false is consistent with a deterministic state read. No contradiction, and the description enriches the annotation context.

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 that is direct and information-dense, listing all the key elements of the toolkit state without filler. It front-loads the core verb ('Returns') and the resource ('current toolkit state') and enumerates the specific components. Perfectly 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 low complexity (no parameters, no output schema), the description is sufficiently complete. It covers the key information the agent might need: what state is returned formatted as a list of components. It doesn't describe pagination or format, but for a zero-parameter info tool, this is adequate. The annotations provide safety context, so the description covers the functional purpose well.

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, and the schema is empty. The description does not need to explain parameters, and per the rubric, a baseline of 4 is appropriate when there are no parameters. The description implicitly confirms that the tool takes no input by describing it as a state snapshot.

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 the current toolkit state' and enumerates the specific information it provides (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like connect or show_version, which have different responsibilities.

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 an informational tool used to inspect toolkit state before taking actions like connecting or using tools. It does not explicitly state when not to use it or name alternatives, but the clear scope (returning state) adequately indicates its use case. Sibling tools like connect are clearly action-oriented, making the context sufficient.

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