l0-py-blocks-mcp

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

With no annotations provided, the description carries the full burden for behavioral disclosure. It indicates a mutation ('updating authentication configuration') but does not mention required permissions, side effects, reversibility, or what happens to existing settings. The lack of such context is a significant gap for a state-changing 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 well-structured with clear 'Args' and 'Returns' sections. The parameter list is necessary given the tool's complexity, though it partially duplicates schema information. Overall, it is efficient and does not waste 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 mutation tool with eight parameters and no annotations, the description is incomplete. It does not explain prerequisites (e.g., whether an SSO credential must be added first), the nature of the 'social login activation result,' or any side effects. The presence of an output schema is acknowledged, but the description fails to leverage it or add essential 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 description lists all eight parameters with defaults, which compensates for the 0% schema description coverage. However, most of this is a direct duplication of the schema's own defaults and types. It does add one meaningful detail: that project_key uses the global tenant_id if not provided, which is useful semantic context 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 with a specific verb ('Activate') and resource ('social login for the project'), and adds the scoping detail 'by updating authentication configuration.' This distinguishes it from other configuration tools and makes 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?

No guidance is given on when to use this tool versus alternatives like enable_authenticator_mfa or add_sso_credential. The description only defines what the tool does, not the context in which it should be selected, and there are no exclusions or alternative recommendations.

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 of behavioral disclosure. It indicates a mutation (add/save credentials) and notes the project_key fallback and is_enable default, but omits permissions, idempotency, overwrite behavior, or side effects. That's a significant gap for a write 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 well-structured: a one-sentence purpose, a clear Args list, and a Returns line. It is concise without being terse, though the parameter list takes up several lines. Each line adds value.

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

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

The tool has 7 parameters, no annotations, and moderate complexity. The description covers most parameters and the return type but lacks usage guidance and omits the audience parameter. It also doesn't address relationships to sibling tools or potential side effects, making it partially complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 6 of 7 parameters, including defaults, examples for provider, and the project_key fallback. However, it omits the 'audience' parameter entirely, which is notable since it has a default in the schema.

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

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

The description clearly states the action: 'Add social login credentials for OAuth providers' followed by concrete examples (Google, Facebook, GitHub). This is a specific verb+resource combination that distinguishes it from sibling tools like activate_social_login.

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 the tool is used to add SSO credentials but provides no explicit when-to-use vs alternatives or exclusions. It doesn't mention how this relates to activate_social_login or other auth-related siblings, so usage context is only 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, so the description must disclose behavior. It mentions the return format ('JSON string with CLI availability status') but does not explicitly state that the tool has no side effects, whether it requires any setup, or how it behaves if the CLI is not installed. The word 'check' implies read-only, but this is not explicitly stated. It provides basic transparency but could be more explicit about safety.

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 short sentences, front-loaded with the main action and then the return type. No unnecessary words or redundancy. It is highly 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?

For a simple no-parameter check tool with an output schema, the description covers the essential information: what it does and what it returns. It could optionally mention the relationship to install_blocks_cli, but the core information is sufficient. The context signals indicate low complexity, so completeness is adequate.

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 schema coverage is trivially 100%. The description does not need to explain parameter meaning. Baseline for 0 params is 4, and nothing in the description reduces this.

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 'Check if Blocks CLI is installed and available.' The verb 'check' plus the resource 'Blocks CLI' make the purpose explicit. It is also distinguishable from sibling tools, especially install_blocks_cli, by focusing on verifying installation instead of installing.

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 guidance on when to use this tool versus alternatives. It does not mention, for example, to use this before attempting to run CLI commands or to call install_blocks_cli if the check returns unavailable. There is no context about prerequisites or expected workflow.

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 transparency burden. It discloses the return type (JSON string) and the fallback to global tenant_id when project_key is omitted. However, it does not state whether the operation is destructive, overwrites existing config, or requires specific 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 well-structured with Args and Returns sections, concise and without waste. The only structural flaw is the parameter naming inconsistency, which is a clarity issue but not a conciseness 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?

The tool has moderate complexity with 4 optional parameters and an output schema. The description provides the purpose, return type, and one behavioral nuance, but misses a parameter and offers no usage context or relation to sibling tools. It is adequate but incomplete.

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

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

Schema description coverage is 0%, so the description must compensate. It covers 3 of 4 parameters but uses camelCase names (connectionString, databaseName) that mismatch the schema's snake_case names, and it omits use_blocks_db entirely. The note about project_key default is helpful but the inconsistency undermines 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 'Configure Blocks Data Gateway for GraphQL operations,' using a specific verb and resource. It distinguishes from the sibling getter get_blocks_data_gateway_config, though it could be more explicit about what configuration entails beyond connection details.

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 given on when to use this tool versus alternatives, such as the sibling get_blocks_data_gateway_config. There is no mention of prerequisites, typical scenarios, or exclusions, leaving the agent without context for invocation.

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 full burden for behavioral disclosure. It does mention a key behavior (project_key uses global tenant_id if not provided) and the return format, but it does not cover potential errors, idempotency, or permissions. This is adequate but not rich.

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

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

The description is concise and front-loaded with the action, followed by a clean Args/Returns structure. Every sentence adds value, and there is no redundant information.

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

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

For a 2-parameter tool with an output schema, the description covers purpose, parameters, and return value. It does not explain prerequisites or edge cases, which might be relevant for a creation tool, but the overall context is sufficiently complete for an AI agent to use 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?

