Server Quality Checklist

Tool Scores

• call_entity_toolD
  1.9/5.0
  Behavior2/5

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

  With no annotations provided, the description must carry the full behavioral burden. The term 'proxy direto' suggests transparent forwarding to another MCP tool, but nothing is said about side effects, error handling, validation of arguments, or whether the call is synchronous. The description provides minimal behavioral context beyond the word 'proxy'.

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

  Conciseness2/5

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

  The description is a single vague sentence. It is technically concise, but it is under-specified rather than efficiently detailed. There is room for several clarifying statements about tool invocation and arguments without becoming verbose.

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

  Completeness1/5

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

  For a generic dynamic proxy with 3 parameters, no output schema, and zero annotations, this description is completely inadequate. The agent cannot determine valid entityId or tool values, expected argument shapes, returned data, or failure modes. It is not possible to invoke this tool reliably based on the provided definition.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description needs to compensate, but it does not mention any of the three parameters. While the parameter names (entityId, tool, arguments) are somewhat self-explanatory, the 'tool' parameter is ambiguous and no guidance is given on how to structure arguments for dynamically invoked tools. The description adds no semantic value beyond schema-visible names.

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

  Purpose2/5

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

  The description 'Proxy direto para uma MCP tool de uma entidade registrada' is essentially a restatement of the name and title: it says the tool directly proxies to an MCP tool of a registered entity. It adds only the words 'direct' and 'registered' without clarifying what calling an entity tool actually does, what an entity tool is, or how this differs from sibling tools like list_entities or orchestrate.

  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?

  There is no guidance on when to use this tool versus alternatives. The description does not state selection criteria, mention the need for a pre-registered entity, or note when call_entity_tool would be preferable to plan_request or orchestrate. This is a clear absence of usage guidance.

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

• get_entityB
  3.1/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. It discloses that the result is the 'registro completo' (full record), which adds some return-value context, but it does not mention error behavior, authentication needs, or explicitly confirm there are no side effects. 'Devolve' does imply a read operation, so it is minimally transparent.

  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 direct sentence with no filler, front-loaded with the action verb and resource. Every word earns its place, making it appropriately concise for such a simple tool.

  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 one-parameter retrieval tool, the description plus schema is mostly sufficient: the agent knows the tool returns a full entity record and that an ID is required. However, with no output schema and no usage guidance versus siblings, the description is only minimally complete and lacks edge-case context.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not compensate by explaining the 'id' parameter or how it relates to the returned entity. The property name 'id' is self-explanatory, but the description adds no semantic value beyond the schema's field name and type.

  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 states a clear retrieval action ('Devolve') and a specific resource ('o registro completo de uma entidade'), making it evident this is a read operation for a single entity. It does not explicitly differentiate itself from list_entities by mentioning lookup by ID, so it stops short of a 5.

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

  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 instead of siblings like list_entities, update_entity, or remove_entity. There are no conditions, exclusions, or alternative recommendations, leaving the agent to infer usage from the name and schema alone.

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

• remove_entityB
  3.1/5.0
  Behavior2/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 only says 'Remove', implying deletion, but does not disclose whether the removal is permanent, whether it has side effects, whether missing IDs cause errors, or whether confirmation is needed.

  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 short sentence with no filler words. The core action and object are front-loaded, making it easy to parse quickly.

  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?

  For a destructive operation with no annotations and no output schema, the description is too thin. It does not explain irreversibility, error behavior, required existence of the entity, or what happens after removal. An agent cannot fully predict the tool's effects from this definition alone.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not mention the 'id' parameter at all. The meaning of 'id' as the entity identifier is implied by the tool name, but the description adds no explicit parameter semantics beyond what the property name already suggests.

  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 ('Remove') and a specific resource ('entidade do registro'), clearly identifying a deletion operation. This distinguishes it from sibling tools like get_entity, update_entity, and register_entity.

  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?

  No guidance is given about when to use this tool versus alternatives. There are no stated preconditions, context cues, or comparisons to sibling tools like update_entity or register_entity. Usage is only implied by the name and basic description.

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

