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

There are no annotations, and the description does not disclose side effects, idempotency, required permissions, or behavior when the user is already in the scope. The description only states the basic operation without additional behavioral details.

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 clear sentence, front-loads the main action, and includes a concise parenthetical for a special case. It is appropriately sized 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 description does not mention return values, potential errors, whether the user must exist in the system, or what happens on duplicate assignment. The unexplained 'extra' parameter also contributes to incompleteness. Given the lack of annotations and output schema, more context is needed for an agent to fully understand the operation.

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

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

The input schema already provides descriptions for 'username' and 'idScope', including the special meaning of idScope 0. The tool description repeats this idScope guidance but adds no further parameter semantics. The 'extra' parameter remains unexplained, so there is no additional value beyond 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 clearly states the action: 'Agrega un usuario existente a un scope' (Adds an existing user to a scope). It specifies the verb and the resources involved, and the parenthetical about idScope 0 clarifies an important input variation. This distinguishes it from siblings like remove_user_from_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?

The description does not explicitly state when to use this tool over alternative tools such as assign_user_roles or remove_user_from_scope. The usage is implied by the name and description but lacks explicit when-to-use or when-not-to-use guidance.

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

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

No annotations are provided, and the description only states the action without revealing side effects, permissions, idempotency, or whether it modifies data. The description carries the full burden but fails to disclose these behavioral aspects.

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

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

The description is a single concise sentence with no fluff, which is structurally sound. However, it lacks necessary detail to be truly useful, and its brevity contributes to the ambiguity rather than resolving it.

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 simple parameter set, the description still feels incomplete due to the invitation/user mismatch, lack of output information, and absence of any contextual hints about typical use cases. It does not provide enough context for an agent to confidently invoke it.

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 descriptions for 'id' and 'roles' are present, but the tool description adds no further clarification. Moreover, the ambiguity between the tool name (invitation) and the parameter description (user ID) creates confusion about what 'id' actually represents, undermining semantic clarity.

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

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

The description states a clear action ('assigns roles to a user') but the tool name 'assign_invitation_roles' suggests it applies to invitations, not users. This mismatch makes the actual purpose ambiguous, especially given the sibling tool 'assign_user_roles' which likely handles user role assignment directly.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'assign_user_roles', 'list_invitation_roles', or other role-related tools. The description offers no conditions or context to help an agent choose correctly.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal a key behavior—that the assignment replaces the current one—which is valuable. However, it omits other behavioral details such as whether the operation is atomic, what happens to existing permissions not listed, whether it requires specific permissions, or how errors are handled. The replacement note is helpful but insufficient for a mutation tool with no annotation support.

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 front-loads the primary action and immediately states the most important behavioral nuance (replacement). There is zero wasted wording, and the sentence is easy to parse. It achieves maximum efficiency for the information it conveys.

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 relatively simple (2 parameters, no output schema, no nested objects), and the schema fully documents parameters. However, the lack of usage guidelines and limited behavioral disclosure (beyond replacement) leaves gaps. For a mutation tool with no annotations, an agent might need to know whether the operation is reversible, whether it is idempotent, or if there are side effects on related entities. The description covers the core purpose but not the full context needed for confident 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 input schema already provides 100% description coverage for both parameters: 'id' (ID del rol) and 'permissions' (IDs de los permisos a asignar). The description adds no additional meaning beyond the schema; it does not clarify formats, constraints, or relationships between parameters. Since the schema covers everything, the baseline of 3 is appropriate, and the description does not elevate 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 the action ('Asigna permisos a un rol') and specifies the resource (permissions to a role). It also includes a critical scoping detail—'(reemplaza la asignación actual)'—which distinguishes it from other permission-related tools like list_role_permissions or update_role. The verb and resource are specific, and the replacement note makes the intent unambiguous.

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

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

The description implies usage through the 'reemplaza la asignación actual' note, suggesting this tool is for setting a role's full permission set rather than incrementally adding. However, it does not explicitly state when to use this tool versus alternatives like update_role or assign_user_roles, nor does it mention any exclusions or prerequisites. No alternative tools are named, leaving the agent to infer context from the sibling list.

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 an important behavioral aspect: it replaces the current role assignment. However, it does not mention other side effects (e.g., removal of existing roles, potential authorization requirements, or impact on user access). The absence of annotations increases the need for more disclosure, but the provided replacement note gives some 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 a single, concise sentence that communicates the core action and the key behavior (replacement). There is no redundant or extraneous information, making it highly efficient and focused.

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 assignment action, the description is sufficiently complete: it explains the primary operation and the replacement behavior. There is no output schema to document, and error conditions or permission requirements are not explicitly stated, but these are not strictly necessary for basic usage. The context parameter remains underdocumented, which slightly reduces 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 schema includes descriptions for all three parameters: id (user ID), roles (array of role IDs), and context (tenant context). While this covers the basics, the 'context' description is vague and does not clarify its purpose or allowed values, leaving some ambiguity in how to use the parameter.

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

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

The description clearly states the action ('asigna roles a un usuario') and the specific resource (user and roles), and adds a crucial detail that it replaces the current role assignment. It does not explicitly differentiate from sibling tools, but the verb and object are specific enough to convey 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 guidance is provided on when to use this tool versus alternatives like assign_role_permissions or assign_invitation_roles. The description does not mention any conditions, prerequisites, or edge cases, leaving the agent to infer usage from the name alone.

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 no annotations, the description carries the burden. It discloses the action and the requirement for the current password, indicating that the current password will be verified. It does not mention potential side effects like session invalidation, but the core behavior is transparent enough for a simple password change.

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 clearly conveys the action and key requirement. It is well-structured and easy to understand 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?

For a simple tool with no output schema, the description is complete. It specifies what the tool does and what is required to use it, providing all necessary context for an agent to invoke it 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?

The input schema already provides clear descriptions for both parameters (newPassword and currentPassword) with 100% coverage. The overall description adds context about the authenticated user but does not add significant meaning beyond the schema's parameter descriptions.

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: changing the password of the authenticated user. It is specific and distinguishes itself from other user-related tools like update_user by focusing on the self-service password change.

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 the requirement of the current password, which provides some usage guidance. However, it does not explicitly explain when to use this tool versus alternatives such as update_user for admin-managed password changes, leaving some 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 discloses important behavioral details: idScope is forced to the token's tenant and author is taken from the token. No annotations are present, so this information carries the full burden, but other behaviors (e.g., email sending, validation) are not mentioned.

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, consisting of two sentences. It is front-loaded with the primary purpose and then adds behavioral context. No unnecessary 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?

While the description gives the core purpose and a key behavioral constraint, it does not explain the meaning of the 'meta' and 'extra' nested objects, nor does it specify any validation or side effects. It also lacks guidance on the relationship with sibling tools, so it is not fully complete for an agent to use confidently.

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 about 80% (4 of 5 parameters have descriptions). The tool description does not add further meaning to the individual parameters; it only explains token-derived fields that are not part of the parameter list. Since coverage is high, baseline score is 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 creates a user invitation with a specific verb ('Crea') and resource ('invitación de usuario'). It also clarifies that idScope is forced and author taken from token, which distinguishes its behavior from other user-related 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 does not explicitly state when to use this tool versus alternatives like create_user or list_invitations. It implies usage for creating invitations, but lacks guidance on conditions or comparisons with 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?