Schema description coverage is 0%, so the description must compensate. It defines both parameters: module_name as the name to create, and project_key as the tenant ID with its defaulting behavior. This adds meaning beyond the bare schema property names, though the default behavior could be more detailed.

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 ('Create') and the specific resource ('a new module for translation in a project'). This distinguishes it from sibling tools like get_translation_modules (which retrieves modules) and save_module_keys_with_translations (which saves keys).

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 context of use is clear: it's for creating a translation module within a project. However, it does not explicitly name alternative tools or state when not to use this tool, so it misses the exclusionary guidance of a 5.

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 add useful context: project_key defaults to global tenant_id, type defaults to 3 for 'Data protection', and dependent_permissions defaults to []. However, it does not disclose side effects, error conditions, idempotency, or whether duplicates are allowed, which are important 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 well-structured with a clear one-line purpose, a concise Args block, and a Returns line. Every line conveys necessary information without fluff, making it appropriately sized and 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?

For a 9-parameter tool with no annotations, the description gives a solid parameter-level overview but lacks guidance on when to use the tool, error handling, or relationship to roles and permissions workflows. The existence of an output schema reduces the need to describe return values, but the absence of usage context and mutation consequences leaves gaps.

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

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

The input schema has 0% description coverage, so the description must compensate. It lists all 9 parameters with explanations, including default values and an example for tags. While some descriptions are tautological (e.g., 'name: Permission name'), the coverage of defaults and the tenant fallback adds real 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 begins with 'Create a new permission', which is a specific verb+resource statement. This clearly distinguishes it from sibling tools like 'update_permission', 'create_role', and 'list_permissions', making the tool's 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 parameter details and defaults, but it never explicitly states when to use this tool versus alternatives like update_permission or list_permissions. There is no mention of prerequisites, exclusions, or scenarios where this tool should not be used. The usage intent is implied only by the tool name.

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, so the description must disclose behavioral traits. It only lists arguments and return value, but does not mention permissions, idempotency, error conditions, or side effects beyond creation.

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

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

The description is concise and well-structured, starting with a clear summary and then listing args and return value. It avoids 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?

The description provides enough to invoke the tool with correct parameters, especially since output schema exists for return values. However, it lacks contextual details like when to use or potential failure modes, making it merely adequate.

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

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

Schema description coverage is 0%, and the description compensates by explaining each parameter. It clarifies repo_name format (e.g., 'username/repo'), repo_link as full URL, and notes defaults for repo_id and is_production.

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 'Create a new project in Selise Cloud' with a specific verb and resource. It distinguishes from sibling tools like get_projects (which lists projects) and create_module.

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 mention when to use this tool versus alternatives, nor any prerequisites 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?

With no annotations, the description must disclose behavioral traits. It adds the detail that project_key uses global tenant_id if not provided, which is useful. However, it does not discuss side effects, permissions, duplicates, or error handling, leaving some transparency gaps.

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

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

The description is compact and front-loaded, with a one-sentence purpose followed by a structured Args/Returns list. No words are wasted, and all lines contribute useful information.

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

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

Given the tool has 4 parameters and no annotations, the description covers all parameters and notes the tenant fallback behavior. The return value is stated as a JSON string, and an output schema exists, so the vague return description is acceptable. Minor gaps remain around error cases and permissions.

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

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

Schema coverage is 0%, so the param list in the description carries the semantic burden. It provides meaningful glosses: slug is a 'URL-friendly identifier' and project_key is a 'tenant ID' with a default fallback. The name/description glosses are basic but confirm the role owner.

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

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

The description opens with 'Create a new role,' a specific verb+resource statement that clearly distinguishes this tool from siblings like create_permission or create_project. It immediately conveys the tool's purpose and the resource it operates on.

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, nor does it list any exclusion criteria. However, the clear 'Create a new role' statement implies the primary use case, and the sibling tools are distinct enough that the intended usage is inferable.

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 must carry the behavioral transparency burden. It does disclose the return format ('JSON string with schema creation result') and the project_key fallback to global tenant_id, but it does not mention whether the schema requires later finalization (via finalize_schema), permissions needed, or other side effects. This is a significant gap given the existence of related siblings.

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: a single-sentence summary followed by a structured Args/Returns block. Every line contributes information, the main action is front-loaded, and there is no redundant or filler 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 tool is simple with only 2 parameters and an output schema, so the description doesn't need to explain return details. It covers the core purpose, all parameters, and the return format. However, it lacks lifecycle context (e.g., whether finalize_schema is required afterward) and usage guidance, which prevents it from being fully complete for agent decision-making.

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?

Despite 0% schema description coverage, the description explicitly explains both parameters: schema_name as 'Name of the schema to create' and project_key as 'Project key (tenant ID). Uses global tenant_id if not provided'. This adds real meaning beyond the schema titles, including a default behavior, fully compensating for the schema's lack of 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 first sentence clearly states the action and resource: 'Create a new schema in Selise Blocks GraphQL API.' This is a specific verb+resource statement that distinguishes it as a creation operation. However, it doesn't explicitly differentiate it from sibling tools like finalize_schema or update_schema_fields, so it falls 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 implies the tool is for creating schemas, which is a clear context, but it offers no explicit guidance on when to use it versus alternatives or any prerequisites. No exclusion or alternative tool references are provided, so it meets the 'implied usage' level.

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 discloses the project_key fallback behavior, but fails to mention any side effects, prerequisites, or whether this is a mutation operation that could overwrite existing settings. The description is minimal for a tool that enables security features.

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

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

