Prefeitura SP Osasco: Certidão de Tributos de Empresa

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

The description adds behavioral context beyond annotations: it explains the permanent config option (non-expiring header) and session-only login when a token is passed, and that calling with no args returns a link. This goes beyond the boolean hints (idempotent, not destructive). It does not mention side effects, but annotations cover safety, and it adds meaningful nuance.

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 appropriately sized given the complexity, with a clear structure: context, steps, options. It is front-loaded with the main purpose and then details. It could be slightly more streamlined (e.g., 'MCP.AI for IDE agents' is a bit vague), but 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?

The description covers the main purpose and usage well, but it doesn't specify the return value or response format for any of the call variants (e.g., what happens after passing a valid token, or even the link format). Since there is no output schema, this is a gap; the agent may not know what to expect from the tool's response. Otherwise, the context is sufficient for the low complexity.

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 fully explains the `token` parameter: it's a JWT string to be pasted for session-only login, and the tool can be called with no args to get a link. This gives the agent complete understanding of how to use the 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's purpose: authenticating IDE agents by logging in and obtaining an access token. It distinguishes itself from sibling tools by explicitly focusing on authentication (browser login, token handling) and offering two modes (permanent config vs session-only). The verb 'log in' and resource 'MCP.AI' are specific.

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: for IDE agents needing authentication, with a recommended permanent setup via config header and an alternative session-only path. It explains how to call the tool: with a token or no args. However, it doesn't explicitly state when not to use it or mention alternative sibling tools (like 'connect') as choices, 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds useful context about the two states (all connected vs. missing credentials) and what URLs are returned, which goes beyond the annotations. However, it does not detail the exact structure of the response or any potential side effects (though none are expected).

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 provides the key behavioral details without any fluff. 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?

Given the tool has no parameters, no output schema, and simple annotations, the description is quite complete. It explains the two possible states and what URLs are returned. It could mention the format of the URLs or the exact response structure, but for a status-check tool, this is sufficient.

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 description coverage is 100% (vacuously). The description does not need to explain parameters, and it appropriately focuses on the output behavior. Since there are no parameters, a baseline of 4 is appropriate.

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, and distinguishes it from siblings like authenticate and toolkit_info by focusing on status/URLs rather than actions or general info. It could be more specific about the exact resource (e.g., 'connection status' is a bit generic), but it is clear enough.

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 when to use it (to check connection status and get URLs when credentials are missing), but it does not explicitly state when not to use it or mention alternatives like authenticate for initiating connections. It provides context but lacks explicit exclusions or alternative 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?

