Server Quality Checklist

Tool Scores

• listar_vendasC
  2.9/5.0
  Behavior2/5

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

  With no annotations to lean on, the description must disclose behavioral traits itself. It only says 'Lista' (lists) and mentions filtering, implying a read-only list operation, but it does not mention pagination behavior, default status, return format, or any side effects. This is inadequate for a tool with 8 parameters and no output schema.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that efficiently conveys the core purpose and key filtering capabilities. It contains no fluff or redundancy, making it appropriately concise.

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

  Completeness2/5

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

  Given the tool's complexity (8 params, no annotations, no output schema), the description is too sparse. It omits crucial contextual details such as pagination mechanics (offset/limit), default status 'paid', and what the returned list contains. This leaves the agent under-informed for correct invocation and output interpretation.

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

  Parameters3/5

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

  The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds minimal value by summarizing filter types (status, date, search text), but this repeats what is already in the schema and does not explain parameter syntax or edge cases beyond the schema.

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

  Purpose4/5

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

  The description clearly states it lists sales/orders and supports filtering, which is a specific verb+resource. However, it does not explicitly differentiate itself from sibling tools like 'vendas_para_enviar' or 'detalhes_venda', so it loses a point for missing sibling differentiation.

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

  Usage Guidelines2/5

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

  The description gives no guidance on when to use this tool versus alternatives. It only mentions filtering capabilities, leaving the agent to infer usage from sibling names. No exclusions or alternative recommendations are provided, which is a significant gap given the multiple related tools.

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

• detalhes_vendaA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description must disclose behavior on its own. It only says it retrieves details; it does not mention whether the response is a full object, any pagination, permissions, or side effects. Minimal behavioral context.

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

  Conciseness5/5

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

  One short sentence that gets straight to the point; no filler or redundant information. It is front-loaded and easy to parse.

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

  Completeness3/5

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

  For a simple one-parameter read tool, the description gives the core purpose, but the absence of an output schema and any mention of response structure leaves some ambiguity about what 'detalhes completos' includes. Adequate but not rich.

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

  Parameters3/5

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

  The schema already fully describes `order_id` as 'ID do pedido'. The description's phrase 'pelo ID' adds no new information about parameter format or constraints. With 100% schema coverage, the baseline of 3 applies.

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

  Purpose5/5

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

  The description uses the verb 'Obtém' and specifies the resource 'detalhes completos de uma venda/pedido' and lookup method 'pelo ID'. This clearly distinguishes it from siblings like 'detalhes_envio' which focus on shipping details.

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

  Usage Guidelines3/5

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

  The description implies the tool is for fetching a single sale's details by ID, but it does not explicitly state when to prefer it over siblings like 'listar_vendas'. Usage guidance is only implicit, not explicit.

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

• historico_envioA
  3.5/5.0
  Behavior3/5

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

  No annotations are provided, so the description is the sole behavioral source. The verb 'Obtém' implies a read-only operation, but additional context such as ordering of history, error conditions, or access requirements is not disclosed. It does not contradict annotations (none exist), but adds minimal transparency beyond the core action.

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

  Conciseness5/5

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

  The description is a single, concise sentence in Portuguese with no superfluous words. It is appropriately sized for the tool's simplicity and front-loads the main action efficiently.

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

  Completeness3/5

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

  The tool has one parameter and no output schema. The description states the action but does not describe the expected return structure (e.g., array of statuses, timestamps) or ordering. This leaves gaps for an agent, but for a simple history retrieval it is minimally adequate.

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

  Parameters3/5

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

  The input schema fully covers the single parameter 'shipment_id' with a clear description ('ID do envio'). With 100% schema coverage, the baseline of 3 applies, and the tool description adds no extra parameter semantics but does not need to.

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

  Purpose5/5

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

  The description uses a specific verb ('Obtém' - gets) and a specific resource ('histórico de status de um envio' - status history of a shipment). It clearly distinguishes from the sibling tool 'detalhes_envio', which likely provides current details rather than historical statuses.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus siblings like 'detalhes_envio' or 'listar_vendas'. There are no preconditions, alternative conditions, or exclusions mentioned, leaving the agent without context for tool selection.

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

• detalhes_envioA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the burden of behavioral disclosure. The verb 'Obtém' (gets) indicates a read operation, but the description does not explicitly state that it has no side effects or mention any permissions or error conditions. It does disclose the content of the response (address, tracking, status), which adds transparency, but it is not as rich as it could be.

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

  Conciseness5/5

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

  The description is a single, concise sentence that includes the verb, resource, and key return elements. Every word adds value, and it is properly front-loaded with the main action.

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

  Completeness4/5

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

  For a simple get-by-id tool with one parameter and no output schema, the description is fairly complete. It covers what the tool does and what the response includes. However, it lacks details about potential errors (e.g., not found) or any special cases, and with no annotations, it could be slightly more explicit about the non-mutating nature.

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

  Parameters3/5

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

  The input schema has 100% coverage for the single parameter 'shipment_id' with a description 'ID do envio (shipment).' The tool description also mentions 'pelo ID', but adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate given the high schema coverage.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Obtém os detalhes completos de um envio (shipment) pelo ID' (Gets complete shipment details by ID). It specifies the resource (shipment) and the exact information returned (address, tracking, status), which differentiates it from siblings like 'detalhes_venda' (sale details) and 'historico_envio' (shipping history).

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

  Usage Guidelines2/5

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

  The description does not provide any guidance on when to use this tool versus alternatives. While the name and description imply it is for retrieving a single shipment's details by ID, there is no explicit context about when to prefer it over sibling tools like 'historico_envio' or 'detalhes_venda'.

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