The description is concise and structured into Args and Returns sections. Every sentence earns its place, with no filler or redundancy. It is appropriately sized for a single-parameter enabling 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?

Given the low complexity (1 optional parameter) and the presence of an output schema, the description is mostly complete. However, it lacks explicit guidance on when to choose this tool over the sibling enable_email_mfa, which is a minor gap for a tool in a suite with multiple MFA options.

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

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

Schema coverage is 0%, but the description compensates by explaining the parameter's meaning ('Project key (tenant ID)') and its default behavior ('Uses global tenant_id if not provided'). This adds value beyond the empty 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 uses a specific verb ('Enable') with a clear resource ('Authenticator Multi-Factor Authentication') and scope ('for a project'). The name itself differentiates from the sibling enable_email_mfa, and the description reinforces this by specifying 'Authenticator MFA' rather than a generic MFA.

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 (enabling authenticator MFA for a project) but does not provide explicit when-to-use guidance or contrast with alternatives like enable_email_mfa. It gives some contextual detail (project_key fallback to global tenant_id), but no exclusions or alternative recommendations.

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 of disclosing behavior. It adds a useful detail about the fallback to global tenant_id when project_key is not provided, and it mentions the return type. However, it does not disclose side effects, permissions, idempotency, or any potential impacts of enabling MFA, leaving some behavioral gaps.

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

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

The description is concise and well-structured: a one-sentence purpose statement followed by clearly labeled Args and Returns sections. Every sentence provides useful information with no redundancy or 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?

Given the tool's simplicity (one optional parameter and an output schema), the description covers the basics but misses context such as whether the operation can be repeated, what constitutes a successful result, or any prerequisites. The fallback behavior is helpful, but overall completeness is adequate with clear gaps around behavior and side effects.

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

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

Schema description coverage is 0%, so the description must compensate. It effectively explains project_key as 'Project key (tenant ID)' and clarifies the fallback behavior to global tenant_id, adding real meaning beyond the bare schema definition. For a single parameter, this is strong semantic guidance.

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

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

The description clearly states the action with a specific verb and resource: 'Enable Email Multi-Factor Authentication for a project.' This distinguishes it from siblings like enable_authenticator_mfa, which target a different MFA method. The intent is immediate and unambiguous.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives such as enable_authenticator_mfa or activate_social_login. It only explains the project_key argument, not the broader usage context or prerequisites. The 'when to use' is only implied by the tool name.

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 does not state whether this operation mutates data, commits changes, or has side effects; saying 'retrieving updated schema' hints at a read operation, but 'finalize' suggests potential state changes. Permissions, reversibility, and error behavior 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 a concise docstring with Args and Returns sections. It avoids fluff and front-loads the core purpose. The structured format is slightly verbose but each element earns its place.

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, the description is the only source of behavioral context. It covers parameters and return type but omits side-effect details, prerequisites, and error handling. Given the simple parameter set (3 params, no enums) and presence of an output schema, it is minimally viable but not fully complete.

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

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

Schema description coverage is 0%, but the description explicitly explains each parameter's purpose, including that 'project_key' uses a global tenant_id if not provided. This adds meaningful semantics beyond the bare schema titles, compensating for the lack of inline schema 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 a specific action ('Finalize schema changes') and resource ('schema'), and positions it as 'step 3 of schema field management', which distinguishes it from sibling tools like create_schema or update_schema_fields. However, the exact meaning of 'finalize' is not elaborated, leaving some 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 gives clear context that it is part of a multi-step workflow ('step 3 of schema field management'), implying when to use it in sequence. It does not explicitly list exclusions or alternatives, but the step-oriented wording provides adequate 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 exist, so the description carries the burden. It implies read-only behavior through 'Get' and discloses default parameter behavior ('Uses global tenant_id if not provided'), but does not explicitly state side-effect safety 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 extremely concise: one purpose sentence, a single parameter explanation, and a return type. No superfluous words, 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 simple one-parameter read tool, the description covers purpose, parameter behavior, and return format. The output schema likely documents the configuration shape. The only gap is the lack of selection guidance versus alternatives, but that is accounted for in the usage dimension.

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 only a title and default for project_key with no description. The description compensates fully by explaining 'Project key (tenant ID)' and the fallback to global tenant_id, adding substantive meaning.

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 'Get the current authentication configuration for the project', using a specific verb and resource. It distinguishes from sibling get_auth_status by focusing on 'configuration' rather than status.

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

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

No guidance is provided on when to use this tool versus alternatives like get_auth_status or activate_social_login. The description lacks any use-case context, exclusions, or alternative references.

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, so the description carries the burden. It discloses the return format ('JSON string with authentication status') which is basic transparency, but it does not describe side effects, safety, or behavior on invalid tokens. This is minimal but not misleading.

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

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

Two concise sentences with front-loaded purpose and a clear return statement. No wasted words; every sentence earns its place.

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 (0 params, output schema exists), the description adequately covers purpose and return type. It does not discuss edge cases or token validity nuances, but the output schema likely provides that detail. It is complete enough for a basic status check.

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 no parameter explanation is needed. The description implicitly covers all parameters (none), and the baseline for 0 params is 4.

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

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

The description clearly states 'Check current authentication status and token validity' with a specific verb and resource. It is distinct from siblings like get_authentication_config, though it does not explicitly compare itself to alternatives, so it misses the full 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?

