Bsoft TMS

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

Annotations indicate idempotent and non-destructive, and the description adds context about session vs. permanent login. However, it does not explicitly describe side effects like session creation or state changes, leaving some ambiguity about the exact 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 disjointed and includes extraneous phrases like 'MCP.AI for IDE agents (Cursor, etc.)' and awkward wording ('log in in the browser'). It could be streamlined to convey the same information more clearly and efficiently.

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 explains the basic flow (get link, paste token) but omits details such as the expected output of the tool, any prerequisites, or how authentication affects subsequent tool calls. Given no output schema, the description should have covered these aspects, but it remains incomplete.

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 sole parameter 'token' has no schema description, but the description explains that it is the access token from the browser (a JWT) and that it can be omitted to get a link. This adds meaning but is not exceptionally detailed, and the token format is only implied.

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 tool name 'authenticate' clearly indicates its purpose, and the description mentions 'log in' and 'get the link', which aligns with authentication. Although the description is somewhat cluttered, it effectively communicates the core function of authenticating a user.

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 usage instructions (call with token or with no args to get a link) and distinguishes between session-only and permanent authentication. However, it does not explicitly state when this tool should be used (e.g., before other API calls), relying more on 'how' rather than 'when'.

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 known. The description adds meaningful behavioral detail beyond annotations: pagination via offset/limit, JSON query filters, nested resource constraints with parent_id, and bulk execution via ids/parent_ids.

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 well-structured and mostly front-loaded, with the core usage in the first lines and a clean resource list. There is mild redundancy: resources are listed in prose and again in the 'Recursos' block, which costs a little conciseness without adding much 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 9 parameters, 12 resource enums, and no output schema, the description covers usage, pagination, nested resources, and bulk support well. It falls short of full completeness by not describing the return shape and by leaving the 'account' parameter unexplained.

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 carries the burden. It explains resource, id, limit, offset, query, parent_id, ids, and parent_ids usage. However, the 'account' parameter is not explained, and the structure of the 'query' JSON is only vaguely described as 'filtros em query JSON'.

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 this as a read-only tool for Bsoft TMS trip data: 'Controle de Viagens no Bsoft TMS (leitura)'. It explains the resource-based access pattern and distinguishes this read tool from the write siblings by using 'leitura' and describing list/get semantics.

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 concrete usage guidance: pass resource + optional id for a single record, omit id to list, use offset/limit for pagination, query for filters, and parent_id for nested resources. It does not explicitly name the write sibling tools as alternatives, but '(leitura)' plus the sibling naming convention makes the read vs write split 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 indicate readOnlyHint=false and destructiveHint=false, so the description correctly aligns with those. The description adds important behavioral context: it explicitly warns 'Altera dados de PRODUÇÃO (o Bsoft não tem homologação)', which is valuable. However, it doesn't disclose whether create is idempotent (despite idempotentHint=false in annotations, the description doesn't clarify) or what happens on error, but given annotations cover some traits, the description adds reasonable extra context.

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 and front-loaded with the primary purpose (write operations) and a critical warning about production data. The list of resources is compact and the flattened action note is brief. The bulk support sentence adds useful info without bloating. It's a single paragraph but well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters with 0% schema coverage and no output schema, the description provides some necessary guidance (resource list, required values, bulk support) but omits crucial details like the shape of `body`, the meaning of `account`, and the exact behavior of create (e.g., response format). For a write tool with no output schema, this is partially complete but leaves significant gaps for execution.

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 for parameter meanings. It mentions that `resource`, `action`, and `body` are needed, and that `id` is required for update/patch/deleteessing, plus `parent_id` for nested resources. However, it doesn't explain the `body` format or content, nor the distinction between `id` vs `ids` vs `parent_id` vs `parent_ids` beyond 'bulk support' at the end. This is minimal compensation for 7 undocumented 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 it handles write operations (create/update/remove) for Bsoft TMS travel control resources and lists the writable resources. However, the name already indicates 'create', and the description covers broader write actions, which is somewhat ambiguous for this specific tool. Still, it's clearer than a bare 'Process' and distinguishes the resource domain.

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 warns about altering production data and notes that update/patch/delete require id, nested resources require parent_id, and create_lote sends a list. However, it does not explicitly compare to alternatives like bsoft_controle_viagens_write_create_lote or explain when to choose this tool over the sibling create_lote. The boundary between 'create' and 'create_lote' is implied but not clearly 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?

The description warns '⚠️ Altera dados de PRODUÇÃO' and lists 'remove' as an action, indicating destructive capability. However, the annotation destructiveHint is false, directly contradicting the description's implication of destructive behavior. Per the rubric, any contradiction with annotations results in a score of 1, even though the description does transparently warn about production impact.

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 reasonably concise but includes a mix of general write info and specific create_lote details, making it somewhat cluttered. The warning and resource list are useful, but the inclusion of update/patch/delete requirements and the flattened action note add noise. It is front-loaded with the core write purpose, but not optimally structured for the create_lote 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?

For a tool with 7 parameters and no output schema, the description is incomplete. It fails to clarify the structure of the body parameter (expected JSON array?) and the role of ids/parent_ids in a create_lote context. The tool is part of a large family, yet the description doesn't fully explain how to use it effectively, leaving an agent with significant ambiguity (e.g., the non-existent action parameter).

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 coverage, the description must compensate, but it introduces an 'action' parameter that is not present in the input schema, which is misleading. It does explain that update/patch/delete require id and nested resources require parent_id, but these are irrelevant to create_lote. It only vaguely mentions 'Bulk support: accepts ids, parent_ids' without clarifying what these mean for a creation endpoint. The instruction to pass body (JSON) is useful but lacks detail on its structure.

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 this is for write operations (cria/atualiza/remove) and specifically highlights the create_lote action with 'create_lote envia lista no endpoint /lotes' and 'Bulk support'. This distinguishes it from sibling write tools like create, update, patch, delete. However, it starts with a generic write description that also covers update/patch/delete, which could dilute the focus on the create_lote variant.

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 over the singular create tool. It mentions 'Bulk support' but doesn't say 'use this when you have multiple items'. It also includes irrelevant guidance for update/patch/delete (requiring id) that doesn't apply to create_lote, which could mislead an agent. No explicit exclusions or alternative recommendations are provided.

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

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

Annotations show readOnlyHint=false and destructiveHint=false, but the description strongly warns that data is altered in PRODUCTION without a homologation environment, adding significant context. It also mentions bulk support with ids/parent_ids. Minor gap: does not explicitly state whether delete is permanent or if any confirmation/recovery is available, but the production warning covers the main risk.

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 front-loaded with a clear warning and usage instructions. It uses bullet-like formatting and bold for key points, packing essential information in a concise, structured way without 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?

Given no output schema and low schema coverage, the description covers the resources, required inputs, and data-safety context. It lacks details like response format or error behavior, but for a delete-focused tool with heavy annotations and sibling differentiation, it is reasonably complete for practical use.

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 mentions 'resource', 'action', 'body', 'id', 'parent_id', and bulk support, but does not explain the format or semantics of 'body', 'account', 'ids'/'parent_ids' beyond 'batched execution'. The description partially compensates but leaves some parameters unclear.

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 explicitly states the tool performs writes (create/update/remove) on 'Controle de Viagens' resources in Bsoft TMS, lists the exact writable resources, and the name includes the specific 'delete' action, distinguishing it from sibling write tools like _create, _update, and _patch.

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 clear instructions: pass resource, action, and body; specifies that update/patch/delete require id, nested resources require parent_id, and create_lote uses a list on /lotes. It also warns about production data and lists resources, effectively guiding when to use this delete-specific 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?

The description discloses critical behavioral traits: it alters PRODUCTION data (no homologation environment), which is a significant warning beyond annotations. It also notes bulk support for ids and parent_ids. Annotations only say readOnlyHint=false, destructiveHint=false, but the explicit drop to production is a critical behavioral transparency not covered by 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 reasonably concise, front-loading the purpose and critical warning, then listing resources and parameter requirements. The resource list is necessary but lengthy; the warning is prominent. Some redundancy with the action mention (patch) in the description and tool name, but overall efficient.

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 write tool with a complex resource set and no output schema, the description covers the main aspects: what resources, required parameters, production warning, bulk support. It lacks details on the response structure, but the description is sufficient for an agent to know how to invoke the tool correctly, especially given annotations and schema presence.

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%, but the description explains the purpose of key parameters: resource selects the writable resource, body is JSON, update/patch/delete require id, nested require parent_id, and create_lote uses /lotes. It adds semantic meaning beyond the schema for resource, id, parent_id, and body, but doesn't detail formats or example structures for body or account.

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 handles writes (create/update/remove) for Controle de Viagens resources in Bsoft TMS, listing writable resources and the required parameters. It is distinguished from siblings like bsoft_controle_viagens (which is likely read-only) and the other write_* tools by resource scope, though it notes the action varies (patch) with the command name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains when to use this tool: for write operations on the specified resources, with specific guidance on required parameters (resource, action, body) and conditions (update/patch/delete require id, nested resources require parent_id, create_lote sends a list). It doesn't explicitly compare against sibling write tools (e.g., write_create, write_update), but the resource list and action parameter provide clear usage 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?

The description discloses that it alters production data, which is valuable, but it also states the tool can 'remove' and references 'update/patch/delete', implying destructive behavior. This contradicts the annotation 'destructiveHint: false'. The description and annotations are at odds regarding whether the tool can delete/destroy data, creating serious ambiguity for the 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?

