Prefeitura SP Campinas: CPOM

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

Annotations already mark the operation as idempotent and non-destructive; the description adds useful behavior context by explaining that config-based authentication is permanent/non-expiring while pasting a token is session-only, and that no arguments returns a login link. 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 compact: two information-dense sentences with clear 'Best' and 'Or' structuring. Every clause adds value, though the flow is slightly telegraphic and mixes config-level instructions with tool-call semantics in one block.

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 auth tool with no output schema, the description covers the key behaviors: how to authenticate permanently, how to do session-only auth, and what happens when called with no args. It does not mention error cases or post-authentication state, but these are less critical here.

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 coverage is 0%, but the description compensates well for the single optional 'token' parameter by stating it accepts a JWT pasted by the user and that omitting it returns the login link. More details about JWT format or response behavior would help, but the core semantics are clearly conveyed.

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 an authentication/login flow for MCP.AI and IDE agents, with specific actions: log in, copy token, and either configure a header or pass a token. The two distinct usage modes (permanent config vs session-only paste) add scope and make the purpose unmistakable.

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 advises the preferred permanent approach (config header) and the session-only alternative via token paste or no-args link retrieval. It does not explicitly contrast with sibling tools like 'connect', but it gives clear when-to-use guidance for this tool's own workflows.

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 valuable behavioral details, such as the conditional return when all providers are connected versus when credentials are missing, which goes beyond the 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 two concise sentences, front-loading the primary purpose and then providing conditional details. Every word earns its place with no 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 simple status-check tool with no output schema, the description sufficiently explains the return values and conditional logic. It covers the key scenarios without needing more detail.

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 of 4 is appropriate since no parameter documentation 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 what it does: returns connection status and URLs. It specifies the exact return values (authenticated, pending, connect_url) and conditions, making it unambiguous and distinct from siblings by its focus on connection status.

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 it is used to check connection status but does not explicitly contrast with siblings like authenticate or toolkit_info. It lacks guidance on when to use this versus alternatives, though the purpose is clear enough to infer.

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?

Beyond the sparse annotations (readOnly false, openWorld true), the description discloses that invoke can succeed without installation, returns connect or checkout links for auth/billing, and that writes require owner/admin. This adds significant hidden behavior without contradicting any annotation.

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 paragraph, but every sentence adds value without fluff. It's efficiently front-loaded with the primary purpose, then flows logically through the core flow, exceptions, and auxiliary features. Length is justified given the tool's multi-action nature.

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 covers the main workflow, differences between one-off and permanent usage, auth/billing behavior, permission requirements, and even mentions output artifacts like connect links and shareable prompt URLs. However, it lacks explicit details on error handling, rate limits, or the exact return format of each action, which would enhance completeness given the absence of an output schema.

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 fails to compensate by explaining parameter meanings. Although it names actions like `action=search` and mentions `tool_id`, it never details the semantics of `query`, `arguments`, `conversation`, `prompt_vars`, etc., leaving users to infer from property names alone.

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 official mcp.ai marketplace, enumerating its core capabilities across cataloging, discovery, execution, and billing. It distinguishes itself from siblings by explicitly naming its comprehensive scope, from search to prompt library, and states the primary flow of search/describe/invoke.

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 explicit usage guidance, contrasting `invoke` for one-off runs against `install` for permanent toolkit inclusion, and names alternatives like `report_bug` and `request_mcp`. It also flags permission requirements for write operations, giving clear when-to and when-not-to scenarios.

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 behavioral details beyond annotations: payment per query, no platform credentials, data is not confidential, and the client is the data controller under LGPD. These align with the readOnlyHint and idempotentHint annotations and provide valuable context for invocation and compliance.

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 purpose, flowing logically through operational details. It covers essential aspects without redundancy, though the LGPD statement could be seen as extraneous but is relevant for legal context.

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 has a simple single-parameter input and lacks an output schema. The description explains the source, payment, and legal aspects but does not specify the structure or content of the response. For a straightforward query tool, this may be sufficient, but it leaves some ambiguity about expected results without an output schema.

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 defines a single 'cnpj' parameter with no description. The description does not elaborate on the parameter format or requirements, but the tool name and context make it clear that the query is based on CNPJ. Given the simplicity of a single well-known parameter, the lack of added semantic detail is acceptable.

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 queries official data from Campinas city hall's CPOM system, specifying the source and that it is a consultation. It distinguishes from generic sibling tools by its specific purpose, though it does not detail what information CPOM contains or returns.

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 context that this is a paid, read-only query to official Brazilian sources and notes no platform credentials are needed. It does not explicitly state when to use this tool vs alternatives, but sibling tools are generic platform functions, so differentiation is implicit rather than 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 declare idempotentHint=true and destructiveHint=false, indicating a safe, idempotent operation. The description adds that it expects a conversation array for reproduction, which is useful behavioral context. No contradiction. However, it doesn't disclose what happens after submission (e.g., acknowledgment, no side effects), though annotations cover safety.

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, concise and front-loaded. The first sentence states the purpose, the second adds a key usage detail. No 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?

