Base de Conhecimento

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

The annotations already mark the tool as idempotent and non-destructive; the description adds context about the two authentication modes (permanent via config header vs session-only via token) and the link-generation behavior. It does not disclose server-side effects like session invalidation or error responses, but with annotation coverage, the added context 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?

The description is compact: three sentences that front-load the purpose, then present the two authentication options. 'Best:' and 'Or' structure the instructions clearly. It could be tightened (e.g., 'MCP.AI for IDE agents' is a bit tag-like), but every sentence contributes necessary information.

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 safe annotations, the description covers the essential usage paths: getting a link via no args and submitting a token for session login. It explains the permanent config alternative and the browser login flow. Minor gaps include return-value details and error handling, but these do not compromise the core understanding.

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 only defines an optional 'token' string with no description (0% coverage). The tool description compensates by explaining that the token is a JWT pasted by the user for session-only login and that calling with no arguments returns a link. This clarifies the parameter's role and optionality, though it doesn't specify validation or format details beyond 'jwt'.

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 authenticate as a tool for IDE agents to log in to MCP.AI, with specific instructions for obtaining and submitting an access token. It distinguishes from sibling tools like connect or kb_search by focusing solely on authentication. The phrase 'MCP.AI for IDE agents' plus the two usage paths make the tool's function specific and 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 explicitly contrasts a permanent config-based header approach ('Best: add it to this server's config as a header...') with a session-only token submission ('Or paste it here for a session-only login'), giving clear context on when to use each. It also specifies call patterns with or without the token argument, though it doesn't formally name alternative tools or exclusion criteria.

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 doesn't need to cover safety. It adds value by disclosing the output structure (authenticated, pending, connect_url) and the conditional behavior, which is not present in annotations. This exceeds the baseline for annotated tools.

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 primary action, and no redundancy. Every sentence adds meaningful information about the tool's behavior, achieving excellent 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 read-only status tool with no parameters and annotations covering safety, the description is sufficiently complete. It describes the two main output cases and mentions URLs, though it doesn't detail URL format or list specific providers—acceptable for this scope.

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 schema coverage is 100% (vacuously). Baseline for 0-param tools is 4; the description adds no parameter details because none exist. It correctly focuses on the output, which 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's function: 'Returns connection status and URLs.' It distinguishes itself from sibling tools like authenticate by being a read-only status check, and specifies the two possible output states, making the purpose 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 implies usage when checking connectivity but does not explicitly state when to use this tool versus alternatives like authenticate. It describes output conditions (all providers connected vs. missing credentials) but does not frame them as direct usage guidance or mention avoiding this for other actions.

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 non-read-only mutation, and the description adds transparency about the behavioral outcome: the pasted text becomes an indexed and searchable document. It does not detail duplicate handling, auth requirements, or account scoping, but it meaningfully supplements the structured metadata.

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-loaded with the core action and effect, followed by relevant use cases. Every sentence earns its place with no filler 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 simple add-text tool, the description covers purpose and appropriate use cases, but it omits parameter semantics (especially account and title) and provides no information about return values or behavior on duplicate submissions. With no output schema and 0% schema coverage, this leaves meaningful 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%, so the description must compensate, but it only hints at the 'text' parameter via 'texto colado'. The 'title' and 'account' parameters are completely unexplained, and the required nature of title/text is not mentioned, leaving significant ambiguity for invocation.

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 action ('Adiciona um texto colado à base') and the result ('vira um documento indexado e buscável'), making the tool's purpose obvious. It implicitly differentiates from kb_ingest_url by focusing on pasted text, but it does not explicitly name or contrast 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 phrase 'Útil pra notas, trechos, anotações' explicitly identifies common use cases, which helps an agent decide when to use this tool. It does not mention when not to use it or name alternatives like kb_ingest_url, but it provides clear contextual 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, providing a safety baseline. The description adds that it returns only metadata and status, not raw text, and discloses bulk support, adding useful behavioral context 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?

Two concise sentences, front-loaded with the core purpose. No filler or redundancy; 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 tool with no output schema and sparse parameter documentation, the description is too brief. It lacks details on error handling, authentication requirements, response format, and the precise usage of parameters, making it incomplete for an agent to invoke with confidence.

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 must compensate but only mentions 'document_ids' for bulk support. There is no clarification on the relationship between document_id and document_ids, nor any explanation of the account parameter, leaving key parameter semantics ambiguous.

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 states it returns metadata and status for a specific document, clearly distinguishing it from list- or search-oriented siblings. The phrase 'sem o texto cru' adds precision, and the mention of bulk support broadens scope without 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?

The description clearly implies usage for a single document or a batch of specific document IDs, but does not explicitly mention when not to use this tool or name alternatives. The context is clear enough to infer appropriate use.

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 the tool is a read/write mutation (readOnlyHint: false, destructiveHint: false). The description adds useful behavior details like supported extensions and download-and-index flow, but it omits important caveats such as duplicate handling, authentication, or failure 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?