No guidance is provided on when to use this tool versus alternatives. The purpose implies usage, but there is no explicit context or exclusions, leaving the agent to infer.

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 adds useful context like the project_key fallback behavior and the fact that it returns a JSON string. However, it doesn't disclose error handling, permission requirements, or explicitly state that the operation is read-only, leaving the safety profile mostly to inference from the name.

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

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

The description is compact and well-structured, with a clear first line stating the action, followed by Args and Returns sections. Every sentence is meaningful and there is no redundancy or fluff.

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

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

For a simple getter with an output schema, the description sufficiently covers the invocation and return type. However, it omits details about what the configuration contains or potential error scenarios, and the lack of annotations leaves some context missing. Still, given the simplicity, it's nearly 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 description explains the single parameter meaning (project key as tenant ID) and its resolution behavior (uses global tenant_id if not provided). This goes well beyond the bare schema type and default, fully compensating for the 0% schema description 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 uses a specific verb ('Get') and a clear resource ('Blocks Data Gateway configuration'), making the primary purpose unmistakable. It distinguishes itself from sibling 'configure_blocks_data_gateway' through the action word, though it doesn't explicitly contrast with other read-only tools.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no mention of complementary tools. The only clue is the name itself, which implies retrieval but does not offer decision-making context.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions the return type (JSON string) but does not explicitly confirm this is a read-only operation, note any permission requirements, or indicate potential side effects or performance considerations. The verb 'Get' implies read-only but lacks explicit assurance.

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 only two sentences, with the purpose front-loaded in the first sentence. The return-type note is brief and adds minimal value without wasted 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?

Given the tool has no parameters and includes an output schema, the description is largely sufficient. It clarifies the scope of 'global state' to include authentication and application domain, but could be slightly more explicit about standing as a composite of the specialized getters.

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 schema fully covers the parameter surface. The description appropriately does not add parameter details, and no further semantics are 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 gets the 'global state' and specifies the included domains ('authentication and application domain'). It distinguishes itself from narrower siblings like get_auth_status and get_authentication_config, which focus on individual aspects.

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 its siblings. It does not mention that it is a broader aggregate getter, nor does it offer any comparison or exclusion criteria. The agent must 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 of behavioral disclosure. It discloses that this is a read-only 'Get' operation, explains the fallback to global tenant_id when project_key is omitted, and specifies the return format (JSON string with key names, IDs, resources). This adds meaningful context beyond the tool name, though it omits error handling and authorization 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 tightly structured with a one-line summary, an Args section, and a Returns section. Every sentence provides relevant information without fluff, making it an exemplar of concise technical writing.

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 getter with two parameters and a fixed return type, the description covers the essential aspects: purpose, argument semantics (especially the optional parameter), and output format. The presence of an output schema further clarifies return structure. It lacks error-handling details and prerequisites, but these are not critical for this low-complexity tool.

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

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

The schema has 0% description coverage, so the description must compensate. It explains module_id as the module to fetch keys from (mostly restating the schema) and project_key as a tenant ID with a fallback default, which adds useful semantics. However, the explanation for module_id is shallow, providing only partial compensation for the missing schema 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 that this tool gets available keys in a specific module for translation, using a specific verb ('Get') and resource (module keys). It distinguishes itself from sibling tools like get_translation_modules (which lists modules) and save_module_keys_with_translations (which saves keys).

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: it is used for translation in a project and requires a module_id, with an optional project_key. However, it does not explicitly contrast with alternatives or state when not to use it, though the intended use case is evident from the wording.

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 transparency. It states that the tool returns a JSON string and extracts application domains, implying a read-only operation, but it does not explicitly disclose side effects, error behavior, or additional constraints. This is adequate for a simple getter but lacks depth.

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

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

The description is concise and well-structured: a single-sentence purpose followed by a clear Args list and Returns line. Every sentence contributes value, and there is no redundant or fluff 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 tool is a simple read-only list operation, and the description covers its purpose, parameters, and return type. Since an output schema exists (as indicated by context), the description need not detail the return structure. It could mention that the operation is read-only, but the verb 'Get' strongly implies this, so it is reasonably complete.

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

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

The schema has 0% description coverage, so the description must compensate. It does so effectively by explaining each parameter: tenant_group_id filters, page is for pagination, and page_size sets the page size. It also notes optionality and defaults, adding meaning beyond the bare 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 tool's function: 'Get projects from Selise Blocks API and extract application domains.' This specifies a verb (Get), a resource (projects), and a distinct outcome (extract application domains), which distinguishes it from sibling tools like get_schema or get_resource_groups.

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 by explaining that tenant_group_id filters projects and that page/page_size control pagination. It does not explicitly name alternatives or exclusion criteria, but the purpose sentence makes it obvious when this tool is appropriate (when needing project data).

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 discloses that project_key defaults to the global tenant_id and that the return is a JSON string, which adds behavioral context. However, it does not explicitly state that this is a read-only operation or describe error behavior, leaving some transparency gaps.

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 and front-loaded, starting with a clear one-sentence purpose before detailing parameters and return. The structured Args/Returns format is efficient, and every sentence provides unique information without 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?

For a simple getter with one optional parameter and an output schema, the description covers the input semantics and return format sufficiently. It could mention what a resource group is or potential edge cases, but given the presence of an output schema, the main gaps are minor. Overall it is reasonably complete.

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

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

