Prefeitura: CPOM

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

Annotations already indicate this is a mutating, non-destructive, idempotent operation. The description adds context about the two authentication modes (session-only vs permanent) and warns that using a token is session-only. However, it doesn't describe side effects like replacing existing sessions or token validation behavior, so it adds some but not all behavioral details.

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 paragraph but well organized: it states purpose, then the 'Best' permanent method, then the 'Or' session method. It is concise enough, though it could benefit from formatting (e.g., bullet points) for clarity. It is not overly long and every sentence adds 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?

For a simple tool with one optional parameter and no output schema, the description is sufficiently complete: it covers the two invocation modes and the token format. It doesn't explain the return value, but that's not critical for an authentication tool where the user provides the token. Given the low complexity, it is adequate.

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 coverage at 0%, the description fully compensates by explaining that the optional 'token' parameter is a JWT to be passed after user paste, and that omitting it returns a login link. It clearly clarifies the parameter's role and optionality beyond the raw schema definition.

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: authenticating an IDE agent to the MCP server. It specifies the exact process (log in, copy token, and either add to config or use this tool) and distinguishes it from a permanent config approach, making it distinct from siblings which are unrelated.

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 explains when to call with a token and when to call with no args, and contrasts with the permanent config method. It doesn't explicitly mention alternatives among sibling tools, but it gives clear context for how to use the tool. The principal scenario is well covered.

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, but the description adds critical behavior: it details the exact response fields (authenticated, pending[], connect_url, per-install URLs) under different conditions. This goes beyond the structured annotations, disclosing return semantics without contradictions.

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 verb and resource. Every clause adds value: the first sentence states the core function, the second explains two conditional outputs. No fluff 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?

For a read-only connection status tool with no parameters and no output schema, the description covers all essential contexts: the success state, the missing-credentials state, and the URLs returned. It anticipates the likely questions an agent would have (what does 'connected' mean? what if auth is missing?) within its scope. Nothing obvious 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?

The tool has zero parameters, and the input schema is empty, so schema coverage is trivially 100%. Per rubric, 0 params warrants a baseline score of 4. The description appropriately focuses on output behavior rather than parameter docs, which is fitting here.

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: 'Returns connection status and URLs.' It specifies the exact conditions and outputs, distinguishing it from siblings like 'authenticate' by focusing on status retrieval. The conditional behavior (authenticated:true vs connect_url) is unambiguous and tied to a specific resource.

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 checking connection status but does not explicitly mention alternatives or exclusions. It clearly outlines when to expect specific outputs (all providers connected vs missing credentials), providing clear context. However, it stops short of naming sibling tools or stating 'use this instead of X', which would be 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?