The description discloses important non-obvious behavior: the name field is persisted while any provided clientId is ignored because the API generates its own. Since no annotations are provided, this helps fill the behavioral transparency gap, though it does not mention return values or error conditions.

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, consisting of two focused sentences with no redundant information. It efficiently conveys the essential creation behavior and special field handling.

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 create operation, the description provides enough context about what happens, but it does not describe the response format, required permissions, or failure scenarios. Given there is no output schema or annotations, this leaves some operational 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?

The description clarifies tenant default behavior and clientId handling, and the schema already describes several parameters. However, parameters such as meta, grants, scopes, type, and extra are not explained beyond their raw JSON structure, so the description does not fully compensate for the schema's partial coverage.

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

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

The description clearly states the tool's action: 'Crea un cliente OAuth en el tenant indicado (default: tenant activo).' It uses a specific verb and resource, and the sibling tools include update/delete/list OAuth clients, so the creation purpose is unambiguous.

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

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

The description gives no explicit guidance on when to choose this tool over related tools such as list_oauth_clients, update_oauth_client, or delete_oauth_client. The intended usage is only inferred from the tool name and creation verb.

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?

There are no annotations, so the description carries the full burden. It only states that it creates an OAuth scope, which implies mutation, but does not disclose side effects, permissions required, reversibility, or behavior when the scope already exists.

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

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

The description is a single sentence with no unnecessary words, achieving high conciseness. However, it is under-specified, so while concise, it sacrifices completeness.

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 annotations, no output schema, and a minimal description, the tool is severely incomplete. An agent cannot determine the effects, requirements, or return value, making it difficult to call 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?

The input schema only describes the 'name' parameter (33% coverage). The description does not add any additional meaning to 'extra' or 'description', and does not clarify the expected format or semantics beyond 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 states a specific action (creates) and resource (OAuth scope) and mentions the tenant context, making the purpose clear. However, it does not explicitly differentiate from sibling tools like create_scope or update_oauth_scope, so it lacks explicit sibling differentiation.

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 guidance on when to use this tool versus alternatives such as create_scope or update_oauth_scope. It does not mention any prerequisites or conditions for use.

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

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

No annotations are provided, so the description carries the burden. It discloses the creation side effect and the important scoping behavior (idScope forced to token tenant), but it does not mention authentication requirements, duplicate handling, or error 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 short, direct, and front-loaded with the purpose. The additional note about idScope is concise and provides meaningful behavioral context without unnecessary detail.

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

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

The description covers the core creation action and the idScope override, but it lacks guidance about the expected result, the meaning of extra and description, and any constraints beyond the idScope behavior. Given the tool's moderate complexity, this is adequate 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 descriptions cover only name and idScope. The extra and description parameters are not described in the schema or the tool description, leaving 50% of parameters undocumented and no compensating explanation.

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 'Crea un permiso' (creates a permission), identifying the specific verb and resource. This distinguishes it from sibling tools like update_permission, delete_permission, list_permissions, and import_permissions.

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: use this to create a permission. It does not explicitly mention alternatives or exclusions, such as using import_permissions for bulk creation, but the intent is unambiguous from the title and description.

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?

No annotations are provided, and the description only says 'creates a role' without disclosing side effects, permissions required, failure modes, or return behavior. This leaves the agent uncertain about what happens on success or error.

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, direct sentence with no unnecessary words or redundancy. It is concise and well-structured for a simple create operation.

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 gives only the fundamental purpose. It omits critical context such as parameter details, required fields beyond what the schema shows, return values, or potential constraints (e.g., duplicate names). This incompleteness could lead to incorrect 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 schema has 4 parameters but only 2 are described (idScope and name). The tool description does not add any parameter explanations, so the 'description' and 'extra' parameters remain ambiguous. With only 50% schema coverage, the description fails to compensate for the lack of clarity.

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 creates a role within a scope/tenant, using the specific verb 'Crea' and resource 'rol'. It distinguishes itself from sibling tools like update_role and delete_role, 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.

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

The description provides clear context that this is for creating a role, and the tool name and sibling set make it evident when to use it over update_role or delete_role. However, it does not explicitly mention alternatives or conditions for use, though the context is strong enough.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'creates', implying a mutation, but it does not disclose permissions required, reversibility, side effects on existing data, or the shape of the response. For a creation tool with zero annotation coverage, this is a significant gap.

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, direct sentence with no fluff. It is appropriately sized for the action and front-loads the core purpose. Every word earns its place, so it scores highly on conciseness.

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

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

For a tool with 5 parameters (2 required), nested objects, and no output schema, this description is far from complete. It does not explain what 'extra' and 'settings' are, how they should be structured, what the response looks like, or any constraints. An agent would lack essential context to call this 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?

The input schema has 60% description coverage (name, idScope, settings have descriptions; extra and description do not). The tool description adds no parameter information whatsoever, and it does not clarify the structure of the nested objects (extra and settings) or their purpose. With moderate coverage and no added guidance, the description fails to compensate for the 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 states a specific verb ('Crea' / creates) and a clear resource ('scope/tenant hijo' / child scope/tenant) within another scope. It is unambiguous about the action, but it does not differentiate from sibling tools like create_scope (if any) or save_scope, 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.

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 alternatives such as list_child_scopes, update_scope, or save_scope. It does not mention prerequisites, edge cases, or when not to use it. There is no explicit or implied usage context beyond the basic action.

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 no annotations provided, the description carries the burden of disclosing behavior. It does state the core side effects—creating a user and associating it with a scope—but it does not mention edge cases, potential errors, required permissions, or whether the operation is idempotent.

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 directly communicates the essential action. There is no unnecessary detail or ambiguity in the wording.

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

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

Given the tool's moderate complexity and the absence of an output schema, the description is mostly complete. It clearly explains what the tool does, and the parameter descriptions fill in the remaining details, though it does not mention what the tool returns or any failure modes.

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 input schema already describes all 7 parameters with 100% coverage. The description itself adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: it creates a user and adds that user to the indicated scope. The verb 'crea' and the resource 'usuario' are specific, and the statement distinguishes this from sibling tools like add_user_to_scope, which would handle an existing 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 does not provide any guidance on when to use this tool versus alternatives. It does not mention conditions, prerequisites, or scenarios where create_user is preferable to other user-management 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?

Does not disclose destructive nature beyond verb, no info on irreversibility, permissions, or side effects. Annotations absent, so description carries full burden but fails to 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?

Single concise sentence, front-loaded with action, no redundant words.

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?

Lacks information on return value, error handling, soft vs hard delete, and differentiation from similar operations like rejection. Adequate for trivial tool but incomplete for safe usage.

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 and description both clearly define the 'id' parameter as the invitation ID, leaving no 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?