The schema provides only the parameter name and default, with no description. The description's Args section adds critical meaning by explaining that project_key is a tenant ID and that if omitted, the global tenant_id is used. This fully compensates for the schema's lack of description, though it could be more detailed on format 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 ('Get available resource groups') and the target ('for a project'), using a specific verb and resource. It distinguishes this from sibling tools like get_projects or get_schema by focusing on resource groups. This is a clear and unambiguous purpose.

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

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

The description does not mention when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. There is no guidance on when to choose this tool over sibling tools. The only context is that it retrieves resource groups for a project, but no usage conditions are 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 annotations are provided, so the description carries the full burden. It does disclose a useful behavior (project_key falls back to global tenant_id) and states the return type (JSON string), but doesn't explicitly confirm read-only nature or mention any access requirements. For a get tool this is decent but not comprehensive.

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

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

The description is well-structured: a one-line summary, a clear parameter list, and a return type statement. No unnecessary prose, and the front-loaded summary is effective. The parameter breakdown is slightly mechanical but not wasteful.

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

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

The tool has 7 parameters and no annotations, but the description covers all parameters, defaults, and the project_key fallback behavior. With an output schema present, the vague 'Returns: JSON string with role permissions result' is acceptable. Overall it is complete enough for an agent to use effectively.

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

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

Schema description coverage is 0%, so the description must compensate. It explains every parameter (7 total) with meaningful context, including defaults, filtering behavior, and the project_key fallback. Some descriptions are borderline tautological ('Search filter') but overall adds significant value beyond the bare 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 'Get permissions assigned to specific role(s)' with a specific verb+resource, and the 'specific role(s)' qualifier distinguishes it from sibling list_permissions (which likely queries all permissions). It clearly differentiates from set_role_permissions (write counterpart).

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 querying permissions by role_slugs, but does not explicitly state when to use this instead of list_permissions or set_role_permissions. No named alternatives or exclusions are provided.

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

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

With no annotations provided, the description carries the burden of disclosing behavioral traits. It clearly indicates the return type ('JSON string with schema fields and metadata') and acknowledges using 'global tenant_id if not provided', which is useful. However, it does not mention error behavior (e.g., if schema_id is not found), authentication requirements, or side effects. For a simple read-only getter, this is adequate but not rich in behavioral context.

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

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

The description is efficiently structured and front-loaded. The first sentence immediately states the purpose, followed by a concise Args section and a Returns line. No word is wasted; every sentence contributes to understanding the tool. The structure follows a conventional docstring format that is easy for an agent 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?

Given the tool's simplicity (2 parameters, no nested objects, output schema present), the description covers the essentials: purpose, parameters, and return format. It also contextualizes the tool within a workflow ('step 1 of schema field management'). It does not elaborate on error scenarios or prerequisites, but for a read-only getter with an output schema, the description is sufficiently 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 input schema has no parameter descriptions (0% schema_description_coverage), so the description's Args section provides essential meaning. It explains that schema_id is 'the ID of the schema to retrieve' and clarifies that project_key is the 'Project key (tenant ID)' with a fallback to global tenant_id. This adds value beyond the schema, which only lists types and titles. It doesn't provide exhaustive formatting details, but effectively covers the semantics.

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 primary function: 'Get a schema's current fields using its ID'. It uses a specific verb ('get'), identifies the resource ('schema's current fields'), and specifies the identifier method ('using its ID'). It also distinguishes itself from sibling tools like 'list_schemas' (which lists all schemas) and 'update_schema_fields' (which modifies fields) by positioning itself as 'step 1 of schema field management'.

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 contextual usage guidance by labeling this as 'step 1 of schema field management', implying it should be used before editing fields. It also mentions the optional project_key fallback to global tenant_id, which helps in mixed-tenant scenarios. However, it does not explicitly exclude alternatives or mention when NOT to use this tool, such as when retrieving all schemas (use list_schemas) or when modifying fields (use update_schema_fields).

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 that project_key defaults to global tenant_id and specifies the return structure (JSON with language names, codes, default status). This adds useful context beyond the schema, though it doesn't explicitly state read-only nature.

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?

Tightly structured with Args: and Returns: sections, no redundant text. Every sentence adds value (purpose, parameter, return).

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 getter with one optional parameter, the description covers purpose, parameter, and return value. Output schema exists, so return details are bonus. It lacks explicit differentiation from siblings, but that is minor for a tool of this 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?

Schema descriptions are absent (coverage 0%), so the description must compensate. It clearly defines project_key as 'Project key (tenant ID)' and explains the default behavior, making the parameter's meaning and usage fully clear.

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

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

Clear, specific verb ('Get') and resource ('available languages for translation in a project'). Distinguishes from sibling tools like get_translation_modules and publish_translation by focusing on languages rather than modules or publishing.

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 use this tool versus alternatives. It only mentions the optional project_key and fallback to global tenant_id, which is a parameter behavior rather than usage context. No comparison 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?

No annotations are provided, so the description carries the full burden. It discloses the parameter fallback behavior and the return format (JSON string with module names and IDs), but does not mention potential errors, authentication needs, or other behavioral nuances. This is adequate for a read-only tool but not deeply transparent.

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 highly concise: a single-sentence summary followed by brief Args and Returns sections. Every sentence adds value with 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?

For a tool with one optional parameter and an output schema, the description covers purpose, parameter semantics, and return value. It could mention error conditions or alternative uses, but for a simple getter it is sufficiently 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 schema has 0% description coverage, so the description must compensate. It adds meaning to 'project_key' by explaining it is a 'Project key (tenant ID)' and describes the fallback behavior when not provided. This goes beyond the schema's bare property definition.

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

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