The description is a single paragraph but front-loaded with the production warning and key requirements. It concisely lists the writable resources. The extra note about 'create_lote' and the flattened action artifact could be trimmed, but overall it is fairly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 7 parameters and no output schema, so the description must carry more weight. It does provide meaningful context (production warning, id requirements, resource list), but it lacks information about expected return values, error handling, and how to structure the 'body' payload for specific resources. The mention of an 'action' parameter not in the schema further adds confusion.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds some useful semantics: it explains that 'id' is needed for updates, 'parent_id' for nested resources, and that 'ids'/'parent_ids' support batch execution. It also clarifies 'body' is JSON and lists valid resource values. However, it fails to explain the 'account' parameter and incorrectly mentions an 'action' parameter that is not in the schema, reducing its reliability.

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 a write operation for 'Controle de Viagens no Bsoft TMS', enumerates all writable resources, and differentiates itself via the 'write_update' naming and the flattened action 'update'. It states the primary purpose (create/update/remove) and lists specific resources, making it unambiguous from siblings like write_create or write_delete.

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: update/patch/delete require an 'id', nested resources require 'parent_id', and it mentions bulk support via ids/parent_ids. However, it does not explicitly advise when to choose this update tool over the patch tool (e.g., full vs partial updates) nor when to prefer the other write tools. The mention of delete may confuse, as this tool is specifically update.

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 tool's safety profile is covered. The description adds meaningful behavioral detail beyond annotations: GET vs POST semantics, output types (PDF/DACTE/DAMDFE/DANFE, access keys, XML), and filter placement (query vs body). It does not explain authentication, rate limits, or the account parameter, but with strong annotations this is minor.

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, immediately stating the resource and main use case. Every line earns its place by defining an action, a parameter, or a filtering rule without unnecessary filler.

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 5 parameters, 2 enums, and no output schema, the description is substantially complete: it covers actions, target document types, HTTP methods, filter placement, and date formatting. The main gap is the unexplained 'account' parameter, and it does not describe response structure, but the core usage is fully specified.

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, and it does for most parameters: it explains the meaning of each kind value, the valid tipo values, how query/body filters are used, and the Y-m-d date format. The only parameter left unexplained is 'account', which prevents a perfect score.

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 resource (Bsoft electronic fiscal documents / e-Doc) and enumerates the three specific actions (pdf, chaves, xml) with their HTTP verbs and outputs. It distinguishes this tool's main purpose from likely siblings like bsoft_documentos_fiscais_evento by stating it is 'o caso de uso principal'.

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 clear context for when to use each kind and how to combine it with tipo, including whether filters go in query or body and the expected date format. It does not explicitly state when not to use this tool or point to alternatives, but the usage guidance is practical and unambiguous.

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 signal mutation (readOnlyHint=false), and the description adds the important production warning '⚠️ Ação fiscal real em PRODUÇÃO', which conveys real-world impact beyond the schema/annotations. It does not detail all side effects, but this is a meaningful behavioral disclosure.

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 compact sentences front-load the action and risk, then give the key arguments. Every sentence earns its place; no filler.

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 what the tool does and the production risk, but with no output schema it does not describe return values, error behavior, or the account parameter. It defers body construction to external Bsoft docs, which is acceptable but leaves gaps for an agent invoking the 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?

Schema description coverage is 0%, so the description must compensate. It does explain that 'body' is a JSON string with event fields per Bsoft documentation and restates the tipo enum, but it leaves the optional 'account' parameter unexplained and does not detail body structure.

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+resource: 'Registrar EVENTO de documento fiscal no Bsoft (CT-e ou MDF-e)' and lists concrete event types (cancelamento, carta de correção, encerramento). This clearly distinguishes it from sibling tools like bsoft_documentos_fiscais or generic write_create tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for the event-registration use case and required arguments, but it does not explicitly state when to use this tool instead of alternatives or mention exclusions. Usage is implied by the event types listed rather than explicitly contrasted with sibling tools.

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 and idempotentHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: pagination via offset/limit, JSON filters in query, the requirement of parent_id for nested resources, and bulk support using ids/parent_ids. It stops short of describing output format or error semantics, but for a read tool 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 well-structured: a concise overview sentence, practical usage instructions, and a resource enumeration. The resource list is somewhat redundant with the schema enum, but the overall length is justified by the large number of supported resources and the need to convey the read-only nature. No filler or 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?

For a tool with 23 resources, 9 parameters, no output schema, and no per-resource details, the description covers the essential operational model: listing vs single fetch, pagination, filtering, nested parent requirements, and bulk execution. It does not explain each resource's meaning or return shape, but the resource names are largely self-explanatory and annotations cover safety. This is reasonably complete for a read-only data access 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?

Schema description coverage is 0%, so the description must compensate. It explains the core parameters (resource, id, offset/limit, query, parent_id, ids, parent_ids) and the single-vs-list behavior. However, the 'account' parameter is not mentioned at all, and 'query' is only lightly described as 'filters in JSON' without syntax details. The resource list duplicates the schema enum, adding little semantic value.

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 this is the financial read module of Bsoft TMS ('Financeiro no Bsoft TMS (leitura)') and enumerates the covered domains (títulos a pagar/receber, pagamentos, contas, contratos, etc.). It also differentiates from the write siblings by explicitly labeling itself as read-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?

It explains when to use the tool (for reading financial records) and provides the core pattern: pass resource plus optional id for a single record, or no id to list. It implicitly distinguishes from the write variants via '(leitura)', though it does not explicitly name alternatives like 'use bsoft_financeiro_write_* for mutations'.

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 prominently warns that it alters production data ('⚠️ Altera dados de PRODUÇÃO') and notes that there is no homologation environment. This adds important context beyond the annotations, which only indicate 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 structured with a warning, usage instructions, and a resource list. It is somewhat long due to the enumeration of resources but remains focused and readable without unnecessary verbosity.

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 does not mention what the tool returns on success or failure, nor does it clarify required fields for creating a record. Since there is no output schema, this is a significant gap in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains that 'resource' and 'body' are needed, lists the valid resource values, and mentions that nested resources require 'parent_id'. However, it does not explain other parameters like 'account', 'ids', or 'parent_ids', leaving some 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?

The description clearly indicates the tool is for financial write operations (create), lists the available resources, and explicitly states the action is 'create'. However, it also mentions update/delete in the opening line, which may slightly confuse the specific 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?

The description does not clearly differentiate this tool from sibling tools like bsoft_financeiro_write_create_lote (for bulk create) or the update/delete variants. It mentions create_lote and id requirements but does not explicitly state when to use this specific create tool versus alternatives.

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 warns '⚠️ Altera dados de PRODUÇÃO (o Bsoft não tem homologação)' which is critical behavioral context not in annotations (readOnlyHint=false already indicates write). It also clarifies bulk behavior and endpoint usage. No contradiction with annotations; the warning adds value beyond the false flags.

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 information-dense but well-structured: a warning, general write instructions, resource list, and bulk support note. Each sentence adds value, though it could be slightly tightened. The resource list is long but necessary. Front-loads the critical production warning.

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 (many resources, no output schema), the description covers the main aspects: operation type, required parameters, nesting, bulk behavior, and production impact. It does not detail per-resource payloads or return formats, but that's beyond scope for a generic write tool. The description is sufficient for an agent to select and invoke the tool for bulk creation.

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 explains resource, action, body, id/parent_id usage for update/delete, and ids/parent_ids for bulk. However, it does not explain the 'account' parameter or the structure of 'body' for different resources. Partial compensation, but significant gaps remain.

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 it's for financial operations in Bsoft TMS, specifically for 'create_lote' (bulk creation), and lists the writable resources. It distinguishes from other write tools by explicitly mentioning the bulk endpoint and the flattened action. However, the opening phrase 'cria/atualiza/remove' is a bit broad and could confuse with update/delete variants, though later context clarifies.

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: for bulk creation via 'create_lote' and mentions 'Bulk support: accepts ids, parent_ids for batched execution.' It also gives guidance on when to use id/parent_id, but doesn't explicitly contrast with the single-create or update/delete tools. The guidance is present but not strongly differentiated from 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?

Annotation Contradiction: annotations declare destructiveHint=false, but the description explicitly says the tool removes/deletes data and warns that it alters PRODUÇÃO data. Since the description contradicts the structured annotation, transparency fails even though it does mention deletion and production risk.

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 production warning is front-loaded and the resource list is useful, but the text is not delete-specific: it includes generic create/update/remove language, a create_lote endpoint note, and 'update/patch/delete exigem id' even though only delete is relevant here. Some sentences could be removed without losing necessary guidance.

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?

