Conselho Regional de Odontologia AM: Cadastro

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

Description explains side effects (permanent config modification vs session-only) and idempotent nature. Adds context beyond annotations by detailing the two modes, though it does not mention potential overwriting of existing config.

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 well-structured, presenting two clear authentication options without unnecessary jargon or redundancy. It is slightly detailed but remains focused and readable.

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 an authentication tool with no output schema, the description covers the purpose, usage, and side effects comprehensively. It explains both permanent and session-based scenarios, making it complete for the intended use.

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 only parameter 'token' is fully explained: it is an optional JWT for session-only login, and its absence triggers returning a link. The description compensates for the lack of schema property 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?

Description clearly states that this tool authenticates for MCP.AI for IDE agents, and explains the two authentication methods. It distinguishes from sibling tools like 'connect' and 'show_version' by focusing on authentication.

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 instructions: either add a permanent token to server config or pass a session token, and explains that calling with no args returns a link. Clarifies when to use each method.

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 and idempotentHint=true, so the description correctly mirrors that safety profile. It adds valuable state-dependent details: returns authenticated:true and empty pending[] when all connected, or connect_url and per-install URLs when credentials missing. This extends beyond annotations 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 two sentences, front-loaded with the main purpose, then explains two behavioral outcomes. No unnecessary words or repetition. It is a model of 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 simple zero-parameter read-only tool, the description fully covers the expected outcomes and responses. The absence of an output schema is acceptable because the description specifies the key fields (authenticated, pending, connect_url). The tool's behavior is fully described given the annotations and simplicity.

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 input schema has zero parameters, so schema description coverage is trivially 100%. The description provides no parameter info because there are none, matching the baseline for 0-param tools. No additional parameter description 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 states the tool's function: 'Returns connection status and URLs.' It also distinguishes two key scenarios (all providers connected vs missing credentials), which differentiates it from authentication or other setup tools. This is a specific verb+resource with clear 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 description provides behavioral conditions that help the agent decide when to use it (e.g., checking if all providers are connected, or identifying missing credentials). It does not explicitly name alternative tools like 'authenticate', but it implies this is for status queries. No explicit when-not guidance is given, but the context makes it 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 signal read-only, idempotent, non-destructive behavior. The description adds valuable context beyond those hints: no platform credentials required, prepaid credit per query, data is public/non-confidential, and LGPD controller responsibilities. This meaningfully expands the behavioral picture, though it omits operational details like response format or failure modes.

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 reasonably concise and front-loaded with the core purpose. It includes necessary caveats (payment, credentials, LGPD) that add value rather than fluff. The legal sentence could be trimmed for an AI-focused audience, but it is still appropriately sized for the tool's complexity.

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 one-parameter, read-only tool, the description covers purpose, data source, auth, payment, and data classification. However, it lacks parameter guidance and does not describe what the returned registration information includes. Since there is no output schema, some explanation of the expected result 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?

The schema has one required string parameter, `inscricao`, with 0% schema description coverage. The description does not mention `inscricao` at all, nor clarify what value should be supplied (e.g., registration number format or examples). Given the low schema coverage, the description should compensate, and it does not.

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 consults registration data from the official Regional Dentistry Council of Amazonas (CRO-AM). The verb 'consultar' and resource 'cadastro' are specific, and the domain distinguishes it from the generic sibling tools (authenticate, marketplace, etc.). It could be slightly more explicit, but the purpose 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 provides clear context: it queries official Brazilian public sources, the data is not confidential, and it is the same data available to citizens. It does not explicitly name when-not-to-use alternatives, but the sibling tools are unrelated, and the official-data framing offers adequate guidance. A brief exclusion note (e.g., 'not for private/sensitive data') would push it 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?

