Secretaria de Inspeção do Trabalho: CAEPI

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

Adds meaningful context beyond annotations: explains that calling with no args returns a link, and that token usage is for session login. Annotations already declare idempotentHint=true, readOnlyHint=false, destructiveHint=false; description does not contradict these and adds clarity on how the authentication flow works, including the permanent vs session distinction.

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, each carrying essential information. The description is front-loaded with purpose, then presents the recommended best practice and an alternative. No wasted words; every clause adds value. Well-structured with 'Best:' and 'Or' guiding the agent.

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 one optional parameter, no output schema, and moderate complexity, the description covers purpose, usage modes, and parameter semantics. It implies the output (a link) and explains how to use both modes. It could be more explicit about success/failure responses but is adequate for an authentication 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?

While schema only defines 'token' as an optional string, description explains its semantic role: 'token: "<jwt>"' for session login, and that omitting it yields a link. This adds practical meaning beyond schema, even though schema coverage is 0% because description does not formally document each parameter but does in context.

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?

Clear purpose: authenticates IDE agents, specifically for browser login and token exchange. It's the only authentication tool among siblings, so differentiation is inherent. Verb+resource is specific: 'log in' and 'access token'.

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 two distinct usage modes: permanent config via header, and session-only via token or no-args to get link. Gives explicit call patterns. While it doesn't explicitly state 'use this when... vs alternatives', the context makes it obvious when authentication is needed, and no sibling serves this role.

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 read-only, idempotent, non-destructive. The description adds transparency by explaining the conditional outputs (authenticated true vs. connect_url). No contradictions, and it enhances understanding of behavior.

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 concise sentences with no redundant wording. All information is essential and directly relevant to the tool's purpose.

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 no output schema, the description sufficiently explains return values including authenticated flag, pending array, connect_url, and per-install URLs. Complete for a no-parameter 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?

No parameters exist, so baseline score of 4 applies. The description does not need to explain parameters, and it does not introduce any ambiguity.

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?

Clearly states that the tool returns connection status and URLs, distinguishing it from sibling tools like 'authenticate' which likely perform authentication actions. The description specifies the resource and action.

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?

Describes when it returns authenticated status vs. missing credentials, but does not explicitly contrast with alternatives like 'authenticate'. Implicitly clear for status checking, but could be more explicit about when to use this versus other siblings.

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 annotations, the description discloses key behavioral traits: invoke runs one-off without installing or bloating the toolkit, missing credentials produce a connect link, empty wallet produces a checkout/top-up link with a retry instruction, and writes require workspace owner/admin. This is substantive behavioral context with no contradiction against readOnlyHint=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 dense and front-loaded, opening with the core flow and the KEY invoke behavior. It contains almost no wasted wording, but the single long paragraph structure makes it harder to scan; bullets or section breaks would improve navigability for an agent.

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 complex 23-parameter, multi-action tool with no output schema, the description covers most major flows: search→describe→invoke, install vs invoke, permissions, billing/subscription, request_mcp, list_tools, and the prompt library. However, it omits the 'resume' action entirely and does not describe return shapes or several parameter semantics, leaving some 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?

Schema description coverage is 0% for 23 parameters, so the description carries a heavy burden. It explains the meaning of the central action enum and core params like mcp_id, tool_id, and prompt_vars implicitly, but many params (limit, immediate, tier_slug, cancel_reason, cancel_comment, prompt_targets, report_context, request_details, prompt_body, prompt_slug, etc.) remain unexplained.

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 that marketplace is the official mcp.ai catalog/execution layer, covering search, describe, invoke, install, billing, and prompt-library actions. It distinguishes itself from siblings like authenticate/connect/show_version by focusing on MCP discovery and execution rather than auth or system info.

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 on when to use invoke versus install ('prefer invoke for a single/occasional use'; 'use install only to make an MCP PERMANENT'), when list_tools applies, and when request_mcp is the right call. It does not explicitly address when to use sibling authenticate/connect instead of the marketplace's connect-link flow, which is 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 indicate this is a write operation (readOnlyHint=false) and idempotent. The description adds that the conversation should be included for reproduction, but doesn't disclose other behaviors like outcome or auth. With annotations covering safety profile, a 3 is appropriate.

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, directly states purpose and usage, 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?