States the verb 'Elimina', object 'una invitación', and method 'por id'. Distinct from sibling tools like create, list, reject.

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 on when to use delete vs reject_invitation_user or other alternatives. Missing context on prerequisites or consequences.

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?

No hay anotaciones y la descripción no menciona efectos secundarios, irreversibilidad, requisitos de permisos ni comportamiento ante fallos. Solo indica la acción de eliminar, dejando al agente sin información sobre consecuencias.

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?

La descripción es breve y directa, con dos oraciones que comunican la acción y la instrucción clave sin redundancias. La información más importante se presenta de forma concisa.

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?

Para una operación de eliminación, la ausencia de especificación del valor de retorno es aceptable. Sin embargo, no se aclara si el parámetro 'tenant' es opcional u obligatorio, ni se indica qué sucede si el cliente no existe.

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?

La descripción añade valor más allá del esquema al aclarar que 'id' es el identificador interno a usar, y que 'clientId' no es válido para la eliminación. Esto resuelve una posible ambigüedad semántica.

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?

La descripción indica claramente que la acción es eliminar un cliente OAuth. El nombre de la herramienta también es explicativo y no hay ambigüedad sobre la operación.

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?

Se proporciona una guía explícita sobre qué parámetro usar: menciona que el id interno (UUID) es obligatorio y que el clientId no debe utilizarse para esta acción, evitando confusión.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the deletion action but does not mention that it is destructive, irreversible, or requires specific permissions. It also does not describe any side effects or return behavior, leaving the agent with minimal insight beyond the basic action.

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 core action. It is appropriately sized for a simple tool with one parameter, containing no fluff or irrelevant details. It could be slightly more informative, but it is 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?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimally adequate. It tells the agent what the tool does, but it does not specify expected return values, error conditions, or any prerequisites. For a deletion operation, this is a notable gap, but the tool is simple enough that the description is not severely lacking.

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 covers 100% of the parameter (id is described as 'ID del scope'), and the description only repeats the parameter ('por id') without adding any new constraints, format, or semantic nuance. The baseline of 3 applies because the schema already fully documents the parameter, and the description adds no extra 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 a specific action ('Elimina' = deletes), the resource ('scope OAuth'), and the parameter ('por id'). It distinguishes from the generic sibling 'delete_scope' by explicitly naming OAuth, so an agent can differentiate the two tools without ambiguity.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for OAuth scopes specifically versus general scopes, nor does it reference any sibling tools. The agent must infer the context from the name alone.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states that permissions are deleted, but it does not disclose whether deletion is permanent, cascades to children, requires specific permissions, or what happens to associated data. The 'children' mode is ambiguous – it does not clarify if deleting a group deletes its children recursively. This is a significant gap for a destructive 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 a single, concise sentence that front-loads the action and then lists the accepted input forms. There is no extraneous information, and it is efficiently structured for quick parsing.

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 (nested objects, no output schema, no annotations), the description is insufficient. It does not explain the behavior when deleting a group with children, the side effects of deletion, or the expected response. For a destructive operation without annotation coverage, this is a major omission.

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 already provides descriptions for id, ids, and children, covering 75% of parameters. The description adds value by explicitly explaining the semantic difference: id for a single permission, ids for multiple, children for a group. However, the 'extra' parameter remains undocumented in both schema and description. The description offers moderate additional meaning beyond 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 clearly states the action ('Elimina permisos' – delete permissions) and the resource. It also lists the three input modes (id, ids, children), making the tool's scope evident. However, it does not explicitly differentiate from sibling delete tools like delete_role or delete_scope, though the name already does that.

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 provide any guidance on when to use this tool versus alternatives, nor does it explain when to use each parameter mode. It merely says 'Puede recibir' (can receive) without stating conditions or context. No exclusions or alternative recommendations are 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 only states the action without disclosing behavioral details such as irreversibility, required permissions, cascading effects, or error handling. Since annotations are absent, the description carries the full burden but provides minimal 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 a single, concise sentence that directly states the purpose without unnecessary words or repetition. It is well-structured and easily understood.

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 low complexity of the operation (a simple delete with one parameter), the description is mostly complete. It omits potential details like irreversibility or error conditions, but these are not critical for basic usage and the schema provides the necessary parameter 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 schema includes one parameter 'id' with a description, and the tool description explicitly mentions 'por id', aligning with the schema. However, the description adds no additional semantic detail beyond what the schema already provides, so the score is at the baseline for high schema coverage.

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

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

The description clearly states the action ('Elimina'), the resource ('rol'), and the identifier ('por id'), making the purpose unambiguous. It distinguishes this tool from other delete operations in the sibling list by specifying the resource type.

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 usage guidance is provided. The description does not indicate when to use this tool versus alternatives, such as when deleting a role is appropriate or required, or any prerequisites for using it.

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?

There are no annotations, so the description carries the full burden of explaining side effects. It simply says 'deletes a scope by id' without mentioning consequences like cascading deletions, reversibility, or impact on associated data, which is insufficient for a destructive 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 extremely concise, consisting of a single sentence. It avoids unnecessary wording and is easy to parse, though it might be slightly too sparse for a destructive action.

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 lacks essential context such as success/failure behavior, side effects, or relationship to sibling tools. Given no output schema and minimal details, the agent has insufficient information to fully understand the operation's impact.

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 input schema already covers the single parameter 'id' with a clear description 'ID del scope'. The tool description repeats this but adds no extra meaning. Since schema coverage is 100%, the baseline score of 3 is appropriate.

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

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

The description clearly states a delete operation on a scope by id, using the verb 'Elimina' and resource 'scope'. However, it does not differentiate from the sibling tool 'delete_scope_own', so ambiguity remains about the exact scope of the operation.

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 alternatives such as 'delete_scope_own' or other deletion tools. The description gives no context for selection, leaving the agent to infer suitability.

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 no annotations, the description carries the full burden. It states the deletion of an own scope and adds that force is only for owners, but does not clarify deletion behavior (e.g., soft vs. permanent), error handling, or side effects. A destructive action needs more 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?

The description is a single concise sentence that gets straight to the point. It is front-loaded and contains 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?

This is a destructive delete operation with no output schema and no annotations. The description is too sparse; it does not explain the outcome, error conditions, or what constitutes an 'own' scope, leaving critical context 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 already describes both parameters with 100% coverage. The description adds that force only works for owners, but this is already implied in the schema's description of force ('solo owner'), so the added value is minimal.

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

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

The description clearly states the action: 'Elimina un scope propio' (Deletes an own scope). It is specific about deleting a scope owned by the caller, distinguishing it from generic delete_scope by the 'own' qualifier, though it relies on the name/title for that distinction.

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 guidance on when to use this tool versus alternatives like delete_scope. The only usage hint is the force parameter condition (only for owners), but no explicit when-to-use or when-not-to-use 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?