• register_entityA
  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 carries the behavioral transparency burden. It adds useful context about tags defining when the orchestrator triggers the entity and about kind 'search' tools being autonomously callable. It does not disclose side effects, overwrite behavior, permissions, or expected response.

  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?

  Two sentences, each purposeful: the first states the core operation, and the second explains key configuration semantics. There is no redundancy or padding.

  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?

  With 10 parameters, no annotations, and no output schema, a two-sentence description is insufficient for correct invocation. It omits how to construct the tools array, what enabled and args mean, whether an existing id is replaced, and what a successful registration returns.

  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?

  Schema description coverage is only 50%, so the description must compensate for undocumented parameters. It clarifies the role of tags and search-kind tools beyond the schema, but it does not help with undocumented fields such as args, enabled, or description.

  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 the action: 'Adiciona uma entidade à cidade' (adds an entity to the city), with a specific resource and scope. It does not explicitly contrast with update_entity or other siblings, so it stops short of a 5.

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

  Usage Guidelines4/5

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

  The description provides a clear usage context: use this tool to add an entity to the city. However, it does not mention when not to use it or point to update_entity as the alternative for modifying an existing entity, so exclusions and alternative routing are missing.

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

• update_entityA
  3.7/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the burden of behavioral disclosure. It does disclose the key non-obvious behavior of a 'merge raso' (shallow merge), which tells the agent that omitted existing fields are preserved. However, it says nothing about failure behavior when the entity is missing, side effects, or the return value, leaving notable gaps for a mutation without 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.

  Conciseness5/5

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

  The description is a single compact sentence with no filler, and the valuable 'merge raso' behavioral note is tucked into a parenthetical rather than cluttering the main clause. Every word contributes, so it is appropriately concise.

  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?

  With no output schema and no annotations, an agent is left without information about the return value or error semantics, though the core operation is captured. For a two-parameter update utility the description is adequate but incomplete around edge cases, making it a minimum-viable definition.

  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 describes the patch parameter as 'campos a sobrescrever; id é ignorado', which covers half of the parameters, but the id parameter has no schema description. The tool description itself adds no parameter-level meaning beyond the operation, so it does not compensate for the id gap; nevertheless, both parameters' roles are reasonably inferable from the operation 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 opens with the verb 'Atualiza' (updates) and specifies the resource as 'campos de uma entidade já registrada' (fields of an already registered entity), clearly distinguishing the operation from sibling tools like register_entity, get_entity, and remove_entity. The parenthetical 'merge raso' adds a precise scoping detail that further identifies what the tool does.

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

  Usage Guidelines3/5

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

  The phrase 'já registrada' implies the entity must already exist, so an agent can infer this is not for creation, but the description never explicitly states when to prefer update_entity over register_entity or other siblings. No exclusions or alternative tools are named, leaving the usage context implicit.

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

• list_entitiesA
  4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. The verb 'Lista' makes the read-only intent reasonably clear, but the description does not disclose behavior such as whether the result includes disabled entities, ordering, pagination, or any scope beyond 'na cidade'. It is adequate but not richly transparent.

  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 short sentence with no filler or redundant wording. It is front-loaded and immediately communicates the action and target resource.

  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 low-complexity listing tool, the description is largely complete: it identifies what is listed and the scope. No output schema exists, but the verb 'Lista' sufficiently implies a list return. The only minor gap is the lack of elaboration on the enabledOnly parameter's effect.

  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 has 100% coverage for the single parameter 'enabledOnly', including a default value, but the description does not add any explanation of what the parameter controls. The baseline of 3 applies because the schema already documents the parameter, though the description could have clarified the enabled-only filtering behavior.

  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 ('Lista') and resource ('entidades registradas na cidade'), clearly identifying the tool's function as listing registered entities. It is immediately distinguishable from siblings like get_entity (single entity), register_entity, update_entity, and remove_entity.

  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 clearly implies the tool is for retrieving a collection of entities within a city, which is a distinct use case from the sibling tools. It does not explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it for listing scenarios.

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