The description is two concise sentences with no filler. It front-loads the action and keeps everything relevant, making it 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 mutating tool with no output schema and no parameter details, the description is too sparse. It does not explain return values, behavior when re-ingesting the same URL, how account affects ingestion, or what happens on unsupported file types.

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 gives some context for the 'url' parameter by specifying accepted file formats, but 'account' and 'filename' are left completely unexplained, leaving two of three parameters ambiguous.

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 and resource: it downloads a URL file (.md/.txt/.docx) and indexes it into the knowledge base. This clearly distinguishes it from sibling tools like kb_add_text, which ingests text directly.

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 says this is good for ingesting a remote document without manual upload, which gives clear usage context. However, it does not explicitly name alternatives or state when not to use the 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:true, idempotentHint:true, destructiveHint:false, so the description does not need to repeat that. It adds value by describing the returned fields (id, label, is_default) and the special meaning of is_default (when only one base), which is behavioral context beyond the annotations. A small gap: it doesn't mention whether pagination or sorting applies, but for a list likely trivial. Score 4.

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: first states the core functionality, second adds crucial context about the is_default flag and account parameter usage across other tools. Every sentence adds value, no redundancy, front-loaded with the primary purpose. Perfectly structured 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?

The tool has no parameters and no output schema, so the description carries full burden. It covers what is returned (id, label, is_default), the meaning of is_default, and the implications for sibling tools. For a simple list tool with no input, this is complete. The presence of sibling context (kb_* tools) makes the cross-reference to 'account' useful.

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?

There are zero parameters and schema coverage is 100% (no params), so description has nothing to add. Baseline for 0 params is 4, and the description does mention that other tools accept an optional `account` parameter (related to this tool), but that's about other tools. For this tool itself, no parameter semantics needed. Score 4.

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 verb-object: 'Lista as bases de conhecimento conectadas' (lists connected knowledge bases). It explicitly states returns id, label, and is_default flag, and it distinguishes from siblings (kb_list_documents, kb_search, etc.) by focusing on the account/list of knowledge bases.

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?

Explicitly explains when to use: to discover if there is a single account (no need to pass 'account' in other tools) or multiple (then pass an optional 'account' id/label). This guides the agent on when to call this tool and how the result affects usage of other kb_* tools, providing clear when-to-use context.

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 readOnlyHint=true and destructiveHint=false, so the description's safety bar is lower. It adds the specific output fields, but does not disclose any potential limits (e.g., pagination, sorting) or behavior when the optional account parameter is omitted. This is acceptable but not enriched.

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, compact sentence that communicates the purpose and output fields without any fluff. It is front-loaded with the primary verb and object, making it immediately scannable.

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 list tool with one optional parameter and no output schema, the description covers the returned fields but omits the meaning of the 'account' parameter, any pagination/limits, or ordering. It is minimally complete but lacks parameter context.

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 parameter 'account' with 0% description coverage little to no info in the description. The description mentions only the fields returned mud, not what 'account' does. This is a major gap for the agent to understand how to use the tool correctly.

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 states a specific verb ('Lista' / lists) and resource (documentos da base), and enumerates the returned fields (id, nome, status, tamanho, nº de chunks). This clearly distinguishes it from sibling tools like kb_add_text or kb_get_document.

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?

Usage context is implied by the verb 'lists' — it's for listing all documents. However, it does not explicitly compare with alternatives like kb_get_document (fetch one) or kb_search (search), nor does it mention the optional 'account' parameter's role (e.g., filtering by account).

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 states the tool deletes original, chunks, and index, which is destructive, but the annotations declare destructiveHint: false. This directly contradicts the description's claim, so transparency collapses.

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 short sentences convey the action and input format without redundancy. Efficient and front-loaded.

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?