This is a complex write/delete tool with 18 resources, no output schema, and 7 parameters, but the description omits return values, account semantics, permanence/cascade behavior, and examples. It does cover production risk, resource options, and ID/bulk rules, but the destructiveHint contradiction further undermines completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description partially compensates by explaining that delete requires id, nested resources require parent_id, and bulk support uses ids/parent_ids. However, it mentions an 'action' property that is not in the schema, leaves 'account' unexplained, and only describes body as 'JSON' without further structure.

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 mentions 'remove' and '[Flattened action: delete]', so a delete operation is identifiable, but it opens with generic write-tool language ('cria/atualiza/remove') and includes create_lote guidance. This does not clearly distinguish the delete-specific tool from its write_create, write_update, or write_patch siblings.

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 provides useful operational rules: delete requires id, nested resources require parent_id, and bulk execution accepts ids/parent_ids. It also warns about production data. However, it never explicitly says when to choose this tool over the create/update/patch siblings or read tools, so the usage context is only implied.

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 explicitly warns that it alters production data (since Bsoft has no homologation environment), which is critical behavioral information beyond the annotations. It also discloses the requirement for id and parent_id for specific operations, and notes the bulk execution capability. This is valuable transparency; annotations only provide operational hints (readOnly, idempotent, destructive) but do not mention the production impact, so the description adds significant context.

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 but packs essential information: operation type, production warning, parameter requirements, acceptable resources list, and bulk support. It is front-loaded with the most critical info (production alert) and structured logically. Minor redundancy in listing resources both in description and schema enum, but that's acceptable for clarity.

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 (many resources, varied actions, bulk support, nested resources) and lacking output schema or annotations providing details, the description covers the key aspects: it explains the required parameters, special cases (id, parent_id, create_lote), and production impact. It is complete enough for an agent to invoke the tool correctly for patch operations.

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%, but the description explains the key parameters: resource (with enum list), action (though not an explicit parameter, seems implied), body (JSON), id for updates/deletes, parent_id for nested resources. It also introduces ids and parent_ids for bulk. This adds meaning beyond the schema, though it doesn't detail the body structure or specific parameter formats, but given the complexity, it 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 it performs write operations (create/update/delete) on financeiro resources in the Bsoft TMS, and lists the specific writable resources. It distinguishes from read-only sibling tools like 'bsoft_financeiro' by explicitly marking this as write operations with a production alert.

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 clear usage context: requires resource, action, and body parameters, and specifies requirements for update/patch/delete (id) and nested resources (parent_id). It also notes bulk support with ids/parent_ids. However, it doesn't explicitly state when not to use this tool versus alternative create/update/delete tool variants, though the tool name itself distinguishes patch 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?

The description includes a clear warning that it alters PRODUCTION data and that there is no staging environment (homologação). This goes beyond the annotations, which only indicate readOnlyHint=false and destructiveHint=false, and provides critical behavioral context for the 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?

The description is somewhat cluttered with repeated resource lists and auto-generated annotations like 'Flattened action' and 'Bulk support'. The core instructions are intermixed with warnings and generic statements, making it less concise than it could be.

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 complexity (7 parameters, no output schema), the description lacks important details such as the expected format of the 'body' payload, the exact behavior of an update (partial vs. full), error handling, or return values. It only partially covers the operation's 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?

It explains that id is needed for update/patch/delete, parent_id for nested resources, and that bulk execution uses ids. However, it does not explain the 'body' parameter (what JSON structure is expected) or the 'account' parameter. The resource enum is listed redundantly, but other parameters remain underexplained.

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 mentions the domain (Financeiro) and the action 'update' in the tool name, but the text says 'escrita: cria/atualiza/remove' (write: create/update/delete), which could apply to all write tools. It does not explicitly state that this tool is exclusively for updating existing records, especially given separate create/delete/patch siblings.

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 provides some guidance on required parameters (id for update/patch/delete, parent_id for nested resources, bulk support via ids) but does not clearly differentiate when to use this tool vs. create, patch, or delete. It does not mention when an update is preferred over a patch, and lacks explicit 'use this when...' instructions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds value by specifying the scope ('conectados a este install') and the returned fields (id, label, domain), which are not in the annotations or schema. This is useful context beyond the structured data.

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 is front-loaded with the verb and key details. Every word adds value; there is no fluff or redundant language.

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 operation with strong annotations, the description covers the core purpose and return fields. However, it lacks any explanation of the 'account' parameter and provides no usage context relative to siblings. Given the absence of an output schema and the parameter gap, it is not fully complete, but adequate for a basic list 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?

The schema has one parameter 'account' with no description (0% coverage), and the tool description does not mention it at all. There is no compensation for the missing schema description, leaving the agent with no guidance on what the parameter means or how to use 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 that the tool lists Bsoft tenants (domains) connected to this install, and specifies the returned fields (id, label, domain). This is a specific verb+resource with clear scope, distinguishing it from sibling tools that operate on other resources.

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 no explicit guidance on when to use this tool versus alternatives. It implies usage when listing accounts, but does not mention exclusions, prerequisites, or alternative tools. For a simple list tool, this is acceptable but not enhanced.

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, aligning with the description's '(leitura)'. The description adds valuable behavioral context beyond annotations by explaining pagination, filtering, nesting, and bulk execution. It does not repeat safety claims but clarifies operational semantics, which is sufficient given the annotations' coverage.

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 front-loaded with the primary purpose and resource list, followed by usage patterns. It is a single paragraph but logically organized (domain, then usage, then resources, then bulk note). Every section serves a purpose, and the length is justified by the tool's complexity (9 parameters, multiple resources).

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 no parameter descriptions, this description provides substantial guidance: it covers listing vs. single record, pagination, filtering, nesting, and bulk operations. It does not clarify return field details or error handling, and misses the 'account' parameter, but given the domain-specific resource names, the data shape is largely inferable. Overall, it is complete enough for an agent to use effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates for most parameters: resource, id, parent_id, offset, limit, query, and bulk ids/parent_ids. It explains pagination and filter format (JSON) but omits the 'account' parameter entirely, and does not specify which resources are nested or the exact structure of the query. This leaves a minor gap but is largely effective.

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 it is for reading maintenance/fleet data from Bsoft TMS, explicitly marked as '(leitura)' to separate it from the write sibling tools. It enumerates the specific resources available (abastecimentos, pneus, equipamentos, etc.), making the purpose unambiguous and distinct from other Bsoft read 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?

Provides explicit usage instructions: how to retrieve a single record with `resource` + optional `id`, how to list with pagination via offset/limit, and how to filter with `query` JSON. It also explains nested resources require `parent_id` and mentions bulk support with `ids`/`parent_ids`. These guidelines are concrete and actionable for selecting and invoking 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?

Adds a valuable warning that it alters production data ('Altera dados de PRODUÇÃO') and mentions bulk support. However, the description's claim that it also handles update/patch/delete contradicts the tool's designated create-only scope, creating confusion. Annotations correctly indicate a write tool, so no annotation contradiction.

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 reasonably concise with a warning and line breaks, but the inclusion of update/delete details and create_lote in a create-specific tool makes it less focused. Some redundancy exists between 'cria/atualiza/remove' and 'update/patch/delete'.

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 7 parameters and no output schema, the description is incomplete. It does not explain what 'body' should contain, the purpose of 'account', or how the bulk parameters work in detail. It fails to clarify that this is specifically for creating new records, making it insufficient for correct invocation.

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% coverage, so description must compensate. It explains that id is required for update/patch/delete and parent_id for nested resources, and lists the valid resource enum values. However, it references 'action' which is not in the schema, and does not explain 'body', 'account', or the distinction between id and ids, leaving gaps.

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's a write tool for Bsoft maintenance/fleet with resources abastecimentos, abastecimentosProprios, pneus, but it says 'cria/atualiza/remove' (create/update/remove), which conflicts with the tool's name 'write_create' and the presence of separate siblings for update/delete. It fails to clearly distinguish this create-only tool from its siblings.

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?

Gives generic usage instructions ('Passe resource, action e body') but no explicit guidance on when to use this tool vs. the update or delete variants. It mentions requirements for id and parent_id for other actions, but does not state 'use this to create new records' or 'for updates use write_update, for deletions use write_delete'.

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 include readOnlyHint: false, idempotentHint: false, destructiveHint: false, which indicate it's a write operation that may change data. The description adds a crucial warning: '⚠️ Altera dados de PRODUÇÃO (o Bsoft não tem homologação).' This is a significant behavioral disclosure beyond the annotations. It also mentions that update/patch/delete require id, which is operational detail. However, it doesn't detail side effects like whether create is idempotent or what happens on failure, but given the annotations already cover safety profile, the added context is valuable.

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 somewhat rambling and mixes general instructions with specific tool details. It front-loads the main purpose and warning, but then lists details in a somewhat disorganized manner. Despite that, it's relatively short and contains necessary information: the operation scope, the warning, required parameters, and writable resources. There is some redundancy (e.g., repeating 'create_lote' and bulk support), but it's acceptable. The structure could be improved by separating the tool-specific info from the general, but it's not overly verbose.

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 (multiple parameters, batch mode, production warning), the description covers essential aspects: the writable resources, the need for id and parent_id, the bulk support, and the critical production warning. However, it lacks details on the exact body structure for create_lote (e.g., array format) or any return value information, but there is no output schema. It also doesn't mention the HTTP methods for each action explicitly, but it's implied. The description is adequate for a competent agent but could be more complete by specifying the batch endpoint and how to construct the body.

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 description coverage is 0%, so the description must compensate. It explains that 'body' is a JSON string, and that create_lote sends a list to the /lotes endpointikuha. It also clarifies that resources can be 'abastecimentos', 'abastecimentosProprios', 'pneus' (which are also in the schema enum). It explains the use of 'id' and 'parent_id' for certain operationscpp, and mentions 'ids' and 'parent_ids' for bulk operations. This goes beyond the schema by connecting parameter usage to the tool's behavior, but it doesn't explain the exact format of 'body' for create_lote or list the fields required for each resource.

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 this is for 'Manutenção / Frota no Bsoft TMS' and specifically for writing operations (create/update/remove). The flattened action 'create_lote' at the end indicates this is the batch create variant, which distinguishes it from other write tools like create, update, delete. However, the description is a bit generic for a create_lote tool; it doesn't explicitly state that it handles batch creation of multiple records, although it mentions 'create_lote envia lista no endpoint /lotes' and 'Bulk support'.

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 tells agents to pass resource, action, and body, and specifies that update/patch/delete require id and nested resources require parent_id. It also lists writable resources. However, it does not clearly differentiate this tool from its siblings like create, update, patch, or delete. It mentions 'create_lote' but doesn't give explicit guidance on when to use this batch version over the single create, nor does it mention when not to use it. The context that it's a write operation to production data is useful, but the when-to-use guidance is incomplete.

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 annotation destructiveHint is false, yet the tools purpose is deletion, which is inherently destructive. The description itself states 'remove' and warns about altering production data, but it does not explicitly state that deletions are permanent or irreversible. This directly contradicts the annotation (destructiveHint=false) and provides insufficient behavioral disclosure about the destructive nature of the operation, scoring 1 for transparency.

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 relatively concise, but its structure is disjointed. It starts with a general write statement, then includes a safety warning, then a set of parameter instructions, and ends with a bulk note and a '[Flattened action: delete]' bracket. The inclusion of create/update in the first sentence is unnecessary for a delete-specific tool, and the bracket seems out of place. While not overly long, the organization reduces clarity.

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 (write operation, multiple resource types, bulk and parent support), the description lacks essential context. It does not explain what happens upon success (e.g., return value, confirmation), error behavior, permissions required, or irreversibility of deletion. Since there is no output schema, the description should cover these aspects, but it only partially addresses them with the production warning and bulk mention, 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?

