JUCESP: NIRE a partir de Sócio

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

The description explains that calling with a token establishes session-only authentication, calling without args returns a login link, and config-based auth is permanent and non-expiring. This adds meaningful context beyond the annotations, though it does not detail side effects like token invalidation or existing session replacement.

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 compact and front-loaded with the core purpose, but it packs multiple alternatives into a long first sentence with colons and semicolons. Still, every sentence contributes necessary information, so it remains reasonably 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 simple single-optional-parameter schema and lack of output schema, the description is complete: it covers both call modes, explains the distinction between permanent and session-only auth, and indicates what happens with no arguments. No important context is missing.

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?

Although the schema provides no description for `token` and coverage is 0%, the tool description fully compensates: it specifies the token is a JWT, should be passed as `token: "<jwt>"`, and that omitting it triggers the login-link flow. This is complete parameter semantics.

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 handles MCP.AI authentication for IDE agents, covering browser login, token capture, and configuring a permanent or session-only connection. It goes beyond a simple restatement of the tool name and explains the full purpose.

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 usage guidance: add the token as an Authorization header for a permanent connection, or call the tool with a token for session-only login, or call it with no args to get a login link. This clearly tells the agent when and how to invoke each mode.

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. The description adds value beyond these by specifying the exact response shape in each state: 'authenticated:true' with 'empty pending[]' when connected, and 'connect_url' for toolkit/per-install URLs when credentials are missing. It could have mentioned the partially-connected/impending state explicitly, but the conditional detail is genuinely informative and consistent 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 sentences, front-loaded with the core purpose and packed with specific behavior. No filler words. Every clause serves a purpose, describing both the happy path and the missing-credentials path efficiently. Excellent conciseness.

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 status-checking tool with no parameters and no output schema, the description covers the two primary states (all connected and missing credentials). The mention of 'pending[]' hints at a third partial state that is never explicitly described, which is a minor gap. Overall, it is complete enough for an agent to understand both invocation and response semantics.

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 in the input schema, and the schema covers 100% of params by default. Per the rubric, a 0-parameter tool starts at a baseline of 4. The description appropriately skips parameter details since none exist. Nothing more 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?

Uses a specific verb+resource: 'Returns connection status and URLs.' The description clarifies it's a status-checking endpoint despite the name 'connect,' distinguishing it from siblings like 'authenticate' (which likely initiates a flow). The behavior under two conditions (all connected vs. missing credentials) precisely scopes the tool's purpose.

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?

Clear usage context: the agent can infer this is the go-to tool when it needs to check whether providers are connected or obtain connection URLs. However, there is no explicit statement of when NOT to use it or which sibling to use instead (e.g., 'use authenticate to establish credentials'). The conditional flow descriptions provide actionable 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 establish readOnlyHint=true and destructiveHint=false; the description adds useful context about prepaid credits, official sources, non-confidential data, and LGPD responsibility. However, the claim 'sem credenciais' conflicts with the presence of credential parameters (login_cpf, login_senha, pkcs12_cert, pkcs12_pass), creating ambiguity about the actual authentication requirements.

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 concise operational context. It is one short paragraph with no filler, though the LGPD sentence is somewhat boilerplate and could be trimmed without losing essential tool usage 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?

Despite the clear purpose statement, this tool has 8 parameters, no required fields, and no output schema. The description does not explain the return format beyond 'NIRE', and it fails to document most parameters, particularly authentication-related ones, making it insufficient for an agent to reliably invoke the tool with the correct inputs.

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 meaning. It clarifies socio_nome, socio_cpf, and socio_cnpj, but leaves login_cpf, login_senha, pkcs12_cert, pkcs12_pass, and inclui_inativas unexplained, with the 'sem credenciais' statement further muddying the credential fields.

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: 'Encontra empresas na JUCESP a partir de um sócio (nome, CPF ou CNPJ), retornando o NIRE de cada participação.' It clearly states what the tool does and the output (NIRE), and it is distinct from the unrelated 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?