The description discloses side-effect boundaries beyond the annotations: writes require workspace owner/admin, invoke performs a one-off install behind the scenes, and it does not bloat the tool list. It also explains credential and payment edge cases ('invoke returns a connect link' or 'checkout/top-up link'). This complements the sparse 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 text is dense and most sentences carry functional information, but it is a single unbroken paragraph with no bullets or section headings. The prompt-library addendum reads as a second topic tacked onto the marketplace explanation. For a 14-action tool the length is justifiable, but the lack of structure makes it harder to scan.

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 23-parameter, no-output-schema dispatcher, the description is unusually complete: it covers the search→describe→invoke lifecycle, permanent vs one-off install, auth and billing fallbacks, workspace permissions, and a separate prompt library. It leaves a few gaps such as return shapes for search, the resume action, and exact use of conversation/immediate, but overall it gives enough guidance for an agent to select and invoke actions safely.

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 enum (search, describe, invoke, install, subscribe/cancel, list_tools, prompt actions) and tying tool_id/mcp_id to the describe→invoke flow. It also clarifies prompt_vars ('{{variables}} filled') and the connect/checkout link behavior. However, several parameters (limit, immediate, tier_slug, resume, message, conversation) remain unexplained, so coverage is strong but not complete.

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 clear mission ('official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them') and gives concrete capability examples. It names the core search→describe→invoke flow and lists all action categories, so an agent can identify this as the central discovery and execution dispatcher. It doesn't explicitly contrast with siblings like authenticate, connect, or toolkit_info, but it is specific enough within its own 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 gives explicit decision rules: 'Use install only to make an MCP PERMANENT' and 'prefer invoke for a single/occasional use.' It also distinguishes list_tools ('lists what is callable right now'), request_mcp ('asks us to build a NEW MCP when nothing fits'), and subscribe/cancel for billing. This is clear when-to-use guidance with named alternatives and concrete tradeoffs.

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 description adds meaningful behavioral context: payment per query, no platform credentials, non-confidential nature of the data, and LGPD controller responsibility. This goes beyond structured 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 concise with three sentences, front-loading the main purpose and then adding payment and data governance details. It is efficient with no filler, though the LGPD sentence is a bit heavy for a brief tool description.

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 query tool, the description covers purpose, cost, and legal context, but lacks details on output format, return values, or parameter constraints. Since there is no output schema, these gaps reduce 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 does not compensate by explaining parameter formats or constraints. Parameters like 'cnpj', 'uf', and 'municipio' are self-explanatory by name, but there is no guidance on formatting (e.g., CNPJ with/without punctuation) or accepted state/municipality representations.

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 performs a CPOM query in an official source, using specific parameters (cnpj, uf, municipio). It distinguishes itself as a Brazilian official data consultation tool, though it doesn't specify what CPOM data is returned or how it relates to 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 contextual constraints (hosted by platform, no platform credentials, prepaid credit required) but no explicit guidance on when to use this tool versus alternatives. There is no mention of scenarios that would make this tool inappropriate or exclusions.

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 adds value by advising to 'Include the conversation array with recent messages for reproduction,' which is a useful behavioral hint for the user. It does not contradict annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false). It could disclose more about side effects (e.g., where the report goes), but the annotation already covers safety, and the description contributes meaningful context beyond that.

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 primary purpose and a single, actionable hint. There is no redundancy or filler. Every word earns its place, making it highly concise and well-structured.

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 (3 simple parameters, no output schema, no nested objects), the description is mostly adequate. It captures the core purpose and the key hint about conversation, but it fails to explain the 'context' parameter and does not describe what the tool does after reporting (e.g., success/failure behavior). This incomplete parameter explanation reduces completeness, though the tool remains usable for an agent.

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 clarifies the 'conversation' parameter (by suggesting to include it for reproduction) and indirectly the 'message' parameter (as the content of the report). The 'context' parameter remains unexplained, and the default values are not described. This leaves a significant portion of the input schema unambiguated, so the description fails to fully fulfill the responsibility.

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.' This is a specific action with a clear resource (the subject of the report), and it distinguishes from sibling tools like authenticate or show_version which serve entirely different functions. The verb 'report' is explicit.

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 communicates when to use the tool ('Report a bug, missing feature, or send feedback') but does not explicitly mention alternatives or when not to use it. Since sibling tools are all unrelated, this is not a critical gap, but the lack of any exclusionary guidance prevents a perfect score. The context is clear and implied usage is accurate.

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 safety profile is known. The description adds no further behavioral context beyond the version-specific scope, such as expected output format or any 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 a single, front-loaded sentence with no filler or redundant content. Every word contributes value, making it highly concise 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 zero-parameter, read-only version query, the description is sufficiently complete. It states the exact subject and scope, and no output schema is present, but the description appropriately conveys what the user should expect.

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 an empty input schema, so parameter explanation is unnecessary. The baseline of 4 applies because there is no parameter gap for the description to fill.

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 identifies the exact resource ('current MCP platform and adapter versions'). It clearly distinguishes this tool from siblings like authenticate or report_bug, leaving no ambiguity about what the tool does.

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 is clear about the tool's function but does not explicitly state when to use it versus alternatives such as toolkit_info or report_bug. Usage context is implied rather than directly stated, and no exclusions are provided.

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 destructiveHint=false, and the description adds concrete details about what data is returned (MCPs, connection status, accounts, catalog tool counts). It doesn't add caveats like staleness or error conditions, but for a read-only state query the added context is sufficient.

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 front-loads the verb and resource, lists the specific outputs without extraneous words, and is perfectly sized for a zero-parameter read-only tool.

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 no output schema, the description fully enumerates what will be returned: installed MCPs, connection status, connected accounts, and catalog tool counts. For a simple state query with no inputs, this is complete and leaves no ambiguity about the tool's purpose or output.

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 rule gives a baseline of 4 for 0-param tools. The description doesn't need to explain parameters since there are none, and schema coverage is trivially 100%.

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 verb 'Returns' with a specific resource 'current toolkit state' and enumerates detailed contents (installed MCPs, connection status, accounts, tool counts). This clearly distinguishes it from action-oriented siblings like authenticate 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?

The description implicitly signals use as a state-inspection tool, and siblings are all action verbs, so context makes it clear when to call it. However, it doesn't explicitly mention alternative tools or exclusions, so it lacks an explicit when-not-to-use clause.

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