The schema has 7 parameters with 0% coverage in the description, so the description must compensate. It explains that 'resource' is an enum, 'id' is required for update/patch/delete, 'parent_id' for nested resources, and 'ids' for bulk operations. However, it does not clarify 'body', 'account', or 'parent_ids' (beyond bulk), and incorrectly mentions an 'action' parameter that does not exist in the schema. This adds some value but introduces confusion and remains incomplete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Manutenção / Frota no Bsoft TMS (escrita: cria/atualiza/remove)' which implies this tool handles all write operations, but the tool name and the '[Flattened action: delete]' indicate it is specifically for deletion. It does not distinguish itself from sibling write tools (create, update) and lists resources, but fails to clearly state 'this tool deletes records' in a concise manner. The purpose is muddled by including create/update language.

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 no explicit guidance on when to use this delete tool versus its siblings (e.g., bsoft_manutencao_write_create, bsoft_manutencao_write_update). It mentions that update/patch/delete require an id, implying these operations share requirements, but does not specify 'use this tool when you need to delete a record'. No exclusions or conditions are given, leaving the agent without clear usage boundaries.

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

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

The description discloses a critical warning about production data ('Altera dados de PRODUÇÃO') and bulk support (ids, parent_ids), which adds value beyond the annotations that only indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. No contradiction with annotations exists; though destructiveHint is false, the warning is a safety note, not a claim of destructiveness.

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 somewhat cluttered: it mixes Portuguese and English, includes an artifact '[Flattened action: patch]', and references create_lote which may not be relevant to this patch-specific tool. It is not overly long but lacks clear structure and could be more streamlined.

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 7 parameters and no output schema, the description covers resource enum, id/parent_id requirements, and bulk support, but fails to clarify that this tool performs only patch operations (contradicting the broader 'cria/atualiza/remove' claim). It also does not describe the response format or error behavior, leaving important context missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must help. It explains 'body' as JSON, id/parent_id requirements, and bulk ids/parent_ids. However, it does not explain the 'account' parameter at all, and it mentions an 'action' parameter that is not in the schema, causing confusion. Partial compensation for schema gaps.

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's a write tool for maintenance/fleet (Manutenção / Frota) and lists writable resources. However, it says 'cria/atualiza/remove' (creates/updates/removes) while the tool name indicates 'patch' and the note '[Flattened action: patch]' suggests only patch operations. This ambiguity about the exact action type makes the purpose less clear, especially given sibling tools like create/update/delete.

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 guidance is provided on when to use this tool versus siblings (e.g., create, update, delete). The description mentions requirements like 'update/patch/delete exigem id' but does not explain when to choose patch over other write operations. It lacks explicit context or exclusions.

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

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

The description explicitly warns '⚠️ Altera dados de PRODUÇÃO (o Bsoft não tem homologação)', which is a critical behavioral trait not captured in annotations (which only mark readOnlyHint false). It also explains that update requires an id, nested resources require parent_id, and bulk execution via ids/parent_ids, adding transparency beyond the schema. Minor detraction is the irrelevant reference to create_lote, but the production warning and requirements make it strong.

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 moderately concise with a front-loaded warning and clear instructions. It includes a warning, parameter requirements, and bulk support note, but some content (like create_lote details) is irrelevant to this specific tool and adds noise. Overall, it is efficient and well-structured, earning a 4.

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 key operational aspects: production impact, id requirement for update, nested resources needing parent_id, and bulk support. However, it lacks details on return values (no output schema), what body should contain for each resource type, and does not explain the 'account' parameter. The conflation of multiple CRUD operations also reduces completeness for the update-specific 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?

With 0% schema description coverage, the description carries the burden of explaining parameters. It clarifies id (required for update), parent_id (for nested resources), body (JSON), and ids/parent_ids (for batch). However, it introduces 'action' as a parameter that is not in the schema, potentially confusing the agent, and fails to explain the 'account' parameter. So it partially compensates but has notable gaps.

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 says 'Manutenção / Frota no Bsoft TMS (escrita: cria/atualiza/remove)' which is generic for all write operations, but the tool name and '[Flattened action: update]' indicate it is specifically for updates. It lists writable resources but doesn't explicitly state that this tool updates existing records, making it ambiguous among the create/delete/patch siblings.

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 mentions 'update/patch/delete exigem id' but does not clearly indicate when to use this update tool vs the patch or delete tools. It also references create_lote which belongs to a different tool, and lacks explicit guidance like 'use this for modifying existing resources' or how to choose between update and patch. This leaves the agent without clear decision 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, idempotentHint, and destructiveHint, so the baseline is high. The description adds useful behavioral details beyond those annotations: pagination semantics, query filtering with JSON, the need for parent_id on nested resources, and bulk execution via ids/parent_ids. It does not mention return format or authentication, but these are less critical for a read-only, non-destructive tool.

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 starts with the core purpose, then flows into usage patterns, resource enumeration, and bulk support. The resource list somewhat duplicates the schema enum, but it reinforces availability without adding excessive bulk. Overall it is efficient and front-loaded, though a bit dense due to the long list of resources.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only multi-resource tool with 9 parameters and no output schema, the description covers most necessary context: how to fetch single records, list with pagination, filter, handle nested resources, and batch via bulk parameters. Gaps like return shape and the meaning of `account` are minor given the tool's query-oriented nature and the existence of sibling write tools that handle mutations.

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 carries the burden of explaining parameters. It meaningfully explains `resource`, `id`, `offset`, `limit`, `query`, `parent_id`, and bulk `ids`/`parent_ids`, which is substantial compensation. However, the `account` parameter is left unexplained and the exact structure of `query` JSON is vague, preventing a perfect score.

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 this as a read-only tool for Bsoft TMS service orders ('Ordem de Serviço no Bsoft TMS (leitura)') and enumerates the exact resources available, such as ordensServico, agendamentos, materiais, status, and tipos. The '(leitura)' marker and explicit resource list distinguish it from the sibling write tools like bsoft_os_write_create and bsoft_os_write_update.

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 concrete usage patterns: pass `resource` plus optional `id` for a single record, or omit `id` to list with offset/limit pagination and JSON query filters. It also explains that nested resources require `parent_id` and mentions bulk support for ids/parent_ids, giving clear operational context. It does not explicitly contrast with write siblings, but the read-only label and sibling naming make the distinction obvious.

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 and destructiveHint=false, but the description adds critical context: it warns that this alters PRODUCTION data and that Bsoft has no homologation environment. This is valuable beyond annotations. It also notes bulk support for batched execution, which is behavioral context not present in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the core purpose. It uses bullet-point-like formatting and a warning emoji to highlight the production risk. The 'Flattened action: create' line is redundant but clarifies the action, and the bulk support note is brief. No excessive verbosity, but it could be slightly tighter by removing the redundant flattened action note.

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 WRITE tool with 7 parameters, 0% schema coverage, no output schema, and no annotations beyond readOnly/destructive hints, the description covers the essential operational details: required parameters, the production warning, the need for id/parent_id, and bulk support. However, it lacks details on return format, error handling, or validation constraints that an agent might need to anticipate failure modes. Given the tool's complexity and risk, a 4 is appropriate.

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% (no parameter descriptions in the schema), but the description lists key parameters in prose: 'resource', 'action', 'body', 'id', 'parent_id', and mentions the 'lotes' endpoint for lists. This partially compensates for the schema's lack of descriptions. However, the description does not explain the format of 'body' (e.g., JSON structure) or the purpose of 'ids' and 'parent_ids' beyond bulk support, leaving some 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?

The description clearly states 'Ordem de Serviço no Bsoft TMS (escrita: cria/atualiza/remove)' and lists the writable resources, distinguishing it from read-only siblings and other write tools. However, the opening sentence is a bit general (covers create/update/remove) without emphasizing that this tool is specifically for create operations, which is clarified later by 'Flattened action: create'.

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 guidance on using 'resource', 'action', and 'body', and states that update/patch/delete require 'id' and nested resources require 'parent_id'. It also mentions the create_lote endpoint for lists, which helps differentiate this create tool from sibling write tools. However, it does not explicitly say when to use this tool vs alternatives like the dedicated create_lote sibling.

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 it's not read-only. The description adds a critical warning that it alters PRODUCTION data and that there is no staging environment, which is valuable. It also mentions the specific endpoint and bulk execution behavior. However, it doesn't detail failure handling, idempotency, or side effects beyond the production warning, which would enhance transparency.

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 yet information-dense, front-loading the critical production warning. It uses semicolons to separate instructions efficiently. The inclusion of generic write actions ('cria/atualiza/remove') is redundant for a flattened create_lote tool but does not significantly harm 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?