The description goes beyond the basic annotations by explaining key behaviors: 'invoke works even when the MCP is NOT installed' and 'runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list'. It also discloses that writes require workspace owner/admin permissions (critical for safety) and that invoke can return connect/checkout links needing user interaction. Annotations are minimal (readOnlyHint false, etc.), and the description adds significant behavioral context without contradiction.

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, long paragraph, not front-loaded with a succinct summary before diving into details. It packs a lot of information but could be better structured with bullet points or short sections for 'Core Flow', 'Key Behaviors', 'Permissions', and 'Prompt Library'. Its length is justifiable given the tool's complexity, but it lacks visual breaks for efficient scanning.

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 high complexity (23 parameters, 14 actions, multiple sub-flows for MCPs and prompts), the description is remarkably complete. It covers the core search-describe-invoke flow, install vs invoke distinction, permission requirements, prompt library functionality, and even edge cases like connect/checkout links. Without an output schema, it explains likely return behaviors. It stands out for its depth and practical orientation.

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 clearly explains the core parameters: 'action' (lists all enum values), 'query' for search, 'mcp_id', 'tool_id', 'arguments', and 'prompt_*' parameters for the prompt library. It also explains how parameters relate to the flow (e.g., describe requires mcp_id, invoke requires tool_id and arguments). However, some parameters like 'conversation', 'immediate', and 'tier_slug' are not described, but the description provides enough for the core flows.

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 as the official mcp.ai marketplace, covering both MCP discovery and execution, and explicitly enumerates the core actions (search, describe, invoke, etc.). It distinguishes itself from siblings by positioning itself as the central catalog and runner, while siblings like authenticate and connect handle auth flows.

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 extensive guidance on when to use each action: use 'search' for discovery, 'describe' for profiles, 'invoke' for one-off runs, 'install' for permanent additions, 'list_tools' to see current callable tools, and 'request_mcp' when nothing fits. However, it does not explicitly state when to use this tool versus siblings, nor does it contrast with alternatives like authenticate, though the marketplace context implies it is the primary hub.

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 idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds context that the action involves reporting, implying an external side effect (sending a report), but does not elaborate on consequences or authorization. It adds some value beyond annotations by mentioning reproduction details, but stops short of full transparency (e.g., no mention of data transmission or persistence).

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 long, front-loading the purpose and immediately providing actionable guidance. Every word earns its place, with no fluff or redundancy. It is a model of concise, useful documentation.

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 low complexity of the tool but the presence of three parameters, the description only covers one parameter (conversation) and leaves 'message' and 'context' unexplained. While the tool is simple, the lack of clarity on required fields is a significant gap. The absence of an output schema is mitigated by the likely void return, but the parameter under-specification makes this incomplete.

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 schema description coverage at 0%, the description is expected to clarify parameter meanings. It only mentions 'conversation array' and that it should contain recent messages, but does not explain 'message' (required) or 'context' at all. The description is insufficient for an agent to correctly populate the required fields without additional inference.

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: 'Report a bug, missing feature, or send feedback.' The verb 'report' is specific, and the resources (bug, missing feature, feedback) are enumerated. It also provides a key instruction about including the conversation array. It is easily distinguishable from sibling tools which are unrelated (e.g., authenticate, 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 guidance to 'Include the conversation array with recent messages for reproduction,' which tells the agent how to use the tool effectively. However, it does not mention when NOT to use the tool or name alternative tools. The guidance is clear but lacks exclusionary context, so it doesn't earn a 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the context of 'current' (implying live retrieval), but does not disclose any additional behavioral traits such as output specifics, error behavior, or network dependencies. With annotations doing the heavy lifting, this is adequate but not enhanced beyond the minimum.

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 sentence with no filler. Every word adds value: 'Show' indicates the action, 'current' specifies recency, and 'MCP platform and adapter versions' defines the output scope. No redundancy or 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 trivial, zero-parameter, read-only tool with comprehensive annotations, the description fully covers the essential information. It clearly communicates what the user can expect to obtain (versions). No output schema exists and the annotation handles side-effect disclosure, so the description is complete for its purpose.

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 trivially covered (100%). No parameter documentation is needed. According to the rubric, the baseline for zero params is 4, and the description does not introduce any unnecessary parameter-related content.

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: 'Show the current MCP platform and adapter versions.' It uses a specific verb ('Show') and identifies the resource (versions), making it distinct from siblings like 'toolkit_info' which might cover broader info. The purpose is unambiguous and directly actionable.

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 no guidance on when to use this tool versus alternatives, no contextual triggers, and no exclusions. For a simple version check, this might be acceptable, but the rubric requires explicit usage guidance for a score above 2. Sibling tools like 'toolkit_info' could overlap, yet no differentiation is offered.

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 meaningful behavioral scope by specifying exactly what information is reported—installed MCPs, connection status, accounts, and catalog tool counts—which is valuable because there is no output schema. 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 single, front-loaded sentence that states the action and resource immediately while each subsequent clause adds specific, non-redundant information. No filler or unnecessary qualification.

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 zero-parameter, read-only information tool, the description adequately enumerates the main return contents despite the lack of an output schema. It loses one point because it does not specify the exact return shape or structure (e.g., object vs array, nested layout), but it is still sufficient for correct 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?

The tool has zero parameters, so schema coverage is trivially 100% and there are no parameter semantics for the description to clarify. The base score for no-parameter tools is 4, and the description avoids adding irrelevant 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 uses the specific verb 'Returns' and names the resource 'current toolkit state', then enumerates concrete content areas: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly differentiates it from siblings like show_version or connect, which serve 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 for read-only inspection of the toolkit state, but it does not explicitly state when to use this tool versus alternatives such as show_version or connect. The context is clear enough for basic selection, but no when-not-to-use or alternative guidance is provided.

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