No output schema exists, so the description should explain return behavior or side effects. It mentions deletions but not response types, irreversibility, or error cases. Combined with the annotation contradiction, it's incomplete for a destructive operation.

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 description explains document_ids as a list of ids, but the account parameter is completely unspecified. With 0% schema coverage, the description should clarify both parameters but only partially addresses one.

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 action ('Remove...documentos da base') and the resource, and specifies what gets deleted (original, chunks, index). It distinguishes from sibling tools like kb_add_text and kb_get_document by focusing on removal.

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 use when documents need to be removed, but provides no explicit exclusions, prerequisites, or guidance on when to prefer this over alternatives (though no direct alternative exists). It is adequate but minimal.

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 useful context beyond those annotations by explaining that the tool returns chunks with source filename and score, and that it does not answer directly. This is clear and non-contradictory.

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: two focused sentences in Portuguese. It front-loads the tool's purpose and then states the key behavioral constraint. Every clause contributes meaning without redundant or unnecessary detail.

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 action, the expected form of results, and the required downstream behavior well enough for simple semantic search with no output schema. It could still be more complete by explaining how top_k/account affect the search and when to use kb_get_document, but the essential task is understandable.

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 needed to explain the meaning/behavior of query, top_k, and account. None of these parameters are described, no defaults or constraints are given, and no semantic value is added beyond the raw parameter names in the schema.

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 starts with 'Busca semântica na base de conhecimento', naming a specific verb and resource. It also distinguishes itself from sibling tools by describing its output format (source chunks, filename, score) and by explicitly saying it is retrieval-only.

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 clear guidance on when to use this tool: to obtain relevant KB chunks as context and synthesize the answer from them. It states 'Retrieval-only' as an explicit usage constraint, but it does not provide direct when-not-to-use guidance or contrast alternatives such as kb_get_document.

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 annotations already indicate readOnlyHint false, destructiveHint false, and openWorldHint true. The description adds that writes require owner/admin and that invoke works even without installation, which improves transparency. However, it does not explicitly clarify the side effects of each action, and the mention of uninstall/cancel conflicts with the destructiveHint false 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 extremely verbose, repetitive, and includes unnecessary multilingual fragments and stylistic noise. It could be condensed to a few sentences, yet it spans multiple lines with redundant explanations of the same flow, significantly hindering readability.

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 (14 actions, 23 parameters, output schema absent), the description is far from complete. It provides a high-level overview and some workflow context but omits details on many actions (e.g., resume, request_mcp) and does not describe expected inputs, outputs, or error handling, leaving significant 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?

With 23 parameters, none of which have descriptions in the input schema, the description fails to explain the meaning or usage of most parameters. It only tangentially mentions a few (action, mcp_id, tool_id, arguments) but leaves the rest unexplained, making it impossible to correctly construct a valid invocation.

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 states the tool is a marketplace for MCPs and outlines various actions (search, describe, install, etc.), but it is verbose and includes confusing bilingual phrases like 'consulta um CPF' and 'pontualmente'. It does not crisply distinguish itself from sibling tools beyond its unique functionality.

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 guidance on when to use 'invoke' vs 'install' (e.g., prefer invoke for one-off use, install for permanent), and mentions the core flow. However, it does not clearly explain when to use each of the many other actions like subscribe, cancel, resume, or report_bug, leaving usage ambiguous for less common operations.

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?

With annotations already indicating this is a non-read-only, non-destructive, idempotent operation, the description adds useful behavioral context by requiring the conversation array for reproduction and clarifying the scope of reports. It does not detail side effects, but the annotation profile covers the key safety aspects.

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 a clear, front-loaded purpose and one actionable instruction. Every phrase earns its place and there is no wasted wording.

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 tool's core purpose and the most important reproduction detail, making it minimally viable for an agent. However, it lacks guidance on the required message field and the context field, and does not mention what happens after a report is submitted.

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 0% description coverage, so the description must compensate. It only adds meaning for 'conversation' (by calling it an array of recent messages), while the required 'message' parameter and optional 'context' parameter are left completely to inference from their names with no format or usage guidance.

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 clear verb ('Report') with specific resource targets (bug, missing feature, feedback) and is easily distinguishable from the sibling tools, which are all auth, knowledge-base, or version operations. It leaves 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?

It explicitly states when to use the tool: report a bug, missing feature, or send feedback. It also provides a practical guideline to include the conversation array for reproduction. It does not name alternatives, but no comparable sibling tool exists, so this is 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context beyond stating it shows versions, which is fine for a simple read-only tool. It doesn't describe output format or any side effects, but annotations cover the essential traits.

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 zero waste. It is front-loaded with the key action and subject. Perfectly concise.

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 low complexity, no parameters, and clear annotations, the description is complete enough. It might benefit from specifying whether it returns a string or structured data, but since there is no output schema, the description is sufficient for an agent to invoke and interpret the result.

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 doesn't need to explain parameters. The schema is empty. The description adds value by specifying what version info is shown (MCP platform and adapter versions), which goes beyond the schema. For a no-parameter tool, baseline is 4 for completeness.

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 shows current MCP platform and adapter versions. It uses a specific verb 'show' and a specific resource 'current MCP platform and adapter versions', which distinguishes it from siblings like 'toolkit_info' 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 implies usage: when you need to know current versions. It doesn't explicitly state when not to use or alternatives, but context is clear given the tool's simplicity and zero parameters. The sibling list includes 'toolkit_info' which might also provide version info, but without more context, the description is adequate.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with these. The description adds useful context about what 'state' includes, but it does not disclose additional behavioral traits such as freshness, side effects, 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 a single, front-loaded sentence that efficiently enumerates all returned information without filler, repetition, or unnecessary detail.

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 info tool with rich annotations, the description is complete enough: it names all major output categories (installed MCPs, connection status, accounts, catalog tool counts), and no output schema exists to backfill this 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?

The tool accepts zero parameters, so no parameter documentation is needed. The baseline of 4 applies because there is no parameter burden for the description to carry.

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') while enumerating the exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like show_version 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 implies this tool is for inspecting toolkit state and connection status, but it does not explicitly say when to use it or how it relates to alternatives like connect or authenticate. No exclusions or when-not-to-use guidance is provided.

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