JUCESP: Busca de NIRE (pesquisa avançada)

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

Beyond the basic annotations (readOnlyHint false, idempotentHint true, destructiveHint false), the description adds meaningful behavioral context: permanent non-expiring connection vs session-only login, token format, and the no-args link behavior. It does not contradict annotations and provides the agent with a realistic model of the tool's effects.

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 core purpose and then moves efficiently through the two login methods. Every sentence adds actionable information with no padding or redundant restatement of the tool name.

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 single-parameter tool with no output schema, the description covers the necessary actions, token format, configuration alternative, and no-arg behavior. It is sufficiently complete for an agent to select and invoke the tool 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?

Schema description coverage is 0%, so the description carries full burden for the single token parameter. It explains exactly how to use it: call with { token: "<jwt>" } for session login, or omit it to get the link. This fully compensates for the schema lacking parameter descriptions.

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 that the tool authenticates an MCP.AI server for IDE agents, with a concrete workflow: logging in via browser, copying a token, and calling with optional token or no arguments to get a link. It identifies the specific resource (MCP.AI authentication) and the actionable verb (log in/get token), distinguishing it from generic 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 explicitly explains two usage modes: configuring the token permanently as an Authorization header, or pasting it for session-only login. It also specifies that calling with no arguments returns the login link. This gives the agent clear guidance on when and how to invoke the tool, including the 'Best' vs 'Or' choice.

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 idempotency, so the safety profile is clear. The description adds behavioral context beyond that by specifying conditional outputs ('When all providers are connected...' vs. 'When credentials are missing...'), which is useful for callers to handle responses.

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 minimally sized, only two sentences, and front-loads the primary purpose ('Returns connection status and URLs') before providing conditional details. Every word adds value, and there is 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 no-parameter, read-only status tool, the description covers all essential aspects: what it returns, the two main scenarios (authenticated vs. missing creds), and the meaning of fields like 'connect_url'. There is no output schema to compensate for, but the description fully specifies expected behavior.

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 zero parameters and 100% schema coverage (vacuously), the description fully explains the input side. There is no missing parameter information, and the description successfully communicates what would otherwise be unclear. A 4 is warranted because no additional parameter context is 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 uses a specific verb ('Returns') with a concrete resource ('connection status and URLs'), and explains behavior in both connected and missing-credential states. It distinguishes itself from siblings like 'authenticate' and 'marketplace' by indicating its purpose as a status check rather than an action.

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?

Even though it doesn't explicitly name alternatives, the description inherently clarifies when to call this tool (to inspect connection status/URLs) and implies when not to (when attempting to authenticate). The context around 'pending[]' and 'connect_url' gives enough usage clarity, though it could be more explicit about not being for authentication.

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 annotations (read-only, idempotent, non-destructive), the description discloses meaningful behavioral traits: platform hosting, no credentials, prepaid per-query billing, official Brazilian data sources, non-confidential data, and LGPD data-controller responsibility. This significantly helps an agent set expectations and assess side effects.

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 core purpose, then adds operational, legal, and cost context in three compact sentences. Every sentence earns its place; 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?

Despite the good purpose and behavioral context, the tool is complex: 15 optional parameters, no output schema, and no parameter documentation. The description only says it returns 'o NIRE' and does not cover query construction, expected response shape, pagination, or edge cases. This leaves the agent under-informed for a tool of this complexity.

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 for the 15 undocumented parameters. It mentions categories like 'razão social, objeto, capital, endereço' but does not explain formats, allowed values, date-range syntax, boolean expectations, or how filters combine. It adds only general semantic hints, not sufficient parameter guidance.

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: 'Pesquisa avançada de empresas na JUCESP por razão social, objeto, capital, endereço e outros filtros, retornando o NIRE.' It clearly states what the tool does and the unique outcome (NIRE), and none of the sibling tools overlap with this search 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 clear context for when to use this tool—advanced company searches by multiple filters—and adds operational constraints such as 'sem credenciais' and 'pague por consulta com crédito pré-pago.' It does not explicitly name alternatives or when-not conditions, but the sibling tools are unrelated, so no exclusion is necessary.

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?