Simple tool with good annotations; description covers what it does and how to use it. Missing details about outcome but acceptable given 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?

Schema has 0% property descriptions, so description must compensate. It explains conversation (include recent messages) but leaves message and context implicit. Partial coverage.

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 reports a bug, missing feature, or feedback, with a specific verb and resource. It distinguishes itself from siblings (auth, version, etc.) by its explicit purpose.

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 (when reporting issues) and instructs to include conversation for reproduction. However, it doesn't explicitly state when not to use or mention alternatives, though siblings are clearly unrelated, so context is 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, non-mutating operation. The description adds no extra behavioral context beyond that, but it doesn't contradict the annotations. With annotations covering the safety profile, a 3 is appropriate.

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 sentence with no wasted words. It is front-loaded with the action and resource. Perfectly concise for a simple 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?

Given the tool's simplicity (no parameters, no output schema, clear purpose), the description is complete. It doesn't need to explain return values because there is no output schema, but the purpose is clear. The annotations provide safety context, so the description 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?

The tool has zero parameters, and the schema description coverage is 100% (vacuously). The description doesn't need to explain parameters since there are none. The baseline for 0 params is 4, and the description is sufficient.

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: showing current MCP platform and adapter versions. It uses a specific verb ('show') and resource ('versions'), and while it doesn't explicitly distinguish from siblings, the sibling tools have different purposes (authentication, connection, marketplace, etc.), so 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 usage: when you need to know the current versions. It doesn't explicitly state when not to use it or mention alternatives, but given the simplicity and the sibling tools' distinct purposes, the context is clear. No exclusions are needed.

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 cover read-only and idempotent. The description adds valuable context: payment model (prepaid consultation), no platform credentials needed, data is non-confidential, and client is LGPD data controller. Contradicts no annotation. It doesn't cover error handling or rate limits, but what's added is meaningful.

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?

Description is ~4 sentences, covering purpose, hosting, payment, and legal responsibility. It's somewhat verbose but relevant. The key purpose is stated first, but the legal and payment details could be shortened. Not overly long, but not tight.

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 low complexity (1 param, no output schema), the description fails to explain the required 'ca' parameter, the format of data returned, or any usage constraints like rate limits. With low schema coverage (0%), the description needed to fill that gap and didn't.

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 1 required parameter 'ca' with zero description coveragecars. The tool description does not explain what 'ca' represents, its format, or expected values. Without that, the agent cannot correctly provide input.

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 indicates a consultation of CAEPI via official Brazilian sources, using the verb 'consultar' (consult) and a specific resource name. It distinguishes from siblings which are generic toolkit utilities, though it could be more explicit about what data is returned.

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?

No explicit guidance on when to use or not use this tool. The description provides context (official source, pay-per-use, not secret data) but does not mention alternatives or exclusions. Sibling tools are unrelated, so it's implied but not stated.

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 specific details about what the tool returns (installed MCPs, connection status, accounts, catalog tool counts), going 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?

Single sentence, clear and concise, front-loaded with the verb 'Returns'.

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, no-output-schema tool, the description fully covers what it returns and serves its purpose. No missing information.

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?

No parameters exist, so there are no semantic gaps. The description effectively explains the tool's output without needing 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 a specific verb ('Returns') and identifies the resource ('current toolkit state') with detailed components: installed MCPs, connection status, accounts, and catalog tools. This clearly distinguishes it from sibling tools that focus on actions like authentication, version, and bug reporting.

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 toolkit state but does not explicitly state when to use it or provide alternatives. Given the read-only nature and clear purpose, context is implied but no formal guidelines are given.

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