The description provides clear context about when this tool is appropriate: it is a hosted, credential-free, pay-per-query lookup of official Brazilian data. It does not explicitly name alternative tools or when-not-to-use scenarios, but no sibling appears to be a similar data lookup, so the context is sufficient.

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 goes well beyond the sparse annotations: it discloses that invoke runs tools even without installation, that writes require workspace owner/admin, that paid tools may return a top-up link, and that search/describe flag installation state. No contradiction with the annotations exists.

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 dense but logically structured: primary purpose, core flow, key one-off invoke behavior, install-vs-invoke distinction, and the prompt library section. It is longer than ideal and includes a stray Portuguese example, but the length is largely justified given the tool has 14 actions and 23 parameters.

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 and the absence of an output schema, this description covers almost everything an agent needs: action semantics, return behaviors, authentication/credential links, payment top-up flow, permission requirements, and the distinction between one-off and permanent installation. It also explains the prompt library sub-system clearly enough for correct tool selection and invocation.

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 compensates by explaining the central action=search/describe/invoke flow, the role of tool_id and mcp_id, and prompt-related fields like prompt_body, prompt_vars, and prompt_slug. However, several parameters such as immediate, tier_slug, conversation, request_name, cancel_reason, and prompt_targets are only inferable from their names and are not explicitly documented.

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 the mcp.ai marketplace catalog and execution layer, and immediately enumerates its two main purposes: discovering/running MCPs and hosting the prompt library. It differentiates itself from sibling tools by describing its core flow (search → describe → invoke) and covering capability requests such as "find an MCP that does X."

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 usage guidance: prefer invoke for one-off use, use install only for permanent toolkit membership, use list_tools to see what is immediately callable, and use request_mcp when nothing fits. It also explains when invoke will return connect or checkout links and tells the agent to retry after the user completes the flow.

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 include idempotentHint=true compact with the description's implication of submitting a report, which is not a destructive or read-only operation. The description adds context about reproduction data, which is useful. It does not fully detail side effects, but annotations cover the main behavioral hints, so this is adequate beyond the annotation baseline.

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 only two sentences, front-loads the core purpose, and adds the one important detail (conversation array) without unnecessary fluff. 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?

The tool is relatively simple, but with 3 parameters and no output schema, the description does not fully explain all parameters or return values. It provides the essential usage context but lacks detail on what happens after reporting (e.g., response format). This is a moderate gap, so a 3 is appropriate.

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. However, the description only mentions the conversation array, while the schema has three parameters. It does not explain 'context' or the format of 'conversation' (which is a string but likely JSON). This is a minimal addition beyond the schema, earning a 3.

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 reports bugs, missing features, or feedback, with specific mention of including a conversation array. It is distinguishable from siblings like authenticate and marketplace, which have different purposes.

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 context on when to use the tool (when encountering a bug, missing feature, or wanting to send feedback) and what to include (conversation array). It does not explicitly mention when not to use it or list alternatives, but the purpose is specific enough to guide 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, so the description doesn't need to repeat safety. It adds the scope (platform and adapter versions) which is useful context beyond the annotations. No contradictions found.

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 captures the tool's purpose with no wasted 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 simple version display tool with no parameters and rich annotations, the description is complete. It tells exactly what versions are shown (MCP platform and adapter), which is sufficient.

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, so the description need not explain any. Baseline for 0 params is 4, and the description adds no parameter info because there are none.

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 exact function: showing the current MCP platform and adapter versions. It uses a specific verb and resource, and it's distinct from siblings like authenticate or report_bug.

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 clearly implies when to use it (when version information is needed) and is obviously distinct from siblings that handle authentication, connectivity, marketplace, etc. It does not explicitly mention alternatives, but given it's a standalone version check, the context is clear enough.

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, idempotent, and non-destructive behavior. The description adds context about what the response includes, which helps set expectations for the return value. It does not mention any side effects or limitations, but given the strong annotation coverage, this is a minor gap.

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 leads with the primary action and then lists the specific state components. Every word adds useful information, with no redundancy or 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?

With no output schema, the description must convey what the tool returns, and it does so comprehensively by listing all key elements of the toolkit state. This is complete enough for a simple introspection tool with no parameters.

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, so the description is not required to explain parameters. Per the rubric, 0 params receives a baseline of 4, and no further compensation 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 explicitly states the tool's purpose with a specific verb ('Returns') and resource ('current toolkit state'), and enumerates the exact contents (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes it from sibling tools like show_version 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?

Usage context is implied: the description tells you what the tool returns, but it does not explicitly say when to choose this over alternatives or mention any prerequisites. There is no direct guidance on when to use toolkit_info versus show_version or other info-related tools.

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