The description clearly states the tool's function: 'Get available modules for translation in a project.' It uses a specific verb ('Get') and resource ('available modules'), distinguishing it from sibling tools like 'get_translation_languages' (which gets languages) and 'get_module_keys' (which gets module keys).

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

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

The description provides clear context (for translation in a project) and notes the default behavior for project_key ('Uses global tenant_id if not provided'). It doesn't explicitly exclude alternatives, but for a simple getter this level of context is sufficient.

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 full burden. It only notes that a JSON string with installation result is returned. It does not disclose prerequisites like Node.js/npm availability, whether the installation is global or local, idempotency, or potential side effects such as modifying global packages. This is minimal 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 two short sentences, front-loaded with the core action. Every word earns its place; no redundant information or 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?

Given the tool has no parameters and an output schema exists, the description's mention of the return format is adequate at a basic level. However, it lacks context about installation prerequisites, potential impacts, and when to use this instead of check_blocks_cli. This is a minimal viable description but with clear gaps in operational 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 tool has zero parameters, so schema coverage is trivially 100%. There is nothing to add about parameter semantics, and the baseline of 4 for zero-parameter tools 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 installs Blocks CLI using npm, with a specific verb and resource. It is distinct from the sibling tool check_blocks_cli, which presumably verifies installation rather than performing it.

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 use this tool versus alternatives. Since check_blocks_cli exists as a sibling, the description could have mentioned using that to verify installation, but it doesn't. Usage is only implied by the tool's name 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?

With no annotations, the description carries the burden. It discloses that project_key uses the global tenant_id when not provided and that it returns a JSON string, which is useful. However, it does not explicitly state that the operation is read-only or has no side effects, though 'List' implies this.

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

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

The description is concise and well-structured with sections for Args and Returns. It contains no redundant information, and every sentence contributes to understanding the tool's purpose, parameters, and return value.

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

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

For a simple list operation with one optional parameter and an output schema, the description covers purpose, parameter semantics, and return format. It lacks explicit usage guidance and read-only confirmation, but given the tool's simplicity, it is reasonably complete.

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

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

The schema only has a default for project_key with no description (0% coverage). The description adds meaning by identifying it as a project key (tenant ID) and explaining the fallback to global tenant_id, which is beyond schema 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 begins with 'List all CAPTCHA configurations for a project,' which clearly states the verb (list), resource (CAPTCHA configurations), and scope (project). This distinguishes it from siblings like save_captcha_config and update_captcha_status, which imply write operations.

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 when-to-use guidance or comparisons with alternatives. The 'List' verb implies read-only retrieval, but it does not mention save_captcha_config or update_captcha_status as alternatives for modification, leaving the decision to the agent.

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 of behavioral disclosure. It explains parameter defaults, the fallback to global tenant_id for project_key, and the return format, but does not explicitly state read-only behavior, required permissions, or potential errors.

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

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

The description is well-structured with a leading purpose statement followed by an Args list and Returns note. It is somewhat verbose but not wasteful, as the parameter explanations are necessary given the lack of schema descriptions.

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

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

The tool has 8 parameters and no required fields, with an output schema available. The description covers all parameters, their defaults, and the return type. It is complete enough for the agent to understand how to invoke the tool, though it could mention use cases or related tools.

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

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

The description adds meaning beyond the schema by explaining each parameter in the Args section, including the special behavior of project_key (using global tenant_id) and default values. Since schema descriptions are absent (0% coverage), this is valuable.

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 'List all permissions for a project' with a specific verb and resource. It distinguishes from sibling tools like create_permission and update_permission by explicitly focusing on the listing 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?

The description provides no guidance on when to use this tool versus alternatives such as get_role_permissions or list_roles. There is no mention of exclusions, prerequisites, or scenarios where another tool would be 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals that the tool returns a JSON string, and it explains pagination, search, sort, and the fallback to global tenant when project_key is omitted. However, it does not explicitly state whether the operation is read-only (though 'list' implies it), nor does it mention permissions or potential side effects, which would be valuable given no annotations.

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

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

The description is well-structured as a docstring with a one-sentence summary, an args list, and a returns line. It is front-loaded with the main purpose and each parameter line is concise and informative. No fluff or redundant content 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?

Given that the output schema exists, the description does not need to detail the return structure. It covers all parameters and the high-level return type. It omits potential error conditions and auth requirements, but for a listing tool with all optional parameters, the description is fairly complete and provides enough 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 schema has 0% description coverage, so the description compensates by explaining all six parameters with their defaults and meanings. This adds value beyond the schema's bare titles. The explanations are mostly clear, though some are terse (e.g., 'Search filter', 'Sort order' for sort_descending), but they are sufficient for basic usage.

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 'List all roles for a project' with a specific verb (list) and resource (roles). It distinguishes itself from siblings like create_role and get_role_permissions by focusing on the listing operation at the project level. The purpose is unambiguous and immediately understood.

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 contextual details such as project scoping and parameter defaults, but it does not explicitly mention when to use this tool versus alternatives like list_permissions or get_role_permissions. The appropriate usage is implied by the name and description, but no clear 'when' or 'when not' 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?

With no annotations provided, the description carries the full burden. It discloses the return type ('JSON string with schemas listing result') and explains the pagination-related parameters. It does not explicitly state it is read-only, but 'List' implies a safe query. Missing explicit notes on concurrency or edge cases, but acceptable for a listing 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 well-structured with a clear one-line summary, an Args list, and a Returns note. It is slightly longer than necessary but every sentence provides useful information, and there is no redundancy.

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

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