• gerar_etiquetasA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the output format (PDF URL or ZPL content), but it does not mention side effects (e.g., whether it marks shipments as labeled), required permissions, or error behavior. This partial disclosure is helpful but leaves gaps.

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

  Conciseness5/5

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

  The description is a single sentence that efficiently states the action, the target (shipments), and the return type. It is front-loaded with the primary verb and contains no filler or redundant information.

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

  Completeness4/5

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

  For a simple two-parameter tool, the description adequately covers the primary purpose and output format. It lacks explicit notes on error handling or prerequisites, but given the straightforward nature and complete schema, it is nearly complete. The absence of annotations and output schema is mitigated by the clear output description.

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

  Parameters3/5

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

  The input schema already provides complete descriptions for both parameters, including default values and constraints (e.g., max 50 shipment IDs). The tool description does not add any additional meaning beyond what the schema conveys, so the baseline 3 for high schema coverage applies.

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

  Purpose5/5

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

  The description uses a specific verb 'Gera' (generates) and a specific resource 'etiquetas de envio' (shipping labels), making the tool's function immediately obvious. It also states the output format (PDF URL or ZPL content), which clearly distinguishes it from sibling tools like listing sales or viewing shipment details.

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

  Usage Guidelines3/5

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

  The description implies this tool is used when shipping labels are needed for one or more shipments, but it does not explicitly state when to use it over alternatives like 'salvar_pdf' or 'detalhes_envio'. No exclusions or alternative tools are mentioned, so usage guidance is only implied.

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

• salvar_pdfA
  3.8/5.0
  Behavior2/5

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

  With no annotations, the description is the sole source of behavioral disclosure. It states the primary conversion and save action but fails to mention important behaviors such as whether existing files are overwritten, whether the base64 is validated, or what happens on failure. This is a significant gap for a file-writing operation.

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

  Conciseness5/5

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

  The description is two concise sentences, with the main action front-loaded and the practical use case following. No wasteful words or redundancy.

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

  Completeness4/5

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

  For a simple two-parameter utility with no output schema, the description covers the core functionality and provides a relevant use case linking to a sibling tool. It lacks some edge-case information, but overall it is sufficient for an agent to select and invoke the tool correctly.

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

  Parameters3/5

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

  Both parameters are fully described in the schema with 100% coverage, so the baseline is 3. The description echoes the schema terms but adds no new semantic detail beyond suggesting the base64 originates from label generation.

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

  Purpose5/5

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

  The description uses specific verbs ('Converte', 'salva') and identifies the resource (PDF file) and destination path. It clearly distinguishes itself from siblings by referencing the label generation tool (gerar_etiquetas), making its purpose unambiguous.

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

  Usage Guidelines4/5

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

  It provides clear context by stating the tool is useful for saving labels generated by gerar_etiquetas, which tells the agent when to invoke it. It does not explicitly exclude alternatives, but the sibling list shows no other saving tool, so this suffices.

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

• vendas_para_enviarA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses that it checks the status of each shipment and only returns those with 'ready_to_ship', and that it filters for paid sales. This is behavior beyond the schema, showing the internal logic. It does not mention side effects (none implied) or return format, but the behavior is clearly described.

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

  Conciseness5/5

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

  The description is two sentences long, front-loaded with the main purpose, then a behavioral detail about status checking. Every sentence adds value, and there is no unnecessary verbosity.

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

  Completeness4/5

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

  For a simple listing tool with no output schema, the description adequately covers what is returned (paid, unshipped, ready-to-ship sales) and the optional filter. It is missing explicit mention of ordering or pagination, but these are not critical for this type of operation.

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

  Parameters3/5

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

  The input schema already provides full descriptions for both parameters (limit and apenas_hoje), so the baseline is 3. The description's mention of optional filtering by today's deadline repeats schema information without adding new semantics.

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

  Purpose5/5

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

  The description clearly states the tool lists paid sales that are not yet shipped and are 'ready_to_ship', with an optional filter for today's deadline. This specific verb+resource+scope distinguishes it from siblings like listar_vendas (likely all sales) and detalhes_envio (individual shipment info).

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

  Usage Guidelines4/5

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

  The description provides a clear context for use (identifying orders ready for dispatch) and mentions an optional filter for today's deadline, which implies when this tool is appropriate. It does not explicitly mention when not to use it or point to alternatives, but the sibling context is available.

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