The description indicates a destructive action (delete) but does not disclose side effects such as irreversibility, cascading deletions, or required permissions. With no annotations, this lack of behavioral detail leaves the agent uncertain about consequences.

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 with no unnecessary words. It is efficiently structured and to the point.

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 delete operation with one parameter and no output, the description provides the essential information needed to call it. However, it does not mention behavior for non-existent users or any return value, which are minor gaps given the tool's simplicity.

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

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

The only parameter 'id' is described as 'ID del usuario', which is clear and sufficient. However, it adds no extra meaning beyond what the field name already implies, so it meets the baseline for full schema coverage.

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

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

The description clearly states the action (delete) and the resource (user), along with the identifier (id). It is unambiguous and 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?

No guidance is provided on when to use this tool versus alternatives like deactivating a user or using other user-related operations. The description simply states what it does without any contextual direction.

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 no annotations provided, the description carries the full burden. It transparently indicates the return behavior, including the null case for no active tenant. It does not mention potential errors or side effects, but for a simple getter, this is sufficient.

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 directly communicates the tool's function without unnecessary detail. It is well-structured and easy to understand.

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

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

Given the tool's simplicity (no parameters, no output schema), the description is complete. It specifies what the tool returns and the null condition, covering all necessary information for a user to invoke it 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?

The tool has no parameters, and the schema description coverage is 100% (trivially). The description adds no parameter-related information, which is appropriate. According to the baseline rule for high schema coverage, a score of 3 is given.

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: 'Devuelve el tenant activo actual de la sesión' with a specific verb (returns) and resource (active tenant). It also clarifies the null return when no tenant is selected, leaving no ambiguity.

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

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

The description does not mention when to use this tool versus alternatives such as list_tenants or set_tenant. It only describes what it does, leaving the user to infer its appropriate usage context without explicit guidance.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It only says it returns aggregated data, but does not clarify aggregation scope, performance implications, authentication requirements, or any side effects. This is insufficient for a tool with zero 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 a single, concise sentence without fluff. However, it is so minimal that it offers little value beyond restating the tool's name. It is concise but lacks substance, making it barely adequate.

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 lack of annotations, no output schema, and an undocumented parameter, the description is severely incomplete. It does not provide any context about the return format, the meaning of 'aggregated', or how the optional parameter affects the result. An agent would struggle to invoke this tool 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?

The schema defines a single optional parameter 'extra' with no description, and schema description coverage is 0%. The description does not mention or explain this parameter at all, leaving the agent without any clue about its purpose or usage. The description completely fails to compensate for the schema 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 'Devuelve los datos agregados del dashboard del tenant' clearly states the action (returns) and the resource (aggregated dashboard data of the tenant). It is specific enough to convey the tool's primary purpose, and none of the sibling tools appear to overlap directly, so no confusion arises.

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 alternatives. The description does not mention any prerequisites, exclusions, or conditions under which this tool is preferable. It simply states what it does.

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 gives minimal behavioral details. It states the action (lists permissions) and the source (roles), but does not mention side effects, authentication requirements, return format, or error scenarios. Since no annotations are present, the description carries the full burden and falls short.

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

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

The description is extremely concise and well-structured. One sentence conveys the essential information without any superfluous content. The verb is front-loaded, making the purpose immediately clear.

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

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

For a simple read operation with no parameters and no output schema, the description is adequate. It specifies the output (permissions) and the determining factor (roles). Some details like pagination or response format are omitted, but they are not critical for such a straightforward 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 no parameters, and the schema correctly reflects this with an empty properties object. Since there are no parameters to describe, the baseline of 4 is appropriate. No additional parameter explanation is needed.

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: listing the permissions of the authenticated user based on their roles. It uses a specific verb ('Lista') and a well-defined resource ('permisos del usuario autenticado'), which distinguishes it from general permission tools like list_permissions.

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

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

No explicit guidance is provided on when to use this tool versus alternatives such as list_permissions or get_my_scopes. The description implies it is for the current user's permissions, but it does not state when this tool should be preferred over others.

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 presents the tool as purely returning information, but the parameter createDefaultScope implies it may create a default scope as a side effect. This potential mutation is not disclosed in the main description, and there are no annotations to clarify 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 a single concise sentence that directly communicates the core behavior without unnecessary detail or repetition.

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 tells the caller what will be returned and the parameter descriptions explain the flags, but it does not mention the possible side effect of createDefaultScope or provide any output structure. Since there is no output schema, a bit more context about the response shape or side effects would improve 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?

Both parameters are covered by the schema with clear descriptions, so schema coverage is 100%. The main description does not add much detail about how the parameters affect the result, but the schema descriptions are sufficient for basic understanding.

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 returns the authenticated user's profile, their scopes, and optionally their permissions. The verb 'Devuelve' and resource 'perfil del usuario autenticado' make the purpose unambiguous.

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

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

No guidance is provided about when to use this tool versus related tools such as get_my_permissions, get_my_scopes, or update_my_profile. The description only states what it does, not when it should be preferred over 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?

No annotations are provided, so the description carries the burden. It states a read-like action (list) but does not explicitly mention that it is read-only, nor does it describe potential errors, side effects, or return format. The behavior is implied but not fully 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 a single, concise sentence that directly conveys the tool's purpose without any fluff or unnecessary details. It is well-structured and easy to parse.

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

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

The description sufficiently conveys that the tool returns a list of scopes, satisfying the core context for a simple get operation. While it lacks details about output format or edge cases, the simplicity of the tool makes the description almost 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?

The tool has zero parameters and the input schema is empty, so there are no parameter details to explain. The description adds nothing about parameters, but since none exist, it meets the baseline for high schema coverage.

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

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

The description clearly states the tool lists the scopes (tenants) the authenticated user belongs to, using a specific verb and resource. It is distinct from sibling tools like list_available_tenants or list_tenants by focusing on the authenticated user's scopes, 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.

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

The description implies usage when needing the authenticated user's scopes but does not explicitly contrast with alternative sibling tools or provide conditions for when to prefer this tool over others. No explicit guidance is given, only the basic functionality.

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 no annotations provided, the description carries the behavioral disclosure burden. The word 'Devuelve' implies a read-only operation, which is minimal transparency, but it does not state possible errors, token requirements, or what 'revisión/configuración' precisely entails. It is acceptable but thin.

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?

A single, front-loaded sentence that directly states the tool's purpose with no filler or redundant content. It is appropriately sized for such a simple zero-parameter operation.

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

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

For a zero-parameter getter, the description gives the core return topic but omits the concrete shape of the response and is ambiguous next to sibling tools that seem to overlap (get_tenant_settings, get_active_tenant). Given the absence of an output schema, more details about what exactly the configuration includes would be needed for a higher score.

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 no-parameter baseline of 4 applies. The description does not need to compensate for missing schema documentation since there is nothing to document.

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

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

The description states a specific verb and resource: 'Devuelve la revisión/configuración del tenant del token.' It is clear about the general action, but it does not differentiate from sibling tools like get_tenant_settings or get_active_tenant, which also deal with tenant information.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention related siblings, prerequisites, or situations where another tool would be more appropriate, leaving the agent to infer selection solely from the name and short description.

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?