• orchestrateA
  4/5.0
  Behavior4/5

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

  No annotations are present, and the description takes on the burden by explicitly disclosing parallel execution, tag-based entity selection, constraint handling, and the return shape (per entity plus combinations). It does not discuss failure handling or side effects of the invoked tools, but the core runtime behavior is transparent.

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

  Conciseness4/5

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

  One dense sentence communicates all core behavior with no filler and is front-loaded with the main action. It could be split for readability, but it is appropriately sized.

  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 description includes return behavior and mentions constraints, and the schema covers inputs, which is enough for basic invocation. It leaves open details such as how constraints are expressed in the request, error behavior, and the exact result structure, and there is no output schema to fill those gaps.

  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?

  Schema description coverage is 100%, so request and limit are already documented with examples and defaults. The description adds little at the parameter level beyond the general natural-language context, so the schema 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 opens with a specific verb and resource ('Recebe um pedido em linguagem natural') and spells out a distinctive orchestration flow: tag-based entity selection, parallel MCP tool calls, constraint application, and result aggregation. This clearly separates it from direct entity tools like get_entity/update_entity and from plan_request.

  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 defines its input as a natural-language request and states that it orchestrates multiple entities and constraints, so the intended use is evident for multi-entity requests. It does not explicitly contrast itself with siblings such as call_entity_tool or plan_request, but the context is clear enough.

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

• plan_requestA
  4.1/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It explicitly discloses the key behavioral trait — nothing is executed — and describes the output content (tags, restrictions, tool calls, arguments). This gives an agent an accurate safety and behavior model, though it does not discuss limit semantics or response format details.

  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?

  Single sentence, front-loaded with the core safety behavior, and every part of the sentence adds meaning. It is compact without losing important 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 planning/preview tool, the description explains the non-execution behavior and the main output components well. It is incomplete only because the limit parameter is left undefined and no explicit alternative (orchestrate) is named for execution.

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

  Parameters2/5

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

  Schema coverage is only 50%: request is documented, but limit has no description in the schema and the tool description never mentions it. An agent cannot determine what limit limits (e.g., number of tool calls, number of tags, or plan entries), which is a significant gap.

  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: it shows, without executing, what the Core understood from a request — detected tags, extracted restrictions, and which entity tools would be called with translated arguments. This distinguishes it from execution-oriented siblings like orchestrate and call_entity_tool.

  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 phrase 'sem executar nada' establishes a clear preview/dry-run context, so an agent can infer this tool should be used before executing a request. It does not explicitly name alternatives or say when not to use it, but the behavior is clear enough.

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

• list_city_toolsA
  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 behavioral burden. It discloses that the tool connects to MCP servers, performs a live check ('agora'), and returns currently exposed tools. It does not cover failure modes, but for a read-only listing operation this is a meaningful and sufficient disclosure.

  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?

  Two sentences with no filler: the first explains what the tool does, and the second gives a concrete use case. It is front-loaded and every word earns its place.

  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 tool with one optional parameter, no output schema, and no annotations, the description provides enough context: the action, result, and a real-world scenario. It could mention behavior on unreachable servers, but that is a minor gap for this simple live-listing tool.

  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% description coverage for the only parameter (entityId), including the 'omit to query all active' guidance. The tool description adds no extra parameter detail, so the baseline score 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 states a specific action ('Conecta nos servidores MCP das entidades') and a clear result ('devolve as tools que elas realmente expõem agora'). This distinguishes it from sibling tools like list_entities and call_entity_tool by focusing on live tool introspection.

  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 explicitly gives a use case: 'Útil para conferir se o registro está de acordo com a realidade', which tells the agent when this tool is appropriate. It does not name alternatives or exclusions, but the context is clear enough for a simple listing operation.

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