Given the tool's simplicity and that an output schema exists (so return values need not be detailed), the description covers the key aspects: purpose, all parameters, and expected output. It does not mention authentication or rate limits, but for a list operation these are not critical; the description is complete enough.

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

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

Schema description coverage is 0%, so the description fully compensates by explaining every parameter in the Args section, including project_key ('Project key (tenant ID)'), keyword, pagination settings, and sort options. This adds significant meaning beyond the bare input schema.

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

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

The description starts with 'List schemas from Selise Blocks GraphQL API', which uses a specific verb ('List') and resource ('schemas') and clearly identifies the source. This distinguishes it from sibling tools like create_schema, get_schema, and update_schema_fields.

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 (listing schemas) but does not explicitly state when to use this tool versus alternatives, such as using get_schema for a single schema. There are no exclusion criteria or alternative tool mentions, 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 provided, the description carries the full burden of behavioral disclosure. It mentions making translations live in production and returns a success/failure status, but it does not disclose potential side effects (e.g., overwriting existing live translations), permission requirements, or irreversibility. The fallback to global tenant_id is a positive detail, but overall it is insufficient for a production-affecting mutation.

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

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

The description is well-structured: a clear one-line summary, a short elaboration, and then explicit Args/Returns sections. It is concise, though the second sentence ('This function publishes all translation keys...') partially restates the first sentence, adding a minor 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?

The tool is simple with one optional parameter and an output schema, so the description covers the essentials. However, it lacks usage guidance and behavioral safety context (e.g., permissions, reversibility), which are important for a production publish action. The description is adequate but has clear gaps.

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

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

The schema has only one parameter with no description coverage (0%), but the description fully compensates by explaining that project_key is a tenant ID and that it falls back to the global tenant_id if not provided. This adds meaningful semantic clarity beyond the bare schema definition.

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: 'Publish translations for a project, making them live and available for use.' It specifies the resource (translations) and the context (production environment), distinguishing it from sibling tools like save_module_keys_with_translations or get_translation_languages.

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 making translations live in production, but it does not explicitly state when to use this tool versus alternatives, and it lacks any exclusions or prerequisites beyond the optional project_key. The context is clear but not explicit about comparative 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 must carry the behavioral transparency burden. It discloses the return type (JSON string), the project_key fallback to global tenant_id, and the default for is_enable. However, it does not mention potential side effects such as overwriting an existing configuration or permission requirements.

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

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

The description is well-structured with a clear summary sentence, parameter list, and return statement. It is appropriately sized with no redundant 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?

The description covers all five parameters and the return value. It explains the project_key fallback and default behavior. While it doesn't detail the exact JSON result structure, the presence of an output schema reduces the burden. Minor gaps include potential error cases or prerequisites, but overall it's a complete tool 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?

The schema has 0% description coverage, but the description compensates fully by explaining each parameter: provider with its allowed values ('recaptcha'/'hcaptcha'), site_key and secret_key origins, project_key fallback, and is_enable default. This adds significant meaning beyond the schema's plain names and 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 clearly states 'Save CAPTCHA configuration for Google reCAPTCHA or hCaptcha,' using a specific verb and resource. It differentiates from siblings like 'list_captcha_configs' and 'update_captcha_status' by focusing on the save action.

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. It implies usage through the save action, but no exclusions or alternative guidance is given. It provides clear context about creating configs but no direct comparison 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?

With no annotations, the description carries the full burden. It explains the create/update semantics and the return format, but does not disclose side effects like overwriting behavior, atomicity, or permissions. This is adequate but has gaps.

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

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

The description is well-structured with Args and Returns sections, front-loaded with a clear purpose sentence. The nested bullet format is appropriate for the complex request object, and each line contributes useful information.

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

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

The description covers the request structure, parameter semantics, and return status for each key, which is sufficient for invoking the tool. It lacks some operational context like error handling or prerequisites, but given the presence of an output schema and the detail provided, it is nearly complete.

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

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

Schema coverage is 0%, but the description compensates thoroughly by explaining every parameter in detail, including ProjectKey fallback, ItemId semantics, and Resources structure. This adds significant meaning beyond the raw 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 opens with 'Save multiple translation keys with their translations to modules in a project,' which clearly identifies the action (save), the resource (translation keys with translations), and the target (modules in a project). This distinguishes it from siblings like get_module_keys or publish_translation, making the purpose unambiguous.

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

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

The description provides contextual guidance on create vs. update via the IsNewKey and ItemId parameters, clarifying when each is used. However, it does not explicitly name alternatives or state exclusions, so while usage context is clear, it stops short of full 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 disclose behavioral traits on its own. It mentions the mutation ('set') and the return format ('JSON string with confirmation'), but it does not state whether the change is persistent, requires special permissions, or affects existing repositories. This is a significant gap for a write 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 concise and well-structured: a one-sentence purpose up front, followed by an Args list, then a Returns line. No fluff, each element earns its place, and the format is scannable.

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

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

The tool has no annotations and an output schema exists, so returns are covered elsewhere. However, the description misses essential context: it does not explain when this setting takes effect, whether it is required before repository creation, or how it interacts with create_project. It also lacks details on permission requirements and side effects, leaving an incomplete picture for a state-changing tool.

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

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

