OAB Cadastro de Advogados

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

Annotations already declare idempotent and non-destructive, but the description adds valuable behavioral detail: the permanent config route vs session-only token, and that calling with no args returns a link. It does not contradict annotations and clarifies side effects (session vs permanent) beyond what annotations convey.

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 at three sentences, each carrying a distinct purpose: the flow, the permanent config option, and the session option. It uses inline code formatting for clarity without waste.

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 one-parameter auth tool, it covers all main usage modes, the token type, and the no-arg behavior. It doesn't mention error handling or exact response format, but the return link is implied. Given no output schema and a simple tool, this is adequately 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 schema has only a bare token string with 0% description coverage. The description fully compensates by explaining that token is an access token/JWT, used in a call like { token: "<jwt>" } after the user pastes, and that no args yields the login link. This is complete for the single optional parameter.

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 MCP.AI for IDE agents (Cursor, etc.) with an explicit process: log in in the browser, copy the access token, and either configure it permanently or paste it for a session. The verb 'log in' and the specific resource 'MCP.AI' distinguish it from sibling 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 gives strong usage context: 'Best: add it to this server's config as a header... for a permanent, non-expiring connection' vs 'Or paste it here for a session-only login'. It also explains when to call with no args vs with a token. However, it does not explicitly mention alternatives among sibling tools, so it's not a full 5.

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, idempotentHint, and destructiveHint. The description adds conditional output details (authenticated:true, pending[], connect_url) that help the agent anticipate response states without contradicting 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 main purpose, and no filler. Every sentence provides meaningful behavioral 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?

For a no-parameter, read-only status tool with strong annotations, the description covers key conditional outcomes (all providers connected vs missing credentials) and specifies return fields. No output schema exists, so the description carries the load adequately.

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?

Tool has zero parameters, so schema coverage is trivially 100%. Baseline of 4 applies; description correctly omits 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?

Description uses specific verb 'Returns' and identifies the resource as 'connection status and URLs'. It distinguishes from siblings by framing itself as a status check, not an action like '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?

Description implies this is for checking connection status, but does not explicitly state when to prefer it over sibling tools like 'authenticate' or mention exclusions. The conditional behavior gives context but no explicit when-to-use 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?

Discloses critical behaviors beyond annotations: invoke works even when the MCP is not installed, returns connect/checkout links when needed, install writes require workspace owner/admin, and prompt library links open without login. This adds rich context that annotations do not 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 long but justified given the tool's multi-action complexity. It is logically organized from core flow to key behavior to prompt library, with minimal redundancy. Slightly dense as a single paragraph, but each sentence contributes value.

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 no output schema and sparse annotations, the description covers the main workflows, auth requirements, billing behaviors, and prompt library. It does not describe return formats for all actions (e.g., subscribe, resume) but is reasonably complete for a tool of this breadth.

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 explains the meaning of action values and central parameters (query, mcp_id, tool_id, prompt_vars), but with 23 parameters and 0% schema coverage, many parameters like immediate, tier_slug, conversation, prompt_targets, and request_details are not explicitly defined. The description provides enough for the core flow but leaves significant gaps for edge-case actions.

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 defines the tool as the official marketplace catalog and execution platform, with a specific core flow (search → describe → invoke). It distinguishes itself from sibling tools by covering MCP discovery, installation, billing, and prompt library operations.

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: prefer invoke for one-off usage, use install only for permanent toolkit inclusion, list_tools lists callable tools, and search/describe handle discovery. It also clarifies billing/auth flows and when to use report_bug or request_mcp.

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. The description goes beyond by disclosing important behavioral traits: 'sem credenciais' (no auth), 'pague por consulta com crédito pré-pago' (cost per query), and 'ACESSO PÚBLICO' (data sensitivity). It also notes legal responsibilities under LGPD, which is valuable context for the agent.

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, front-loaded paragraph with three sentences. Each sentence adds value (purpose, cost/auth, data classification). It includes some legal boilerplate that could be trimmed, but overall it is efficient and not repetitive.

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 lookup tool with no output schema, the description covers the main contextual aspects: purpose, hosting, payment, authentication, data sensitivity, and compliance. The main gap is the missing explanation of the 'completo' parameter and any return format, but given the tool's simplicity, the description is nearly 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?

