Conselho Regional de Odontologia SE: Cadastro

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

The description meaningfully extends the annotations by explaining behavior: idempotent login behavior (calling repeatedly with same token is fine), permanent vs session-only connection semantics, and conditional behavior based on args. It does not contradict the annotations (readOnlyHint: false, idempotentHint: true, destructiveHint: false).

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, informal paragraph that mixes configuration instructions with tool-call guidance. While it avoids filler and communicates all needed points, the rambling structure and informal asides ('Best:', 'Or paste it here') could be more tightly organized for machine consumption.

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 low-complexity tool (1 optional parameter, no output schema), the description covers both invocation modes, the difference between permanent and session-based login, and the pre-requisite of user interaction. Minor gaps remain on error cases (e.g., invalid/expired JWT) and response shape, but these are not critical.

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 provides only an unadorned 'token: string', and with 0% schema coverage, the description must compensate fully. It does so excellently by explaining exactly when to pass the token ('{ token: "<jwt>" }' after user pastes it) and when to omit it ('no args to get the link'), adding rich, actionable meaning.

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 specific verbs and resources ('log in in the browser, copy the access token', 'add it to this server's config') and conveys the tool's role as the authentication mechanism for MCP.AI IDE agents. It clearly separates this tool from siblings like 'connect' and 'report_bug' by focusing solely on the login/token flow.

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 contextual guidance on the two usage scenarios: permanent setup via config header versus session-only login via token argument. However, it doesn't explicitly mention when *not* to use this tool or name specific alternative tools for comparison.

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, so the bar is lower. The description adds behavioral context beyond annotations by specifying the returned fields (authenticated, pending, connect_url) and how they vary, which is valuable for understanding the 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?

The description is two sentences, front-loaded with the main purpose, and every word adds value. It is concise and well-structured without redundancy.

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 parameters and no output schema, the description fully explains the return behavior through the two scenarios. The annotations cover safety aspects, making this complete for a simple status 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 tool has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the schema coverage is 100% (vacuously). No additional parameter semantics are 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 returns connection status and URLs, with specific details about the two possible outcomes. This distinguishes it from siblings like authenticate, which likely handles authentication, and marketplace, which deals with marketplace 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?

The description provides clear context on when results differ based on connection state (all providers connected vs. missing credentials), giving the user a sense of when to use this tool. It does not explicitly name alternatives or exclusions, but the usage is well implied.

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 mark this as read-only and idempotent; the description adds key behavioral context: 'pague por consulta com crédito pré-pago' (pay per query with prepaid credit) highlights a non-obvious cost implication, and 'sem credenciais da plataforma' clarifies no authentication is needed. It also clarifies data sensitivity and legal responsibility, which goes beyond the annotation hints without contradicting them.

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 block of four sentences, each carrying some distinct information (domain, payment, data origin, legal). While not excessively long, the first sentence is grammatically stilted ('Cadastro, consulta em fonte oficial') and the flow could be improved by front-loading the tool's action and then adding context. It is compact but could be clearer in structure.

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 lookup with one parameter and no output schema, the description covers several important aspects: the data source is official, it is not confidential, there is a cost, and there are legal responsibilities. However, it leaves out what the response contains (e.g., whether it returns the registration record, errors, or pagination). Given the absence of an output schema, a brief note on return value would have made it more 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 a single required parameter `inscricao` with no description, and the tool description does not explain what this parameter represents beyond its self-evident name (registration number). Since schema coverage is 0%, the description needed to compensate with details on format or meaning, but it only vaguely refers to 'Cadastro'. This 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 identifies the domain (CRO-SE) and hints at a registration query ('Cadastro, consulta em fonte oficial'), but it never explicitly states that this tool returns the registration details for a given professional. The phrase is more of a label than a clear statement, lacking a direct verb like 'retrieves' or 'returns.' It distinguishes itself from the generic sibling tools only by domain, not by a clear functional description.

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 is implied through context: it queries official Brazilian public data from the regional dentistry council. The description notes the data is not confidential and that the client is the data controller under LGPD, which sets compliance expectations but gives no explicit guidance on when to select this tool over alternatives or mention of alternative tools. No exclusions or alternative tools are mentioned, falling short of a 4.

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 annotations by disclosing one-off execution behavior, credential and checkout link flows, workspace owner/admin requirements for writes, and prompt-link login behavior. It also explains the installed_in_toolkit vs installed_in_workspace distinction. 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 long but information-dense; every sentence contributes a distinct behavioral fact or routing rule. The core flow is front-loaded and the prompt-library section is cleanly separated at the end, making the structure easy to parse despite the breadth.

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 no output schema and 14 actions, this is unusually complete: it explains invoke's connect/checkout outcomes, get_prompt/publish_prompt return behavior, and search/describe installed flags. Minor gaps remain for the 'resume' action, list_tools result shape, and report_bug/request_mcp output expectations, preventing a perfect score.

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 embedding action semantics and key parameters like tool_id, mcp_id, prompt_body, and prompt_slug into the workflow explanation. However, many parameters remain unexplained, including limit, immediate, tier_slug, cancel_reason, prompt_targets, and conversation, leaving advanced usage under-specified.

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 marketplace as the catalog and execution hub for MCPs, with a concrete core flow (search → describe → invoke) and a secondary prompt-library feature. It distinguishes itself from sibling tools by naming its specific actions and 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?

It explicitly tells the agent when to use invoke versus install: prefer invoke for one-off use, install only to make an MCP permanent. It also maps each action to a use case, such as subscribe/cancel for billing, request_mcp for building new MCPs, and list_tools for currently callable tools.

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 readOnly=false, destructive=false, and idempotent=true. The description does not add further behavioral details beyond the instruction to include conversation for reproduction. It doesn't contradict annotations but also doesn't disclose additional side effects or outcomes, so it's neutral.

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 concise, consisting of two short sentences. It is well-structured, directly stating the purpose and then the key instruction. No unnecessary words or redundancy.

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 sufficiently covers the tool's purpose and a key usage detail (conversation array). It doesn't mention response or post-submission behavior, but given the simplicity and annotations, it is largely complete. It could be improved by briefly noting what happens after submission, but it's not critical.

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 explicitly mentions the 'conversation' parameter, explaining its purpose (recent messages for reproduction). However, it does not describe 'context' or 'message' beyond what is obvious from the name. Since only one of three parameters is clarified, and schema coverage is low, the description partially compensates but not fully.

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: reporting bugs, missing features, or sending feedback. It is specific with a verb and resource, and the mention of including the conversation array adds clarity. No ambiguity.

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 a general when-to-use (reporting issues/feedback) and instructs to include the conversation array, but it lacks explicit guidance on when not to use it or alternatives. It doesn't mention any exclusions or prefer other tools, so it's adequate 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?

Annotations already declare readOnlyHint and idempotentHint, so the tool's safety is clear. The description adds minimal extra context (e.g., 'current' suggests live state), but does not disclose potential network calls or other behaviors. This meets the baseline with annotations but adds little beyond them.

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 unnecessary words. It is perfectly sized for the tool's simplicity.

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 parameterless read-only version tool, the description is complete. No output schema exists, and the description sufficiently conveys what the tool does. No additional context is 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?

With zero parameters and 100% schema coverage, there is nothing for the description to clarify. The baseline of 4 is appropriate as the schema fully documents the empty parameter set, and the description does not need to compensate.

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: 'Show the current MCP platform and adapter versions.' It uses a specific verb and resource, and is distinct from siblings by focusing on version retrieval. No ambiguity.

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 (showing versions) but provides no explicit guidance on when to prefer this tool over alternatives. Since it's a simple, obvious tool, the lack of explicit context is acceptable but still a minor gap.

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 clear. The description adds value by detailing what the return includes (installed MCPs, status, accounts, catalog counts), which goes 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, information-dense sentence with no filler or redundancy. It front-loads the purpose and lists the key elements, making it efficient 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?

For a simple read-only tool with no parameters and no output schema, the description fully explains what the tool returns. It covers the important aspects of the response without unnecessary detail, making it complete for agent 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?

The tool has zero parameters, so there is nothing to describe. The baseline for no parameters is 4, and the description does not add any parameter-related information, which is acceptable since the schema is empty and fully covered.

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 and lists the specific components included (installed MCPs, connection status, accounts, catalog tool counts). The verb 'Returns' with the resource 'toolkit state' is specific and distinguishes it from sibling action-oriented tools like authenticate and 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 implies usage (when you need to know the current state) but does not explicitly mention when to use this tool versus alternatives or provide any exclusions. It lacks explicit guidance on when not to use it, though the context from siblings makes it implicit.

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