No annotations are provided, so the description carries the full behavioral burden. It conveys that the operation is a read ('Devuelve') and explains the id/tenant resolution behavior, but it does not mention side effects, permissions, or error conditions. This is acceptable for a getter 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?

Two sentences with the main action, endpoint, and default behavior. The parenthetical about the endpoint is useful but 'el tenant va como id' is somewhat redundant with the following sentence about the default id. Still compact and front-loaded.

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

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

The tool is simple (only two params, both documented) and has no output schema. The description covers the operation, endpoint, and default behavior, which is sufficient for basic invocation. It does not describe the response format, but for a low-complexity getter this is a minor omission.

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 100%, so the baseline is 3. The description repeats the fact that omitting id uses the active tenant, which reinforces the schema but does not add new semantic meaning. It adds the endpoint context and clarifies the id maps to the tenant, but no more.

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

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

The description states a specific verb and resource: 'Devuelve la configuración (settings) de una app para el tenant activo de la sesión.' It also references the exact endpoint (profile/get-scope-settings), and the get/set contrast with the sibling set_tenant_settings makes the purpose unambiguous. No confusion with get_active_tenant, get_dashboard, or list_tenants remains.

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: it applies to the active session tenant and falls back to that tenant when no id is passed. It does not explicitly tell when not to use it or point to alternatives like set_tenant_settings, but the read-only role is evident enough. That places it at 'clear context, no 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?

With no annotations provided, the description carries the full burden, yet it only states the action without disclosing side effects, such as whether existing permissions are overwritten, whether partial failures occur, or what permissions are required. The behavior is essentially a black box beyond the high-level import action.

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 front-loads the primary action and includes the most important parameter note. No unnecessary words or redundancy are present.

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 explain the expected structure of the 'items' array objects, nor does it mention any output or response behavior. Given the nested object schema and lack of output schema, an agent would have insufficient context to construct valid inputs or understand results.

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?