Despite having no output schema, the description covers the core purpose, endpoint, required parameters, and production impact. It lists writable resources and bulk options. It might be improved by mentioning the expected response (e.g., created records or IDs), but for a bulk write operation, this is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must explain parameters. It explains resource, action, body, id (for updates), parent_id (nested), and ids/parent_ids (bulk). However, it does not mention the 'account' parameter at all, leaving its purpose ambiguous. This is a gap given the schema provides no hints.

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 is for writing Ordem de Serviço (OS) in Bsoft TMS, with the action 'create_lote' sending a list to the /lotes endpoint. It identifies the writable resources (ordensServico, ordensServico/acao) and emphasizes bulk support. However, the opening line mentions 'cria/atualiza/remove' which could confuse since this is specifically for create_lote, slightly diluting the focus.

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 instructions on required parameters (resource, action, body) and notes that update/patch/delete need 'id' and nested resources need 'parent_id'. It implies use for bulk creation via 'Bulk support: accepts ids, parent_ids for batched execution,' but does not explicitly state when to prefer this over the single-create sibling (bsoft_os_write_create). The production warning is useful but not directly about usage selection.

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 warns about altering production data, which is good. However, it does not clarify that deletion is permanent or destructive, and the annotation 'destructiveHint: false' contradicts the implied destructive nature of a delete operation.

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 relatively concise and includes a useful production warning, but the structure is somewhat jumbled, mixing general write operations with delete-specific details and referencing undefined parameters.

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 that this tool is for delete operations, the description lacks specific context such as how to target a single record vs bulk delete, expected outcomes, and prerequisites. It does not adequately distinguish this tool from its write siblings, leaving the context incomplete.

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 introduces an 'action' parameter not defined in the input schema. It explains id and parent_id requirements but does not clearly describe the use of 'ids' for bulk operations or how 'body' is used in delete, leaving parameter semantics incomplete.

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 'cria/atualiza/remove' (create/update/remove) which implies all write operations, but the tool name is specifically for delete. This ambiguity makes it unclear that the tool is exclusively for deletion of Ordem de Serviço records.

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 mentions requirements like needing an id for update/patch/delete and parent_id for nested resources, but does not explicitly say when to use this tool versus the create/update/patch siblings. It also references an 'action' parameter that is not present in the schema, adding confusion.

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 contradicts the annotations: it says the tool 'cria/atualiza/remove' and warns 'Altera dados de PRODUÇÃO', implying destructive/removal capability, while destructiveHint is false. Although the production-data warning is valuable, the contradiction with the structured annotation makes this dimension fail.

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 compact paragraph that front-loads the critical production warning and packs in requirement conditions and bulk support without excessive verbosity. The mention of 'action' is slightly disorganized, but overall every sentence conveys useful 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?