The schema has 0% description coverage, so the description must compensate for the parameter meanings. The Args section lists all four parameters, but the explanations are terse and largely restate the parameter names (e.g., 'tenant_id: Tenant ID for the project'). It adds minimal value beyond the schema, except clarifying that domain is a URL.

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

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

The description clearly states the tool's function: 'Manually set the application domain and tenant ID for repository creation.' This is a specific verb (set) with a clear object and purpose, and it stands apart from sibling tools like create_project or get_projects.

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 use this tool versus alternatives. The phrase 'for repository creation' implies it is a setup step, but there is no mention of prerequisites, exclusions, or preferred scenarios. Sibling tools such as create_project are not referenced.

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 the core behavior (add and remove permissions), the default empty lists, and the project_key fallback, as well as the return type (JSON string). However, it does not specify side effects, error conditions, permission requirements, or whether changes are immediately persistent. Some behavioral transparency is present, but not comprehensive 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 structured with a purpose sentence, then Args and Returns sections. Every sentence adds value, and the parameter explanations are necessary because the schema provides no descriptions. It is slightly longer than strictly needed but not wastefully verbose.

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

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

The description covers the main input parameters and return type, and the existence of an output schema is noted. However, it lacks information about edge cases such as what happens when permission IDs are invalid, whether the role must exist, or whether the operation is idempotent. For a mutation tool without annotations, this leaves gaps for the agent.

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

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

Schema description coverage is 0%, but the description fully compensates by explaining each parameter: role_slug is an identifier, add_permissions and remove_permissions are lists of permission IDs with defaults, and project_key acts as a tenant ID with a global fallback. This adds essential meaning beyond the bare schema and clarifies default behavior.

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 first sentence, 'Assign or remove permissions from a role,' clearly states the action and target. This distinguishes it from sibling tools like get_role_permissions (read-only) and create_permission (creating a permission definition). The verb 'assign/remove' makes the purpose unambiguous.

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

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

The description gives context on how the tool works (e.g., project_key fallback to global tenant) but does not explicitly state when to use it over alternatives or provide exclusions. Usage is implied by the role-permission modification function, but there is no direct guidance about 'use this instead of get_role_permissions' or 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 must disclose behavioral traits on its own. It explains the project_key fallback and indicates the return type ('JSON string with status update result'), which adds useful context. However, it does not mention side effects, idempotency, permissions, or error behavior—common expectations 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 tightly structured: a one-line action summary, followed by a compact Args list and a Returns statement. Every sentence earns its place—no redundancy, no filler, and the most important 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?

Given the tool's simplicity (a status toggle with three parameters), the description covers the essential aspects: what it does, the parameter meanings, and the return type. It lacks explicit error scenarios or preconditions, but the output schema exists and the operation is straightforward, so the gap is acceptable. A 5 would require more detail on edge cases or side effects.

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 zero property descriptions, so the Args section shoulders the entire explanatory burden. It does excellent work: item_id is identified as the config ID, is_enable is clearly mapped to True/False, and project_key is explained as a tenant ID with a global fallback. This far exceeds what the schema alone communicates.

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

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

The description opens with a specific verb-resource pair: 'Enable or disable a CAPTCHA configuration.' This clearly distinguishes the tool from siblings like save_captcha_config and list_captcha_configs by focusing solely on status toggling.

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 one-line summary makes the intended use obvious: to turn a CAPTCHA config on or off. It does not explicitly mention alternatives or exclusions, but the contrast with sibling tool names (e.g., save_captcha_config) implies that this tool is specifically for status changes, not full config editing.

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 must disclose behavioral traits, but it only states 'Update an existing permission' and the return type. It does not mention side effects, required permissions, validation, or any constraints beyond parameter defaults.

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

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

The description is structured as a docstring with a clear purpose statement, Args list, and Returns note. While lengthy due to 10 parameters, each line adds value and 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?

The description thoroughly covers parameters and return type, and the output schema exists for structured results. It lacks usage scenarios or behavioral caveats, but for a straightforward update operation, it is reasonably complete.

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

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

The Args section adds meaningful explanations for all 10 parameters, compensating for the 0% schema description coverage. It clarifies optionality, defaults, and examples (e.g., 'uses global tenant_id if not provided' and 'default: 3 for "Data protection"').

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 'Update an existing permission,' using a specific verb and resource. This distinguishes it from siblings like create_permission and 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?

The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It only restates the function's operation without context.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that reserved fields are automatically filtered out and that project_key falls back to the global tenant_id. However, it does not explain whether existing fields are replaced or merged, potential permissions, or error behavior, leaving gaps 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 well-structured with a clear opening sentence and a formatted Args/Returns section. It is slightly lengthy due to listing all reserved fields, but each sentence adds meaningful detail 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?

For a 3-parameter update tool with an output schema, the description is fairly complete: it covers all inputs, the return type, and key behavioral quirks. The main omission is the exact semantics of field replacement (e.g., whether unspecified fields are removed), which is important for a destructive-feeling update operation.

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

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

The description provides thorough parameter explanations that go beyond the sparse input schema: it details the fields array with SchemaField properties, explains the project_key fallback, and lists the reserved field names. With 0% schema description coverage, this fully compensates.

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 updates schema fields, using the verb 'update' with a specific resource. The phrase 'step 2 of schema field management' provides context and distinguishes it from siblings like create_schema and get_schema.

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

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

It indicates this is part of a multi-step schema field management process and describes the expected input (existing + new fields). However, it does not explicitly state when not to use this tool or directly name alternatives, leaving some ambiguity.

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