Two of three parameters (items and idScope) have descriptions in the schema, and the tool description adds crucial context for idScope (0 uses token's tenant). However, 'extra' is completely undescribed, leaving its purpose ambiguous. The moderate coverage and the idScope explanation justify a mid-range 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 states the tool imports a batch of permissions into a scope, using the specific verb 'imports' and identifying the object and target. It distinguishes itself from sibling tools like create_permission and list_permissions by emphasizing the batch nature and the special idScope 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 implies usage for bulk permission imports but does not explicitly contrast with single-permission tools or list-permission tools. It provides a useful note about idScope=0 but lacks explicit guidance on when to choose this over 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?

With no annotations, the description must disclose behavior. It states the list is filtered by token permissions (assignable roles based on user scopes), which is useful. However, it omits details like error handling for invalid scope IDs, pagination, or whether an empty list results from insufficient permissions.

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, efficient sentence that front-loads the core behavior. No redundant or vague wording is present.

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 simple with one parameter and no output schema, but the description does not specify what the returned list contains (e.g., role objects, IDs, or just names). It also lacks information about error scenarios or behavior when the token lacks access to the given scope. These omissions matter because there is no output schema to clarify the return structure.

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 100% for the single 'id' parameter, which already has a clear description ('ID del scope (tenant)'). The tool description adds no additional meaning about the parameter, so the baseline of 3 applies.

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 lists roles the token can assign, filtered by user scopes. This is specific and distinguishes it from sibling 'list_roles' which likely lists all roles. The verb 'lista' and resource 'roles asignables' are precise.

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

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

The description implies usage when you need assignable roles based on token scopes, but it does not explicitly mention when not to use it or compare it to alternatives like list_roles. No exclusions or prerequisites are given, so 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.

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

With no annotations, the description carries the full burden. It clearly states the action (list) and the result (tenants with id and name), and implies token-based access. It does not explicitly state read-only or side-effect-free, but listing is inherently non-mutating.

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

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

The description is two concise sentences. It front-loads the primary purpose and includes a necessary disambiguation note without any 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?

Given the simple nature of the tool (no parameters, no output schema), the description provides all necessary context: what is listed, what fields are returned, and how it differs from a similar 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 no parameters, so there is nothing for the description to clarify. The schema is trivially complete and the description adds no unnecessary parameter information.

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 lists tenants (scopes) accessible to the token, including id and name. It also differentiates from list_tenants, making the purpose unambiguous.

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

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

It explicitly says these are the tenants among which you can choose with set_tenant, and warns not to confuse with list_tenants, providing clear guidance on when to use this tool versus the alternative.

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?

No annotations are provided, and the description only says 'lists' without explicitly stating it is read-only or has no side effects. It does not disclose return format, pagination, or error 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 a single, concise sentence with no redundant information. It directly conveys the action and target, maintaining excellent 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?

While the purpose and parameter are clear, the description lacks any mention of the expected output (e.g., list format, fields returned) or potential error conditions. This leaves some ambiguity 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?

The single parameter 'id' is fully described as 'ID del scope padre', providing clear meaning and required context. Schema coverage is 100% with a descriptive label.

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 function: listing child tenants/scopes of a parent scope. It specifies the resource (children) and the relationship (parent), distinguishing it from other scope-related 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?

No guidance is provided on when to use this tool versus alternatives like list_tenants or get_scope_review. The description only states what it does, not the context or conditions for 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 verb 'Lista' clearly indicates a read-only operation, and no side effects are mentioned. However, since no annotations exist, the description carries the full burden; it does not explicitly state that no data is modified, but this is strongly implied.

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 begins with a clear verb and contains no unnecessary words or details. It is well-structured and easy to parse.

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

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

For a simple no-parameter list operation, the description provides sufficient context about what is listed. It does not describe the output format, but this is a minor gap given the simplicity of the operation and the absence of an output schema.

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 input schema has no properties, so schema description coverage is effectively 100%. The description adds no parameter semantics because there are no parameters to describe, matching the baseline for high coverage.

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

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

The description clearly states the specific action ('Lista') and the resource ('roles disponibles para asignar en invitaciones del tenant'), making it distinct from sibling tools like list_invitations or list_roles.

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 invitation-related role assignment but does not explicitly contrast with alternative tools or provide conditions for when to choose this over others. No direct 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?

No annotations are provided, so the description carries the full burden. It does not disclose whether the operation is read-only, requires any permissions, or has side effects. While 'list' suggests read-only, this is not explicitly stated, and no other behavioral traits are mentioned.

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 directly conveys the action, resource, and scope with no unnecessary words. It is perfectly structured for its 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?

For a simple list operation with no parameters and no specified output schema, the description is complete. It identifies exactly what is listed and for which tenant, providing sufficient context for an agent to invoke it 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?

The tool has no parameters, so schema coverage is effectively 100%. There is nothing to explain about parameters, and the description does not add extra meaning. The baseline score of 3 applies.

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

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

The description clearly states the action ('Lista' - lists), the resource ('invitaciones' - invitations), and the scope ('del tenant del token' - of the token's tenant). This distinguishes it from sibling tools like 'list_invitation_roles' and 'create_invitation' without ambiguity.

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

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

The description does not explicitly mention when to use this tool versus alternatives. However, the name and description suffice for a simple listing operation, implying usage when a list of invitations is needed. Still, no explicit guidance is 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?

No annotations are provided, and the description does not explicitly state that the operation is read-only or side-effect free. It also does not disclose any potential behavioral aspects like pagination beyond the parameters.

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, clear sentence that avoids 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?

No output schema is provided, and the description does not mention the response format or any error conditions. It gives no context about the returned user objects or whether it supports filtering.

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?

Only the limit parameter has a description; offset is described only by its type. The description of limit includes a default value, but offset's semantics (e.g., starting index) are not explained.

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

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

The description clearly states the action (lists users), the scope (of the token's tenant), and a specific use case (to assign roles in invitations). It differentiates from generic list_users by adding the tenant scope and invitation purpose.

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

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

It implies usage for invitation role assignment but does not explicitly state when to use this instead of search_users or list_users. It lacks explicit alternatives 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?

No annotations and no mention of side effects, return shape, or read-only guarantees; verb 'Lista' suggests read-only but behavior is not fully 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?

Single concise sentence, directly states purpose without extra words.

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 one well-described parameter and no output schema, the description is adequate, though it lacks any usage context or alternatives.

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 is already described in the schema as 'ID del tenant'; description adds no extra semantic clarification but schema coverage is complete.

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 uses specific verb 'Lista' and resource 'clientes OAuth', scoped by tenant, clearly distinguishing from create/update/delete and other list 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?

No explicit guidance on when to prefer this tool over siblings like list_oauth_client_scopes; usage is implied by name/description but not stated.

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

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

No behavioral information is disclosed beyond the basic listing action. The description does not mention whether the operation is read-only, requires specific permissions, or returns a particular format. Since no annotations are present, the description carries full responsibility for transparency but fails to provide details.

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 with no redundant words. It effectively communicates the core functionality without unnecessary elaboration.

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 listing operation, the description provides the essential purpose and parameter. However, it lacks guidance on usage context, expected output, or edge cases, making it only partially complete for an agent that needs to decide when and how to invoke it.

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 input schema provides a description for the single parameter 'id' ('ID del tenant'), so the meaning is clear. The tool description does not add any additional context or clarification about this parameter, but the schema already covers it adequately.

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: to list OAuth scopes assignable to clients of the tenant. It uses a specific verb ('list') and identifies the resource ('OAuth scopes') and context ('for clients of the tenant'), distinguishing it from the sibling tool 'list_oauth_scopes' which likely lists all scopes.

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 indicate when to use this tool versus alternatives such as 'list_oauth_scopes' or 'list_available_tenants'. No context or conditions for selection are provided, leaving the agent to infer use cases.

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 no annotations, the description only states that it lists scopes. It does not disclose potential side effects (likely none), required permissions, or output format, but the simple read operation is adequately described for basic understanding.

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, clear sentence with no redundant words, efficiently conveying the tool's purpose.

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

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

The description sufficiently conveys the core functionality for a simple list operation, including the tenant context. It lacks details about output or authentication but remains adequate given the tool's simplicity.

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

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

There are no parameters, so schema coverage is 100%. The description adds no parameter-specific information, which is acceptable given the absence of 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 the tool lists OAuth scopes for the token's tenant. It is specific and distinguishes from related tools like list_oauth_clients or list_oauth_client_scopes.

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 the tenant scope, but does not mention edge cases or comparative usage.

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 verb 'Lista' implies a read-only operation and 'árbol aplanado' hints at the return shape, but no explicit statement about side effects, required permissions, or error behavior is included. With no annotations, the description carries the burden and only partially covers it.

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 immediately conveys the tool's purpose and scope, with no superfluous content.

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 simple tool signature and single optional parameter, the description provides enough context for selection and invocation. It could mention the output structure more explicitly, but 'árbol aplanado' gives a reasonable indication.

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 already describes the optional 'id' parameter as 'ID de scope (se usa como tenant de referencia)', so the tool description adds no further meaning. Schema coverage is 100%, so baseline 3 applies.

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 lists permissions for the token's tenant as a flattened tree, which is a specific verb and resource and distinguishes it from related tools like list_role_permissions or get_my_permissions.

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

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

No explicit guidance is given about when to use this tool versus alternatives such as list_role_permissions or get_my_permissions. The context is implied by the description but not stated.

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

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

With no annotations, the description carries the burden for behavioral transparency. 'Lista' implies a read-only operation, but it does not explicitly state that there are no side effects, nor does it mention auth requirements, pagination, or other behavioral details.

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, focused sentence with no redundant words. It front-loads the verb and resource, making it easy to scan.

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 simple and the description is adequate for a basic list call, but there is no indication of the output shape, whether results are paginated, or how errors are handled. The absence of an output schema makes this a notable omission.

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 already provides 100% coverage for the single parameter with 'ID del rol'. The description adds no new semantic detail beyond reinforcing that the id refers to a role.

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

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

The description clearly states the action ('Lista') and the resource ('los permisos asignados a un rol'), and the role scoping distinguishes it from general permission listers. It could be stronger by explicitly contrasting it with sibling tools like list_permissions, but the purpose is unambiguous.

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

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

There is no guidance on when to use this tool versus alternatives such as list_permissions or assign_role_permissions. The description implies its use case, but it never states conditions 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?

No annotations are present, and the description does not mention side effects, permissions, read-only nature, or any behavioral traits. It is impossible to know if this operation is safe or what it returns beyond the generic listing.

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

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

The description is extremely concise, containing only the essential information without any redundant or irrelevant content.

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 lacks information about the output format, pagination, ordering, or any potential errors. Given the absence of an output schema and annotations, the description leaves too many unanswered questions for an agent to understand the full behavior.

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 only parameter, id, is described as 'ID del scope (tenant)' which matches the tool's purpose and clarifies its meaning. The schema already indicates it is an integer and required, so the description adds reasonable semantic context.

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

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

The description clearly states the tool lists roles of a scope/tenant using the verb 'Lista' and specifies the object. It distinguishes the operation from other role-related tools, though it could be more explicit about the return value.

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 alternatives like list_assignable_roles or list_role_permissions. The description is a bare statement without context or selection 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It adds context about the X-Tenant dependency, which is useful, but does not explicitly state read-only nature or any permissions/limitations. The 'list' verb implies a safe operation, but the description could be more explicit.

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

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

Two sentences, both purposeful. The main action is stated first, followed by a critical disambiguation from a sibling. No 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 parameterless listing tool, the description fully covers the key context (active tenant) and the critical distinction from a similarly named tool. It is complete for an agent to invoke correctly without further 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?

The tool has zero parameters and schema coverage is 100%, so the description has nothing to add. Baseline for 0 params is 4; no further explanation needed.

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 uses a specific verb ('Lista') and resource ('árbol completo de tenants/scopes') and clarifies it applies to the active tenant of the session. It explicitly differentiates from sibling list_available_tenants, making the purpose unmistakable.

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

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

Explicitly warns against confusing this with list_available_tenants and explains the difference: this lists the active tenant's tree, while the alternative lists tenants the token can access. This provides clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that operation is a paginated listing, and the wording 'Lista' implies a read-only, none-destructive action. The required tenant-scope condition is also disclosed. There is no mention of response format or error behavior, but these are not critical for a safe read/list 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 text consists of two sentences with zero filler. The first sentence captures the core action, resource, and key behaviors (pagination, optional search). The second sentence adds a necessary permission precondition. Each sentence earns its place and the core information is front-loaded.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description is largely complete: it defines the operation, pagination, optional filtering, and the required tenant permission. It lacks only minor details such as default/limit behavior or response error formats, which are no less predictable for a simple list operation.

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

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

The schema has 100% coverage for parameters, so the baseline is 3. The description adds value beyond the raw schema: it explicitly mentions pagination and the optional search, and adds a semantic constraint on the `id` parameter (the scope must be among the token's tenants), which is not present in the schema description.

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

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

The description states a specific verb ('Lista'), a concrete resource ('usuarios de un scope/tenant'), and key functional flags (pagination, optional search). It clearly distinguishes the operation from broader search tools by scoping it to a tenant, and the additional sentence about the token requirement reinforces its specific use case.

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 when to use the tool (listing users of a tenant, paginated, with optional search) and explicitly states a prerequisite (scope must be within the token's tenants). However, it does not explicitly mention alternatives like search_users or list_invitation_users, nor does it state when not to use it.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that it removes a user from a scope, but doesn't disclose whether this is destructive, reversible, requires specific permissions, or what happens to associated invitations. For a mutation tool with no annotations, this is a significant gap.

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 immediately conveys the core action and context. It is front-loaded and contains no wasted words. It efficiently states what the tool does.

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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain side effects, permission requirements, or how it differs from the sibling 'remove_user_from_scope'. Given the complexity of the scope management context and the existence of a very similar sibling, more detail is needed for an agent to call it correctly and safely.

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 100%, so the schema already describes each parameter (id, idScope, username). The description adds no additional meaning beyond what the schema provides, so it stays at the baseline of 3. It doesn't clarify relationships between parameters or usage constraints beyond 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 clearly states the action: removes a user from a scope, and specifies the context as invitation rejection. This is a specific verb and resource. However, it doesn't explicitly differentiate from the sibling tool 'remove_user_from_scope', which also removes a user from a scope, so it lacks explicit sibling differentiation.

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 the similar sibling 'remove_user_from_scope'. The description mentions 'invitation rejection' but doesn't explicitly state that this tool is for rejecting invitations while the other might be for direct removal. No alternatives or exclusions are mentioned.

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?

No annotations are provided, and the description only states the core action without mentioning side effects, error conditions, or reversibility. The agent is left uninformed about potential outcomes.

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, direct sentence with no superfluous information. It is concise 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?

Given the simplicity of the operation and the clear parameter descriptions in the schema, the description sufficiently conveys the tool's purpose. However, some details about expected behavior or return values are missing, though not critical for this simple action.

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 provides clear descriptions for both parameters (user ID and scope ID). The description adds no additional meaning beyond what the schema already states.

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

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

The description clearly states the action: removing a user from a scope/tenant. It is specific and distinct from related tools like add_user_to_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?

The purpose implies when to use it, but there is no explicit guidance on prerequisites, context, or comparison with alternatives beyond the tool name itself.

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?

There are no annotations, and the description gives no information about side effects, authorization checks, error conditions, or return behavior. The phrase 'si es owner' hints at a permission requirement but does not explain what happens if the user is not the owner.

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

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

The description is extremely brief, which aids readability but sacrifices necessary detail. It lacks any structured explanation of the operation's logic or conditions, making it feel incomplete rather than concise.

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

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

Given the existence of separate create_scope and update_scope tools, this save_scope tool likely serves as an upsert convenience. However, the description does not explain how it relates to those siblings, when to prefer it, or what constraints apply. This makes the tool ambiguous within the broader context.

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

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

The schema provides basic descriptions for id, name, users, and description, but the tool description adds little beyond restating 'negocio'. The 'extra' parameter remains unexplained, and relationships between parameters (e.g., how id differs for create vs update) are not clarified.

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

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

The description states a clear verb ('creates or updates') and resource ('scope'), but it does not define when to create versus update, nor does it clarify what 'scope propio' and 'si es owner' mean. This leaves ambiguity about the exact operation, especially given sibling tools like create_scope and update_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?

No guidance is provided on when to use this tool instead of create_scope or update_scope. The description does not mention any selection criteria, prerequisites, or context that would help an agent decide between this and the more specific 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?

No annotations are provided, so the description carries the full burden. It states the search behavior and case-insensitivity, but does not clarify whether the operation is read-only, whether it returns partial results, or how errors or empty results are handled.

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 with no unnecessary words. It conveys the essential behavior and matching semantics 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 is sufficient for a simple search tool, but with no output schema or annotation, it does not describe the return structure, result limits, or sorting. An agent would know what the tool does but not exactly what to expect in the response.

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 already describes the username parameter as 'Texto a buscar', and the description adds the iLike matching behavior. This is adequate but minimal; it does not explain expected length, required format, or how the search string is interpreted beyond being a partial match.

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 searches for users by username using a case-insensitive partial match (iLike). The verb 'Busca' and resource 'usuarios' are explicit, and the iLike qualifier distinguishes this from a simple exact-match lookup.

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 what the tool does but provides no explicit guidance on when to use it versus related tools like list_users. It does not mention whether this should be used for filtering, autocomplete, or as a precursor to other user 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?

No annotations are provided, but the description discloses the key side effect—setting the active tenant for the MCP session—and the header mechanism. It also covers prerequisites (token access to the tenant) and the duplicate-name resolution behavior, which goes beyond a bare mutation description.

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?

Three concise Spanish sentences, each earning its place: what the tool does, how the effect is realized, and the constraint on the name/id pair. No filler or redundant restatement.

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 setter with two parameters and no output schema, the description covers the operation, its side effect, validation path, and an edge case (duplicate names). An agent has enough information to call this tool 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 coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: the name must be among tenants accessible to the token, and the id is the disambiguator for repeated names. This helps an agent decide when to supply the optional id.

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 ('Establece') and a precise resource ('tenant activo'), and it explains the session-scoped effect (sent as X-Tenant header in all requests). This clearly separates it from listing tools like list_available_tenants or get_active_tenant.

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 usage context and directs the agent to list_available_tenants to validate accessible names. It does not explicitly state when not to use the tool or mention get_active_tenant as the query counterpart, but the intent is 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?

With no annotations provided, the description carries the full burden. It discloses a critical destructive behavior ('Reemplaza la lista de settings'), names the endpoint, and explains the tenant default. It does not mention permissions, reversibility, or response format, but the replacement semantics are clearly stated.

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

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

The description is two sentences long, front-loads the core action, and contains no filler. Every clause adds useful information: the action, the endpoint, the replacement behavior, and the default tenant.

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 mutation tool with no annotations and no output schema, the description covers the primary behavior and default logic, but omits what the tool returns (if anything) or how errors are surfaced. Given its moderate complexity, this is a noticeable but not critical gap.

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 100%, so all three parameters are already documented. The description adds a bit of context (e.g., id defaults to active tenant, settings is a list) but does not materially exceed what the schema provides, warranting the baseline 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 states a specific verb (guarda/saves), a resource (configuration of an app), and the scope (tenant activo de la sesión). It also references the underlying endpoint, making the intent clear. It does not explicitly differentiate from the sibling get_tenant_settings, so it misses the top score for sibling distinction.

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 what the tool does and the default tenant behavior, but gives no explicit guidance on when to use it versus alternatives like get_tenant_settings or save_scope. There is no mention of exclusions or conditions that would make another tool more appropriate.

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?

There are no annotations or additional behavioral details. The description does not mention side effects, partial-update semantics, authentication requirements, or the response format.

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 clear sentence with no redundant information. It is well-structured and easy to read.

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 nested object parameters and lack of annotations, the description is far too sparse to fully support correct invocation. Important details about expected fields, output, and side effects are 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?

The parameters 'extra' and 'profile' are entirely unexplained, and 'fullname' is only self-explanatory by name. With no parameter descriptions or schema documentation, the meaning of the inputs is 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 updates the authenticated user's profile, matching the title. It distinguishes from get_my_profile (read) and update_user (admin update) by targeting the current 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?

No guidance is provided on when to use this tool versus related tools such as get_my_profile or change_my_password. The description only states the action, leaving the selection context implicit.

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?

No annotations are provided. The description mentions that the name field is persisted (implying other fields may not be), but it does not disclose side effects, permission requirements, whether updates are partial or full, or any error behavior. This leaves significant behavioral ambiguity.

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, with no superfluous words, and directly communicates the essential points in two sentences.

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 13 parameters including nested objects and boolean toggles, the description is far too brief to convey how these fields behave, whether they are optional for updates, or how they interact with each other. It is not complete for a user to correctly use 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 covers only 54% of parameters, and many fields (clientId, clientSecret, grants, scopes, extra) lack descriptions. The tool description adds some semantic context for id and name, but many parameters remain unexplained.

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

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

The description clearly states the action ('Actualiza los datos de un cliente OAuth') and distinguishes the identifier (internal UUID vs clientId), making its purpose obvious.

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

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

It explicitly clarifies that clientId is not the update identifier, which is a useful usage hint. However, it does not explicitly contrast with create/delete/list alternatives, though the context implies this is for existing clients.

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?

No annotations are present, and the description provides no behavioral details such as side effects, permission requirements, or whether the update is partial or full replacement. The agent gets no insight into what happens beyond the basic action.

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

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

The description is a single sentence that concisely conveys the core purpose without unnecessary words. It is appropriately sized for the minimal information it delivers.

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 annotations, sparse schema descriptions, and a description that only states the action, the context is highly incomplete. The agent is left without knowledge of required fields, optional parameter meanings, or any expected output.

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 covers only 25% of parameters with descriptions (only id). The description does not explain the meaning of name, extra, or description, nor does it clarify how they are updated. It merely repeats 'por id' without adding 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 the action (actualiza), the resource (scope OAuth), and the selector (por id), distinguishing it from other scope-related tools like create_oauth_scope or delete_oauth_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?

No guidance is provided on when to use this tool instead of alternatives such as update_scope or update_oauth_client. The description neither mentions conditions nor contrasts 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 no annotations provided, the description carries the full burden. It only states the basic action without disclosing side effects, idempotency, validation rules, or error behavior (e.g., if the permission does not exist). This is insufficient for understanding the tool's full 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 a single, concise sentence with no redundant words. It is well-structured and directly states the 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?

The tool lacks an output schema, annotations, and a detailed description. It does not mention required fields beyond the schema, the meaning of optional fields, expected return values, or error handling. This is not enough for an agent to confidently invoke the tool in various scenarios.

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?

Of the four parameters in the schema, only 'id' has a description. The description of the tool itself adds no additional meaning for 'name', 'extra', or 'description'. Parameter semantics are therefore largely under-specified.

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

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

The description clearly states the action (updates permission data) with a specific verb and object, distinguishing it from create/delete siblings. However, it lacks any context about the scope or implications of the 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 usage is implied by the name 'update_permission' and the action 'Actualiza', but there is no explicit guidance on when to use this tool versus create_permission or delete_permission. The description provides no alternatives or conditions.

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 no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it updates a role, but does not explain partial vs. full replacement, required permissions, reversibility, or side effects on associated data. This is a significant gap for a mutation 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 a single concise sentence with no wasted words. It front-loads the action and target. However, its brevity is also a weakness, as it omits essential details, but that is a content issue rather than a structure issue.

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 (4 parameters, nested object, no output schema, no annotations), the description is woefully incomplete. It does not mention return values, behavior of optional fields, or any constraints. An agent cannot reliably invoke this tool correctly based on this description.

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 only 25% (only 'id' has a description), so the description must compensate for the other parameters. It mentions 'por id' but offers no meaning for 'name', 'extra', or 'description'. The agent gets almost no help understanding these fields beyond their types.

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 'Actualiza los datos de un rol por id' clearly states a specific action (update) on a specific resource (role) identified by id. This distinguishes it from siblings like create_role, delete_role, and list_roles. The purpose is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or any comparison with related role operations. The agent is left to infer usage from the tool name and 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?

No annotations are present, and the description gives no information about side effects, permissions required, idempotency, or consequences of updating a scope. The behavior is completely opaque.

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 with no fluff or redundancy. It is well-structured and front-loaded, but lacks detail that could be included without becoming 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 complexity of the parameters (nested objects like extra and settings) and the surrounding scope-management context, the description is far too incomplete. It does not explain what a scope is, what the nested fields mean, or what happens after the update.

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 no extra meaning to the parameters. Only the 'id' parameter has a schema description; the other four parameters (name, extra, settings, description) are undocumented, and the tool description does not clarify their purpose or constraints.

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

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

The description clearly states the action (update) and the resource (scope by id), distinguishing it from other tools like create_scope or delete_scope. However, it is somewhat generic and doesn't specify which fields are updatable, though the schema provides 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?

There is no guidance on when to use this tool versus alternatives such as update_oauth_scope or save_scope. The description provides no conditions, prerequisites, or comparisons to 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?

It discloses the profile merge behavior, but omits details like password handling, extra field behavior, or error cases, which would be expected without annotations.

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

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

Two concise sentences front-load the primary purpose and key behavior 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?

With 7 parameters including nested objects and no output schema, the description is too sparse; it omits parameter semantics, response format, and failure modes.

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?

Only 'id' is described in the schema; the description adds no explanation for extra, state, fullname, password, or username, leaving their roles 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 clearly states it updates a user's data by ID, distinguishing it from create/delete/list operations among 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 implies use for existing users but does not explicitly contrast with create_user or other update variants, leaving some ambiguity.

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