Given no output schema and weak annotations, the description does cover key operational constraints and production risk. But it leaves significant gaps: the missing 'action' property, no explanation of 'account', no body schema or examples, and no mention of return behavior. A tool that mutates production data with no output schema needs more complete guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate. It adds meaning by explaining that body is JSON, id is required for updates/patches/deletes, parent_id is for nested resources, and ids/parent_ids enable bulk operations. However, it references an 'action' parameter not present in the schema and does not explain the 'account' parameter or the body structure.

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 this tool writes to Ordem de Serviço in Bsoft TMS ('escrita: cria/atualiza/remove') and enumerates the writable resources. However, it does not differentiate this patch-specific tool from sibling create/update/delete tools, and it confusingly mentions an 'action' parameter that is absent from the input schema.

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 provides operational context: update/patch/delete require id, nested resources require parent_id, create_lote uses /lotes, and bulk execution accepts ids/parent_ids. However, there is no explicit guidance on when to prefer this tool over the sibling write tools, and the description frames it as a general write tool rather than specifically a patch operation.

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 warning about production data and lack of homologation adds valuable context beyond the annotations. However, it inconsistently mentions multiple actions (update/patch/delete) and 'create_lote', which could mislead about actual behavior. It doesn't describe return values or side effects beyond the generic 'altera dados'.

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 verbose and redundant. It lists resources, mentions actions not relevant to the tool, and has an odd '[Flattened action: update]' line. The flow is not clear, and the production warning interrupts the instruction flow. Could be condensed into a focused, single-purpose description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an update tool with 7 parameters and no output schema, the description lacks critical details: what the response looks like, required vs optional parameters per action, error behavior, and how `action` fits (since it's not in the schema). The bulk support mention is vague and doesn't clarify batching mechanics.

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 coverage, the description must compensate but only partially does. It explains that `id` is required for update, `parent_id` for nested resources, and bulk uses `ids`, but it fails to explain `account`, `body` details, and introduces `action` which is not in the schema. This is confusing and incomplete.

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 is ambiguous: it says 'cria/atualiza/remove' (create/update/remove) but the tool name is 'write_update' and sibling tools exist for create/delete/patch. It doesn't clearly state that this tool specifically updates OS records, and the mention of 'create_lote' and multiple actions muddies the 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?

No explicit when-to-use guidance or distinction from sibling tools (e.g., 'Use this instead of bsoft_os_write_patch to update OS'). It mentions general requirements like id and parent_id but does not clarify when this tool is the right choice over create/delete/patch tools.

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's main behavioral add is that it is for reading ('leitura') and explains pagination via offset/limit and query filters, plus bulk support with ids and parent_ids. This adds context on how pagination works and that bulk operations are supported, which is beyond the annotations. It does not describe return format or edge cases (e.g., errors, rate limits), but given strong annotations, this is adequate but not exceptional.

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 and front-loaded with the primary purpose, then a how-to sentence, then a list of resources, and a final bulk note. The structure is logical, and every sentence adds value—except perhaps the bulk support sentence could be more explicit about how to use it, but it is still informative. It is not verbose, and the resource list is useful. Slightly under-detailed on bulk mechanics, but overall efficient.

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 9 parameters, no output schema, and modest annotations, the description covers the main usage patterns (single get, list with pagination, nested resources, bulk) but misses the 'account' parameter entirely, which is a significant context signal given that it's a common parameter in this API family (bsoft_list_accounts suggests account contexts). It also doesn't explain the 'query' format beyond saying it's JSON, which could be ambiguous. Given the tool's moderate complexity, completeness is acceptable but not thorough.

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 explains the role of resource, id (optional), query (JSON filters), offset/limit (pagination), parent_id (nested resources), and bulk ids/parent_ids. However, it does not explain the 'account' parameter, which is new and not self-explanatory. The description adds meaning for most parameters but leaves 'account' undefined. Given 9 parameters and 0% coverage, the description partially compensates but with a notable 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 begins with 'Pessoas no Bsoft TMS (leitura)' and explicitly states the read-only nature, listing the types of registers (physical and legal persons) and the resource paths. It clearly distinguishes from write siblings by the '(leitura)' suffix and the readOnlyHint annotation, and it enumerates all supported resources, making it distinct from other bsoft_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage instructions: pass resource with optional id to get a single record, or without id to list with pagination and filters using query JSON. It mentions nested resources require parent_id. However, it does not explicitly say when not to use this tool (e.g., for writes) or contrast with sibling tools, though the read-only context is implicit. The sibling list shows separate write tools, and the readOnlyHint annotation makes exclusion 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 state readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds a critical warning about PRODUCTION data and lack of homologation, which is valuable. It also explains the need for id for updates and parent_id for nested resources. However, it doesn't disclose details about authentication requirements or what exactly gets created or deleted, relying on annotations for safety profile.

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 moderately concise, but it includes a mixed set of instructions (write operations in general) that could confuse for a create-specific tool. It front-loads the warning but then covers multiple actions, making it less focused and efficient.

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 7 parameters, no output schema, and no annotations on return values. The description explains the core flow (resource, action, body) and addresses nested resources and bulk support, but lacks detail on parameter formats (e.g., body structure) and response handling. It is sufficient for basic creation but incomplete for advanced 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?

Schema description coverage is 0%, so the description must compensate. The description explains the purpose of key parameters like resource, action, body, id, and parent_id, but does not elaborate on 'account', 'ids', or the structure of the body JSON. Since coverage is 0%, a baseline of 3, but it's borderline; the description adds initial context but leaves many parameters under-documented.

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 it handles creation (and other write operations) for 'pessoas' resources in Bsoft TMS, listing the specific sub-resources. It distinguishes from siblings by being scoped to 'pessoas' and using 'create', but it also mentions update/delete actions, which may cause ambiguity with sibling tools dedicated to those 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?

It provides clear instructions on required parameters (resource, action, body) and notes when id is needed (update/patch/delete) and when parent_id is needed (nested resources). It also mentions the bulk support. However, it does not explicitly say when to prefer this tool over sibling 'write_create_lote' or other write variants beyond the action implication.

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 critical context beyond annotations by warning '⚠️ Altera dados de PRODUÇÃO (o Bsoft não tem homologação),' which is absent from the annotations. It also lists writable resources and explains parameter requirements for nested resources (parent_id). However, it does not disclose return values or error behavior, and the mention of 'action' (which is not in the schema) could cause confusion. Overall, it provides valuable operational transparency.

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, front-loaded with a production warning, then provides resource lists, parameter notes, and a bulk support line. It is structured in short paragraphs that are easy to scan. Every sentence adds value, though some redundancy exists between the generic write statement and the specific batch focus.

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 7 parameters and no output schema, the description covers the production warning, supported resources, endpoint behavior, and partial parameter requirements. However, it does not describe the body format in detail, does not mention return values or error handling, and has a mismatch with the nonexistent 'action' parameter. The description is adequate for basic usage but not fully complete for a complex batch write 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?

With 0% schema description coverage, the description must compensate. It explains that 'resource' and 'body (JSON)' are used, and that 'update/patch/delete exigem `id`' and 'recursos aninhados exigem `parent_id`.' It also notes 'create_lote envia lista' indicating the body contains a list. However, it omits explanation of 'account' and does not specify the exact structure of the body list. It also references 'action,' which is not a schema parameter, adding confusion. This partially compensates but leaves gaps.

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 handles 'Pessoas no Bsoft TMS (escrita: cria/atualiza/remove)' and specifically notes 'create_lote envia lista no endpoint /lotes.' It correctly identifies this as the batch variant, distinguishing from singular write tools like bsoft_pessoas_write_create. However, the generic 'cria/atualiza/remove' may confuse agents into thinking it handles all write actions, which is not the case for this specific tool.

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 mentions 'Bulk support: accepts ids, parent_ids for batched execution' and 'create_lote envia lista no endpoint /lotes,' clearly implying this tool is for batch operations. Yet it does not explicitly state when to use this instead of the singular create tool, nor does it describe exclusions or scenarios where this tool is inappropriate. The guidance 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?

The description clearly states '⚠️ Altera dados de PRODUÇÃO' and implies deletion through 'remove' and 'delete', which are destructive operations. However, the annotation destructiveHint is false, which directly contradicts the described behavior. This is a serious inconsistency that undermines trust in the tool's safety profile. Aside from the production warning, no other behavioral traits (e.g., idempotency, side effects) are disclosed.

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 relatively short but packs several concepts in a somewhat disorganized way. It includes a warning, general write capabilities, parameter requirements, a flattened action note, and bulk support. The '[Flattened action: delete]' line is oddly placed and might confuse. It could be more streamlined and front-loaded with the delete-specific 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 the complexity (7 parameters, no output schema, no annotation coverage), the description is insufficient. It does not explain what the return value is, what happens on successful delete, or any error scenarios. It also does not clarify the full behavior for delete specifically, such as whether it deletes single or multiple resources, or the effect of missing required fields beyond id. The description leaves many gaps for an agent to operate 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?

Schema description coverage is 0%, so the description must explain parameters. It mentions that update/patch/delete require 'id', nested resources require 'parent_id', and bulk operations accept 'ids' and 'parent_ids'. However, it does not explain the 'body' parameter (only that it is JSON) or the 'account' parameter at all. The description adds some context for id-related fields but leaves key parameters undocumented.

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 'Pessoas no Bsoft TMS (escrita: cria/atualiza/remove)' which is generic for all write operations, not specifically delete. The tool name and '[Flattened action: delete]' suggest delete-only, but the description does not clearly state that this tool is for deleting people resources. It also references an 'action' parameter that is not present in the schema, adding confusion.

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 constraints like 'update/patch/delete exigem id' and mentions bulk support, but it does not explicitly say 'use this tool when you need to delete a person resource'. There is no guidance on when to prefer this over the other write tools (create, update, patch) or what distinguishes it from them. The mention of 'action' without a schema field adds ambiguity.

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 says this tool can create, update, and remove, and states that delete requires id, while annotations declare destructiveHint=false. This is a direct contradiction between the described capability of removing data and the structured annotation claiming no destructive behavior. The production warning is useful, but the contradiction rule applies.

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 production warning and core usage rules are front-loaded and mostly efficient. The description loses some focus because it lists create/update/delete behaviors and resource values that are already implied by the tool name and schema, and it mentions create_lote even though this tool is action-specific to patch.

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 7-parameter, no-output-schema tool, the description covers the basic patch workflow and bulk support, but not the body payloads, error/response behavior, the account parameter, or the meaning of each resource in enough detail. It is sufficient for a simple use case but not fully self-contained.

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 explains that body is JSON, id is needed for patch/update/delete, parent_id is needed for nested resources, and bulk execution uses ids and parent_ids. The account parameter and detailed per-resource body contents remain undocumented, preventing a 5.

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 identifies Pessoas in Bsoft TMS as the domain, calls it a write tool, and lists the exact writable resources, with the flattened-action line showing this is the patch variant. However, the phrase “cria/atualiza/remove” is broader than a patch tool and the resource list duplicates the schema enum, so it is not maximally 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?

It provides useful routing rules: update/patch require id, nested resources require parent_id, and bulk execution accepts ids/parent_ids. It also warns against using this on production data. However, it does not say when patch should be preferred over update/delete/create, nor when a read tool like bsoft_pessoas should be used instead.

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 a significant warning that it alters production data and that there is no staging environment, which goes beyond the readOnlyHint annotation. It also mentions bulk execution via ids. However, it does not describe side effects, error behavior, or idempotency (which is already hinted as false). The transparency is adequate but not exhaustive.

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 verbose, with redundancy such as repeating the list of resources and mixing multiple actions (create/update/remove) into the update-specific tool. While organized, it could be more concise and focused on the update action alone. The repeated warnings and lists add length without proportional 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 provides essential context: it targets people resources, lists the writable sub-resources, specifies required parameters, warns about production impact, and notes bulk support. Given the absence of an output schema, the description gives enough operational context for a user to understand what the tool does and its critical constraints. It is fairly complete for the given 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 description explains that `id` is required for update, `parent_id` for nested resources, and that `body` is JSON. It also clarifies bulk support with `ids` and `parent_ids`. However, it does not explain the `account`, `resource`, or `action` parameters beyond listing resources, leaving some ambiguity. The parameter documentation is partial.

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 handles people resources and mentions 'escrita: cria/atualiza/remove' (create/update/remove), but the tool name is specifically 'write_update'. It later clarifies 'Flattened action: update', but the initial mention of create/remove introduces ambiguity. The purpose is reasonably clear but not sharply distinguished from create/patch/delete siblings.

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 provides conditions like 'update/patch/delete exigem `id`' and nested resources requiring `parent_id`, and warns about production data. However, it does not explicitly state when to use this tool over the create, patch, or delete variants. The guidance is present but not fully explicit regarding alternatives.

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 doesn't need to restate safety. It adds useful context about pagination (offset/limit), filtering (query JSON), and bulk support (ids, parent_ids). However, it doesn't describe return format or error behavior, which is acceptable given annotations cover the safety profile.

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. It uses bullet-like structure for resource types and parameters. Every sentence adds value, though the bulk support sentence could be more specific. It's appropriately sized for a 9-parameter 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 has 9 parameters, no output schema, and moderate complexity, the description covers the main usage patterns: single record, list, nested, and bulk. It doesn't explain the 'account' parameter or return structure, but the core functionality is well-covered. The annotations provide safety context, so the description is reasonably complete.

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 explains the key parameters: resource (with enum values listed), id (single record), offset/limit (pagination), query (filters), parent_id (nested resources), and ids/parent_ids (bulk). However, it doesn't explain 'account' parameter, and the description is somewhat terse. It adds meaning beyond the schema for most parameters, but not all.

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 reads Bsoft TMS resources (users) and lists the specific resource types (recursos, grupos, inatividades, IPs de acesso). It distinguishes from write siblings by explicitly noting '(leitura)' and the readOnlyHint annotation. However, it doesn't explicitly contrast with sibling read tools like bsoft_pessoas, but the resource scope is clear.

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 when to use it: pass resource + optional id for a single record, or no id to list with pagination and filters. It also mentions nested resources require parent_id. It doesn't explicitly say when NOT to use it or name alternatives, but the usage pattern is clear and distinct from write tools.

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?

It adds a production warning and notes parameter requirements (body JSON, id, parent_id), but it also includes contradictory statements (mentioning update/patch/delete in a create-only tool) and fails to clearly disclose the tool's exact side effects. Annotations provide no safety context, so the description carries the burden but is inconsistent.

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 reasonably tight, with the production warning placed first. It lists resources and key constraints without excessive verbosity, though the mention of unrelated actions (update/patch/delete) detracts from structure.

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 7 parameters, no output schema, and no behavioral annotation beyond flags. The description does not explain what the response looks like, does not clarify the `account` parameter, and gives mixed signals about the action. It fails to comprehensively cover the tool's behavior for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains some parameters (body is JSON, id needed for updates, parent_id for nested, ids/parent_ids for bulk), but it omits `account` and introduces a non-existent `action` parameter. With 0% schema coverage, it should explain each parameter adequately, which it does only partially.

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 handles 'recursos' but describes a generic write capability ('cria/atualiza/remove') while the tool name and ['Flattened action: create'] indicate it is specifically for creating. It does not clearly identify this tool as the create-only variant, nor does it distinguish it from siblings like update, delete, or create_lote.

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 no explicit guidance on when to use this tool versus the other write variants. It mentions that update/patch/delete require an id, but this is not selection guidance; it does not say 'use this to create new resources' or compare to create_lote.

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 a critical warning that it alters PRODUCTION data (since Bsoft has no staging environment), which goes beyond the annotations (which only indicate not read-only). It also discloses that it uses a specific endpoint and accepts ids/parent_ids for batch operations. This is valuable context not present in the structured fields.

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 moderately concise but includes redundant information: it repeats the list of writable resources which is already fully enumerated in the schema's enum. It also includes parameter guidance for update/patch/delete actions that are not relevant to a create_lote tool, making it slightly unfocused. The structure is acceptable but could be trimmed.

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?

With no output schema, the description should explain expected return values, success/error handling, or atomicity. It does not. It covers production impact and batch behavior, but doesn't mention what happens after a batch create succeeds (e.g., response format, error handling). This leaves significant gaps for an agent to know what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains some parameters (resource, id, parent_id, ids, parent_ids) and introduces the concept of 'action' which is not in the schema (a mismatch). It does not explain 'body' or 'account', and with 0% schema coverage, it doesn't fully compensate. The bulk execution hint clarifies ids/parent_ids but other parameter meanings remain 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 clearly states it is a write tool for 'recursos' (system users) in Bsoft TMS, and specifically indicates that create_lote sends a list to the /lotes endpoint. This distinguishes it from the single-create sibling (bsoft_recursos_write_create) by mentioning the batch nature, though it doesn't explicitly compare them.

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 provides some guidance on when to use it (bulk support, batch execution), but it doesn't explicitly state when to choose this over the non-lote variant or mention conditions like 'use this for multiple resources at once.' It also includes usage details for update/patch/delete actions which may not apply to this specific tool, causing potential confusion.

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 includes a strong warning: '⚠️ Altera dados de PRODUÇÃO (o Bsoft não tem homologação)', which effectively alerts the agent to the high-impact nature of the operation. It also mentions that certain actions require 'id' and 'parent_id', providing some behavioral context. However, it does not disclose potential side effects such as idempotency, cascading effects, or whether deletions are reversible, and the annotation 'destructiveHint=false' contradicts the possibility of deletes.

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 relatively concise, containing the essential warning and a list of parameters. However, it is somewhat redundant and could be streamlined. The structure is acceptable but not exemplary.

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 presence of many sibling tools (create, patch, update, delete for the same resource), the description does not sufficiently distinguish this tool's role or provide guidance on when to use it. It also lacks details about return values or error handling, although no output schema is provided. The description is incomplete for an agent to make a fully informed decision.

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 mentions 'resource', 'action', 'body', 'id', 'parent_id', and 'create_lote', but the input schema does not include an 'action' parameter, creating a discrepancy. It also fails to explain the purpose of 'ids', 'parent_ids', and 'account'. Coverage of schema parameters is low, and the description adds limited clarity to the parameter meanings.

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 is ambiguous: it mentions 'escrita: cria/atualiza/remove' (write: create/update/remove), suggesting it covers all write operations, while the tool name 'write_delete' implies a delete-specific function. This ambiguity makes it unclear what the tool actually does, especially given the existence of separate create, patch, update, and delete tools for the same resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Some usage details are provided, such as requiring 'resource', 'action', and 'body', and noting that update/patch/delete require 'id' and nested resources need 'parent_id'. However, it does not explain when to use this tool versus the dedicated create/update/delete variants, nor does it specify the allowed values for 'action', leaving the agent uncertain about the correct selection.

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 prominently warns that it alters PRODUCTION data and that Bsoft has no homologation environment, which is critical behavioral context. It also discloses id requirements and bulk behavior, though it does not cover reversibility, response shape, or idempotency details; there is no contradiction with 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 packs several useful pieces of information: production warning, parameter requirements, resource list, flattened action, and bulk support. It is somewhat dense and redundant because the writable-resource list duplicates the schema enum, and the `action` instruction adds ambiguity rather than clarity.

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 7 parameters, 0% schema coverage, and no output schema, the description covers the main constraints needed to invoke the tool: `id`, `parent_id`, `body`, production impact, and bulk execution. It remains incomplete because `account` semantics are omitted and the behavior of a patch (partial vs. full update, return value) is not clarified.

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 compensates by explaining `resource` via the enum list, `id` for update/patch/delete, `parent_id` for nested resources, `body` as JSON, and bulk `ids`/`parent_ids`. However, `account` is never explained, and the `body` structure is left unspecified; the mention of `action` is also confusing since `action` is not present 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 identifies the resource domain (system users in Bsoft TMS) and states it is a write operation, with the flattened action 'patch' and the list of writable resources clarifying the target. However, it opens with generic 'cria/atualiza/remove' language rather than explicitly defining patch-specific partial-update semantics, so it does not fully distinguish itself from the update/delete siblings.

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 gives useful invocation rules: update/patch/delete require `id`, nested resources require `parent_id`, `body` should be JSON, and bulk execution accepts `ids`/`parent_ids`. It does not clearly state when to prefer patch over update, nor does it provide explicit when-not-to-use guidance or name alternatives for this specific 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?

The description warns that it alters PRODUCTION data and includes remove operations, while annotations declare destructiveHint=false. This directly contradicts the annotation and obscures the actual risk profile, so the warning is not enough to compensate.

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, front-loads the production warning, and every sentence adds relevant context. Minor issues: the resource list duplicates the schema enum, and the flattened-action note adds noise.

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?

With no output schema and minimal annotations, the description carries a heavy burden. It covers production risk and key field dependencies, but it omits return behavior, account semantics, exact endpoint details beyond /lotes, and fails to resolve the write-vs-update ambiguity. The destructiveHint contradiction further undermines completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics for id, parent_id, body as JSON, resource enum values, and bulk ids/parent_ids, partially compensating for 0% schema coverage. However, it does not explain account, references an action parameter not present in the schema, and leaves body formatting and exact endpoint behavior vague.

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?

Description clearly identifies the tool as writing Bsoft TMS 'recursos' (system users) with create/update/remove operations, and enumerates the writable resource paths, distinguishing it from the read-only bsoft_recursos sibling. However, the tool name says 'update' while the description claims all write actions, which muddies the exact scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides concrete usage rules: update/patch/delete require id, nested resources require parent_id, create_lote uses the /lotes endpoint, and bulk execution accepts ids/parent_ids. It does not explicitly tell when to choose this tool over the sibling create/patch/delete variants, and it confusingly references an 'action' parameter that is absent from the schema.

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/destructiveHint, and the description adds pagination, nested-resource requirements, and bulk execution behavior. It does not mention special output types for resources like conhecimentos/obterDacte or contratosFrete/pdf, but this is a minor gap given the annotation coverage.

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 well front-loaded and uses clear paragraphs, but the full resource list duplicates the input schema's enum verbatim, adding length without new information. Trimming to a reference to the schema enum would make it tighter.

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 broad read-only resource tool with no output schema, it explains the generic access pattern, pagination, filters, nested resources, and bulk support. Gaps include the `account` parameter and the non-JSON/PDF nature of some sub-resources, but core usage is sufficiently specified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining `resource`, `id` vs list mode, `limit`/`offset` pagination, `query` filters, `parent_id`/`parent_ids`, and bulk `ids`. It omits the `account` parameter, leaving one of nine parameters 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?

Description opens with 'Transporte no Bsoft TMS (leitura)', clearly stating the domain and read-only nature. It enumerates concrete resource categories (CT-e, MDF-e, veículos, agências, etc.) and the full resource list, distinguishing it from sibling bsoft_transporte_write_* 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?

It provides explicit invocation patterns: pass `resource` with optional `id`, omit `id` to list, use offset/limit pagination, query JSON filters, and `parent_id` for nested resources. It does not explicitly name write alternatives, but 'leitura' and the sibling naming make the read/write boundary 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?

The description claims the tool can 'remove' data and warns it modifies PRODUÇÃO data, while annotations set `destructiveHint` to false. This is an annotation contradiction: the text promises destructive behavior that the annotations explicitly deny. Despite useful production-warning context, per scoring rules the contradiction forces a score of 1.

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 opening warning and structural notes are useful, but the description repeats a long resource list that already exists in the schema enum and spends several lines on update/patch/delete behavior that is irrelevant to a create-specific tool. It is moderately concise but not as tight as it could be.

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 that this is a write tool, has no output schema, 7 parameters, and 0% schema description coverage, the description is not complete enough for reliable invocation. It warns about production data and lists supported resources, but it does not describe the request/response shape, error behavior, auth/account expectations, examples, or the exact management associated with the `action` requirement. The agent is left guessing on many operational details.

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 heavily. It explains generic requirements like `body` as JSON, `id` for updates, `parent_id` for nested endpoints, and bulk support via `ids`/`parent_ids`; however it never explains what valid `body` content looks like for any of the 23 resources, fails to mention the `account` parameter entirely, and references a non-existent `action` parameter. This is not enough for such a polymorphic write tool.

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 says 'Transporte no Bsoft TMS (escrita: cria/atualiza/remove)', which positions the tool as generic CRUD, not specifically as a create tool. This conflicts with the tool name and the '[Flattened action: create]' note, so the agent cannot tell whether this is create-only or a generic write endpoint. The resource list is helpful, but it does nothing to distinguish this tool from the write_patch/write_update/write_delete siblings.

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 operational constraints like requiring `body`, `id` for updates, and `parent_id` for nested resources, but it never states when to use this tool versus the sibling create_lote/patch/update/delete tools. It even instructs the agent to pass an `action` parameter and discusses update/patch/delete behavior, which is misleading for a create-only tool. No explicit when/not-to-use guidance is given.

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 warns 'Altera dados de PRODUÇÃO' which adds value beyond the annotations (which only indicate not read-only/destructive). However, it includes irrelevant details about update/patch/delete that may confuse the agent, and it does not disclose whether failures are partial or atomic. The annotation destructiveHint:false is not contradicted.

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 moderately long and includes a redundant mention of update/patch/delete requirements that do not apply to this specific action. It front-loads the critical warning and lists resources effectively, but could be tightened to focus only on create_lote behavior.

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 provides a useful overview, resource enumeration, and production warning, but lacks details on response format, error handling, or body structure. Since there is no output schema, the description should explain what to expect, but it does not. It is adequate for a batch creation tool but not complete.

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%, so the description must compensate. It explains resource, action, and body, but action is not in the schema, and it does not explain the expected structure of 'body' for the list or the purpose of 'account'. It does mention parent_id for nested resources and bulk support via ids/parent_ids, but leaves ambiguities.

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 it is for the Bsoft TMS transport module (escrita: cria/atualiza/remove) and specifically that create_lote sends a list to the /lotes endpoint. It also lists all writable resources, distinguishing this batch creation tool from single-operation siblings like bsoft_transporte_write_create.

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 batch creation via the /lotes endpoint and mentions that update/patch/delete require id (though not relevant to this tool). It warns about production impact and notes bulk support with ids/parent_ids. It does not explicitly contrast with single-create tools, but the resource list and endpoint mention give 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?

The description includes a critical warning: 'Altera dados de PRODUÇÃO (o Bsoft não tem homologação)' - which is a significant behavioral disclosure beyond the annotations. The annotations only say readOnlyHint=false, destructiveHint=false, and no other hints. The description also explains that it alters production data, which is a key behavioral trait. It also mentions that it supports bulk operations with ids/parent_ids. This adds valuable context beyond what annotations provide.

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 fairly concise, with a critical warning at the beginning, followed by usage instructions and a resource list. It's front-loaded with the warning about production data, which is important. The resource list is long but necessary. The mention of 'Flattened action: delete' and 'Bulk support' at the end is a bit redundant with the schema, but adds some value. Overall, it's well-structured and not overly verbose.

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 complex with 7 parameters and no output schema. The description covers the key usage patterns (update/patch/delete require id, nested resources require parent_id, bulk support) and the production warning. It lists resources, which is helpful. However, it doesn't explain what the body should contain or any constraints on the resources. It also doesn't explain the 'account' parameter. Given the complexity, the description is reasonably complete for a delete tool, but could be more detailed.

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 description coverage is 0%, meaning the description does not explain the parameters at all. The schema lists 'resource', 'id', 'ids', 'body', 'account', 'parent_id', 'parent_ids', but the description only mentions some of them: resource, action (not a parameter), body, id, parent_id, and ids. It also mentions 'create_lote' but that's not a parameter. The description partially compensates by explaining the usage of id and parent_id, but it doesn't explain 'account' or 'ids' or 'parent_ids' in detail. Since the schema has 0% coverage, the description should compensate more, but it only touches on some parameters. Baseline would be 1 or 2, but it adds some meaning for id and parent_id, so I'll give a 3.

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 this tool handles write operations in Bsoft TMS (create/update/remove), but the tool name ends with '_write_delete' and the flattened action is 'delete', which suggests a specific delete operation, while the description covers a broader write set. The verb is implied by the name and the flattened action. The description lists resources, which is helpful. It distinguishes from siblings by the resource list and the note about production data. However, the description starts with a broad 'cria/atualiza/remove' which is ambiguous and could confuse an agent expecting a delete-specific tool. The flattened action clarifies it, but the mismatch between description and name is a minor issue.

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: 'Passe resource, action e body (JSON)' and states that update/patch/delete require 'id', nested resources require 'parent_id', and create_lote sends a list. However, it doesn't explicitly say when to use this tool vs the other write tools (create, patch, update) except by the action parameter. The flattened action is delete, which implies this tool is for deletion, but the description says it covers all write operations. There is no explicit 'when not to use' or alternatives mentioned. The sibling tools are similar, so this could be ambiguous.

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 claims 'cria/atualiza/remove' while annotations declare destructiveHint=false, which contradicts the non-destructive hint. Although the production-data warning is valuable, the rule requires a score of 1 when the description contradicts 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 structured with a warning, usage notes, and a resource list, and it is not excessive in length. However, the broad 'cria/atualiza/remove' phrasing and the 'Flattened action' meta-note add confusion that reduces the value of the overall structure.

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?

It includes a production-data warning and enumerates writable resources, but it does not explain the account parameter, which resources are nested, what a patch body should contain, or return/error behavior. The missing action parameter and patch-vs-update ambiguity leave the description incomplete for safe invocation.

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 adds meaning to body, id, parent_id, and bulk ids, but it instructs the agent to pass an 'action' parameter that does not exist in the input schema. With 0% schema coverage, this wrong instruction actively harms parameter understanding and outweighs the partial explanations.

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 identifies the domain (Bsoft TMS transport) and lists writable resources, and it ends with 'Flattened action: patch'. However, the opening line says 'cria/atualiza/remove', which obscures the actual patch-specific purpose and does little to distinguish this from the sibling update/delete 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?

It provides useful conditions: update/patch/delete require id, nested resources require parent_id, and bulk mode accepts ids/parent_ids. It does not explicitly say when to choose patch over update/delete, so the when-to-use guidance is implied 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?

The description states the tool can 'remove' data and mentions 'delete', but the annotations declare destructiveHint=false. Because the description also warns that it alters PRODUCTION data, the safety information is useful, but the contradiction with the destructiveHint annotation is severe and forces a score of 1.

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 production warning is front-loaded and the prose is reasonably compact. However, the long resource list duplicates the schema enum verbatim, and the sentence about 'action' adds confusion, so the description is not as concise or focused as it could be.

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 production-mutating tool with 7 parameters and no output schema, the description omits return-value/response behavior, authentication or account prerequisites, and does not clarify the missing 'action' parameter. It does include a strong production warning and nested/bulk guidance, but important context for correct invocation is still absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining that body is JSON, update/patch/delete require id, nested resources need parent_id, and bulk accepts ids/parent_ids. However, it introduces an 'action' parameter that is absent from the input schema and leaves 'account' and exact body shape 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 identifies the tool as Bsoft TMS transport writing operations and lists the writable resources, but it says 'cria/atualiza/remove' (create/update/remove) rather than focusing on the update action implied by the tool name. The '[Flattened action: update]' note helps, yet the text still does not clearly differentiate this tool from sibling create/delete/patch tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives operational constraints: update/patch/delete require id, nested resources require parent_id, and bulk mode uses ids/parent_ids. However, it does not explicitly say when to use this update tool instead of write_create, write_patch, or write_delete, and the reference to a generic action parameter makes the guidance somewhat ambiguous.

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 establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations by explaining what happens in different states: when all providers are connected versus when credentials are missing, including the returned fields and URL 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 the primary action front-loaded and supporting state-dependent details packed efficiently. Every sentence adds substantive information about behavior or return values; there is no redundant filler.

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 0-parameter, no-output-schema tool, the description adequately covers the key return scenarios: fully connected state and missing-credentials state. It provides the agent with enough information to interpret the response and decide whether to call authenticate or another 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?

The tool has zero parameters, so the input schema carries no parameter semantics to explain. The description appropriately focuses on return behavior instead, which is the relevant semantic content for an agent invoking this 0-parameter tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Returns connection status and URLs.' It clearly identifies the tool's function as a status/connectivity check, and the state-dependent details ('authenticated:true', 'empty pending[]', 'connect_url') further distinguish it from sibling tools like authenticate, which would initiate rather than report 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 usage: call this to check connection status and retrieve connection URLs when providers are not connected. However, it does not explicitly name alternatives or state when not to use it (e.g., 'use authenticate to initiate authentication'), so there is no direct comparison with sibling tools.

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 providing readOnlyHint=false, destructiveHint=false, and openWorldHint=true, the description adds context on mutations (e.g., invoke runs one-off without installing, returns connect/checkout links, install makes permanent). It also notes permission requirements for writes. It does not describe cancellation partial-success behavior, but given the annotations, this is sufficient context.

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 with many clauses and run-on sentences. It covers a lot of information but lacks structuring (no bullet points, no clear sections). It front-loads the core purpose but then meanders into prompt library details. It could be split into sections for main actions vs prompt library to improve 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 large scope (14 actions, prompt library, permissions, install vs invoke distinction), the description covers most essential behavior. It explains the core flow, one-off vs permanent install, auth/payment handling, and permission requirements. It does not detail return values (no output schema), but the description explains what invoke returns (connect/checkout links, retry). It could mention error cases or more paramet details, but it's fairly complete for the size.

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 carries the burden. It explains action parameter semantics by describing each action (search, describe, invoke, etc.) and the flow connecting them, which indirectly clarifies parameters like mcp_id, tool_id, arguments. However, it does not explain many parameters (e.g., limit, immediate, tier_slug, prompt_* fields, cancel_reason) in detail beyond their names. Might be a 2.5 but rounded to 3.

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: 'the in-platform catalog of every MCP/tool, AND the way to run them.' It enumerates the actions and explains the core flow (search → describe → invoke). However, it is overly broad and covers many distinct actions (search, describe, install, invoke, subscribe, request_mcp, prompt library), making it less focused. It does not clearly distinguish from siblings like bsoft_* tools because it's a meta-tool for the marketplace, not a domain-specific tool.

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 explicit usage guidance: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT...' and explains when to use search vs describe vs list_tools. Also notes permission requirements for writes. However, it does not explicitly say when NOT to use this tool or mention alternatives for the prompt library 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 indicate readOnlyHint=false and destructiveHint=false, but no annotation covers side effects. The description clarifies it sends feedback and includes conversation for reproduction, which adds context. 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?

Description is concise and front-loaded, but it is a single sentence and could be slightly more structured, e.g., clarifying the context parameter.

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 3 params with 0% schema coverage and no output schema, description is minimal. It provides some guidance on 'message' and 'conversation' but lacks full coverage of the 'context' parameter and any expected behavior or return.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.