Given the tool's simplicity and lack of output schema, the description covers the basic purpose but omits critical parameter details. With 3 params and zero schema coverage, the description should explain each parameter's meaning at least briefly. It also doesn't mention whether any authentication is required, though siblings include authenticate. Overall, it's minimally adequate but with notable gaps.

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 3 parameters with 0% description coverage. The description only mentions 'conversation array' among the three, leaving 'message' and 'context' undocumented. It doesn't clarify the format of 'conversation' (string containing JSON array) or the purpose of 'context'. With 0% coverage, the description must compensate but only partially does.

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.' It names the action (report) and the target (bug, missing feature, feedback), which is specific enough. It doesn't explicitly differentiate from siblings, but siblings are unrelated (authenticate, show_version, etc.), so 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?

It implies when to use it (when you identify a bug or missing feature or want to give feedback), but doesn't explicitly state when not to use it or alternatives. Given the sibling tools are unrelated, this is acceptable but could be stronger with a direct 'Use when...' statement.

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 the tool as read-only, idempotent, and non-destructive, covering the main safety concerns. The description adds the exact scope (platform and adapter versions) but doesn't disclose output format or whether connection/authentication is required, which could be valuable context for an 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?

This is minimal and efficient: a single sentence that precisely describes the output. No fluff, no repetition of the tool name, and all words add 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 no-parameter read-only tool with clear annotations, the description is adequate. It could be more explicit about the exact version strings returned or potential error cases, but given the low complexity and full schema coverage, no significant gaps remain.

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 description needs to convey no input is required. The description implies this by simply stating 'Show the current...' without mentioning any arguments. Given the schema already has no properties, the baseline for zero-param tools is 4, and this description satisfies it.

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 MCP platform and adapter versions. This verb+resource mapping is specific and distinguishes it from siblings like toolkit_info, which likely provides broader tool information.

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 a common use case: checking environment versions for debugging or compatibility. Though it doesn't explicitly exclude alternatives, no other sibling tool appears focused solely on version info, so the purpose context is sufficient. It could be improved by noting when to use this instead of toolkit_info.

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 aligns with the annotations (read-only, idempotent, non-destructive) and transparently indicates that it returns a snapshot of the current state. It does not mention error behavior or edge cases, but for a simple read-only query, this is adequate.

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 efficiently enumerates the return contents. It is concise and to the point, with no unnecessary verbiage.

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 (no input schema, no output schema), the description is complete. It tells the user exactly what information is returned, which is sufficient for understanding the tool's purpose and usage.

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 properties, so there are no parameters to describe. The description fully covers the tool's behavior without needing parameter details. Schema coverage is trivially 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 clearly states the tool's purpose: it returns the current toolkit state, listing specific aspects (installed MCPs, connection status, accounts, catalog tool counts). This is a precise, verb-driven description that distinguishes it from siblings like 'connect' or '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?

The description does not explicitly state when to use this tool versus alternatives. While it is implicitly a read-only status query tool, there is no guidance on when to prefer it (e.g., before connecting) or when not to use it. This is a common gap.

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