The description adds rich behavioral context beyond annotations: invoke runs tools even when the MCP is not installed, returns connect or checkout links for auth/payment, and does not bloat the tool list. It also discloses that install/uninstall/subscribe/cancel require owner/admin and that published prompt links open without login. No contradiction with annotations exists.

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 dense and front-loaded with the core marketplace purpose, then covers workflows, permissioning, and the prompt library. It is a long single paragraph, but nearly every sentence earns its place given the tool's breadth; light formatting or separation would improve scannability.

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, multi-action tool with no output schema and sparse annotations, the description is quite complete: it explains the main lifecycle, one-off vs permanent execution, auth/payment flow, admin requirements, and prompt library. Missing details are mostly return-value shapes for search/list/describe and precise semantics for several billing and prompt parameters.

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 across 23 parameters, the description must compensate substantially. It explains core parameters like action, mcp_id, tool_id, query, and arguments through the workflow narrative, but many prompt_* fields, billing flags, and request/report parameters remain unexplained. It adds meaningful semantics but not enough to fully cover the schema gap.

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 establishes marketplace as mcp.ai's in-platform catalog and execution layer for MCPs/tools, with an explicit core search→describe→invoke flow. It is broad and multi-action rather than a single verb+resource, and it does not distinguish itself from the sibling report_bug tool (which shares the same name as one of its actions), so it falls just short of a 5.

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 guidance: use invoke for occasional one-off runs, use install only when an MCP should be permanent, and prefer invoke over install when the tool is not installed. It also states when connect/checkout links appear and when workspace owner/admin is required, making when-to-use very clear.

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 agent knows this is a safe read operation. The description adds valuable context: it's a paid consultation (prepaid credits), it accesses official Brazilian sources (not confidential data), and it clarifies LGPD responsibilities. This goes beyond the annotations by explaining the commercial and legal aspects, which is useful for the agent to set expectations.

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 with three sentences, each carrying distinct information: what the tool does, how it's hosted and paid, and legal context. It's concise and front-loaded with the core purpose. No fluff, but it could be slightly more structured (e.g., bullet points) for readability, though it's acceptable.

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 complexity (5 required parameters, no output schema, no parameter descriptions), the description is incomplete. It doesn't explain what the response will look like, what the parameters mean, or any prerequisites (e.g., does the user need to have the municipal registration number?). The annotations cover safety, but the description lacks operational details. For a paid consultation tool, the agent would benefit from knowing the expected output format or any error conditions.

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%, meaning the description provides no parameter-level details. The schema lists 5 required parameters (inscricao_municipal, finalidade, cpf_solicitante, telefone_solicitante, email_solicitante) but the description doesn't explain their meaning or format. For example, 'inscricao_municipal' is likely the municipal registration number, but the description doesn't clarify. With 0% coverage, the description must compensate, but it doesn't. This is a significant gap.

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: to consult a municipal tax certificate (Certidão de Tributos de Empresa) from the Osasco city government, using an official source. It specifies the resource (certificate) and the action (consult), and distinguishes it from generic tools by naming the specific municipality and certificate type. However, it doesn't explicitly contrast with sibling tools, but the siblings are mostly unrelated (authenticate, marketplace, etc.), so the purpose is clear enough.

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 some usage context: it mentions that the service is hosted by the platform, requires prepaid credits, and that the client is the data controller under LGPD. It implies when to use (when needing this specific certificate) but doesn't explicitly state when not to use or mention alternatives. The guidance is more about operational and legal context than about choosing between tools, but it's adequate for a niche tool.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the behavioral detail that the conversation array is needed for reproduction, which is useful context. However, it does not disclose what happens after reporting (e.g., whether it sends to a remote service, stores locally, or returns a reference). This is acceptable given the simple nature, but more transparency about the post-action effect would improve it.

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, starts with the primary purpose, and avoids any fluff. The instruction about the conversation array is directly relevant and earns its place. No unnecessary details are included.

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 reporting tool with no output schema and modest parameters, the description covers the core purpose and a key usage requirement. It could be improved by explaining what the agent should expect after calling (e.g., a confirmation or that the report is queued), but overall it is adequate for this tool's complexity. Annotations provide the safety profile, so the description does not need to restate that.

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 does clarify the 'conversation' parameter by instructing to include it for reproduction, but it does not mention 'message' (the required one) or 'context'. Since 'message' is self-evident from the tool name, some credit is given. However, 'context' remains unexplained. The description adds some value but does not fully cover all parameters.

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 uses a specific verb ('report') and resource ('bug, missing feature, feedback'), and is distinct from sibling tools like authenticate, connect, or show_version, which have no overlap. It is immediately clear what this 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 provides a direct usage hint: 'Include the conversation array with recent messages for reproduction.' This tells the agent what to supply for effective use. While it does not explicitly mention when not to use (e.g., alternatives), the sibling tools are unrelated, so no exclusion is needed. The context is clear, though it could be more explicit about when this tool is the right choice.

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, covering safety. The description adds that it shows both platform and adapter versions, giving a slightly richer picture of the tool's output scope. No 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?

The description is a single concise sentence that immediately states the tool's purpose. There is zero redundancy or filler; every word adds informational 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 parameterless informational tool with no output schema, the description is fully adequate. It tells the agent exactly what this tool returns (platform and adapter versions) and nothing else is needed to use it correctly.

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 per the rubric the baseline is 4. The description correctly notes it shows versions without needing parameter elaboration; schema coverage is 100% by virtue of having no params.

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 from sibling tools like authenticate or connect, which are unrelated actions.

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 conveys the general use case (retrieving version information) but does not explicitly state when to use this tool over alternatives like toolkit_info, which may overlap. No exclusion criteria or context about typical invocation scenarios is 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 disclose readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context about the returned information (installed MCPs, statuses, accounts, tool counts), which goes beyond the annotations and helps the agent understand what to expect.

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-formed sentence that lists the key output categories without any filler. It is front-loaded with the core purpose and immediately provides concrete details, 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?

The tool is simple with no parameters and no output schema. The description fully covers what the tool returns, and given the absence of parameters or complex behavior, it is complete. No additional details are necessary for an agent to understand or invoke it correctly.

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 coverage is 100% (no properties). Per guidelines, a baseline of 4 is appropriate for a parameterless tool. The description does not need to explain parameters, and it correctly focuses on the output.

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, specifying exactly what it includes (installed MCPs, connection status, accounts, catalog tool counts). It distinguishes itself from siblings like authenticate, connect, and marketplace, which focus on other actions.

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 explains what the tool does but does not provide explicit guidance on when to use it versus alternatives. For a simple read-only info tool, this is a minor gap; the purpose is clear enough that an agent would likely infer usage, but no when/when-not guidance is given.

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