Schema description coverage is 0%, so the description must compensate. It explains the purpose of 'Nome' and 'IE' via 'por nome e inscrição', but leave 'completo' completely unexplained. This is a partial coverage: two of three parameters are semantically described, but the third remains ambiguous.

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: 'Consulta o cadastro nacional de advogados na OAB por nome e inscrição'—a specific verb, resource, and scope. It distinguishes itself from sibling tools, which are about authentication, marketplace, etc., by being a public registry lookup.

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 the tool ('Consulta o cadastro nacional de advogados'), along with operational details like no credentials needed, prepaid credit required, and public data access. It does not explicitly name alternatives or exclusions, but among the sibling tools there are no equivalent competitors, making the usage context 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the context that the conversation array is used 'for reproduction,' which offers some insight into behavior, but it does not disclose side effects, rate limits, or expected outcomes. 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?

The description is a compact two-sentence statement that immediately conveys purpose and a key usage instruction. There is no fluff or repetition of schema data.

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 three string parameters and no output schema, the description covers the core purpose and one important usage detail. However, it omits parameter semantics for message/context and does not hint at what response the agent might receive. This leaves some gaps, but the tool is simple enough that the description is minimally 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 only explains the 'conversation' parameter ('Include the conversation array with recent messages'), but does not describe the required 'message' parameter or the optional 'context' parameter. This leaves the agent without meaningful 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 states 'Report a bug, missing feature, or send feedback' with a specific verb and resource. This clearly distinguishes it from sibling tools 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?

Provides clear context for when to use the tool (bug reports/feedback) and includes a specific instruction to include the conversation array for reproduction. However, it does not explicitly mention when not to use it or name 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. The description adds no additional behavioral context beyond what the annotations convey, but the tool is simple and no extra disclosure is necessary.

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 conveys the full purpose without any redundancy or unnecessary 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?

For a simple version-check tool with no parameters and strong annotations, the description covers its purpose sufficiently. It does not detail return format, but no output schema exists and the expected output is obvious from the description.

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 0 parameters, so there is nothing to explain. Schema description coverage is 100% (trivially), and the baseline for parameter-less tools is 4.

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 clearly identifies the resource: 'current MCP platform and adapter versions.' This distinguishes it from sibling tools like authenticate, connect, and marketplace, which serve entirely 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?

The description implies usage (when you need to check platform/adapter versions) but does not explicitly contrast with sibling tools. Since the siblings are functionally unrelated, clear usage context is present, but no explicit when-to-use or alternative guidance is given.

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. The description adds value by disclosing what the tool returns (the toolkit state in terms of MCPs, connections, accounts, and tool counts), which gives the agent a clearer picture of the behavioral output. 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?

The description is a single, well-structured sentence that front-loads the primary action and then enumerates the key data points. Every phrase contributes meaning without redundancy or verbosity.

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 read-only tool with no input parameters and no output schema, the description adequately covers the return value at a high level. It could be slightly more explicit about the response structure or format, but it effectively communicates the essential information an agent needs to understand the tool's function.

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 no parameter semantics to explain. Baseline for no-parameter tools is 4, and the description appropriately omits any parameter discussion since none exist.

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 a specific action ('Returns the current toolkit state') and lists the exact contents: installed MCPs, connection status, accounts, and catalog tool counts. This distinguishes it from sibling tools like 'connect' or 'authenticate' which perform actions rather than report state.

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: to retrieve toolkit status. However, it does not explicitly state when to use this over other information-gathering tools (e.g., 'show_version') or provide any exclusion criteria. No alternatives are named, leaving usage inference up to the agent.

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