Goes well beyond annotations by disclosing that writes require workspace owner/admin, that invoke runs one-off without installing or bloating the tool list, and that credential/payment gaps result in returned links for the user to complete. It also explains installed_in_toolkit vs installed_in_workspace flags, adding 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 long but structured and front-loaded with the core flow; each sentence adds meaningful operational guidance. It is not as tight as a two-sentence description, but the complexity of 14 actions justifies the length, and it avoids 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?

For a tool with 14 actions, 23 parameters, and no output schema, the description is remarkably complete. It covers all main flows, edge cases (connect/checkout links), permission requirements, and the prompt library, and even specifies return behaviors for describe and publish_prompt. Only minor details like the 'resume' action are omitted, but this does not undermine overall 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?

Schema description coverage is 0%, and the description compensates partially by explaining the action enum and core flow (e.g., search uses query, describe uses mcp_id, invoke uses tool_id and arguments, publish_prompt returns a link). However, many parameters like immediate, tier_slug, prompt_vars, cancel_reason, and report_context are not addressed, leaving gaps for a 23-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 as 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' with a specific verb-like role (search/describe/invoke). It distinguishes from siblings by laying out the core flow and naming related tools like list_tools and the prompt library, making its unique scope unmistakable.

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 guides when to use which action: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT', and covers when to use search, describe, list_tools, subscribe/cancel, request_mcp, and prompt actions. It also explains handling of connect/checkout links for credentials or payment, and notes permission requirements for writes.

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=false, destructiveHint=false, and idempotentHint=true, which covers safety and idempotency. The description adds that the conversation should be included for reproduction, which is useful for understanding the tool's purpose. It does not disclose any additional side effects or behaviors, so the description adds limited value beyond 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 extremely concise, consisting of two short sentences. It is front-loaded with the core purpose and immediately provides the key usage instruction. No fluff or unnecessary 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?

The tool is simple (a bug/feedback reporter) with no output schema alert. The description covers the primary purpose and mentions the conversation inclusion. However, it does not explain what happens after submission, nor does it fully disambiguate the three parameters. Given the lack of parameter explanations, the description is minimally complete but not thorough.

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 for parameter understanding. It only explains the 'conversation' parameter ('include the conversation array'), but does not clarify 'message' or 'context'. The 'message' parameter is required, yet its purpose is not explained. With only one of three parameters addressed, the description is insufficient.

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 purpose: 'Report a bug, missing feature, or send feedback.' It uses a specific verb ('report') and identifies the resource (bug/missing feature/feedback). It is distinct from sibling tools like authenticate, connect, and marketplace, none of which relate to bug reporting.

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 usage context: it's for reporting bugs, missing features, or feedback. It also instructs to include the conversation array for reproduction, which is useful preparation. However, it does not explicitly state when to use this tool over alternatives or when not to use it, though the sibling tools are clearly unrelated.

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, non-destructive behavior; the description adds no additional context about side effects, permissions, or rate limits. It is consistent but does not augment transparency beyond what annotations provide.

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, clear sentence with no extraneous words. It is fully front-loaded with the action and subject.

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, unambiguous purpose), the description is sufficient. It conveys the exact function without needing to explain return values or edge cases.

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 no parameters, so there is nothing to describe. The schema is empty, and the description correctly omits any parameter details.

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 the current MCP platform and adapter versions. The verb 'Show' is specific, and the resource (versions of platform and adapter) is 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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. For a trivial version check, this might be acceptable, but the rubric requires explicit usage context to score higher.

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 this as read-only, idempotent, and non-destructive. The description adds meaningful context about what information the tool exposes, which is beyond the annotation data and clarifies the actual behavioral output.

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 that is front-loaded and compact. Every phrase adds value, with 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, parameter-less info tool with clear annotations, the description fully covers what the tool returns and when it applies. No output schema exists, but the description supplies an itemized list of return content, making it 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?

The tool has zero parameters, and schema description coverage is 100%. No parameter documentation is needed, so the baseline score of 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 the current toolkit state, listing specific details (installed MCPs, connection status, connected accounts, catalog tool counts). It distinguishes from siblings like show_version by describing a broader resource 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?

The tool's purpose signals when to use it (whenever toolkit state is needed), but it does not explicitly mention alternatives or exclusions. Sibling tools like show_version or marketplace could overlap conceptually, and the description does not draw those boundaries.

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