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

With no annotations, the description fully bears responsibility for transparency. It explains non-destructive behavior ('without replacing other blocks'), but does not disclose what happens on failure (e.g., invalid path or blockType) or return value. Adequate 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 extremely concise: two sentences and an example. Every part adds value, with the example serving as a quick reference. No 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?

The description covers the core action and parameters, but lacks information about the return value (since no output schema exists). For a tool with 4 parameters and no output schema, additional context about what the tool returns or side effects would be beneficial. 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 coverage is 100%, providing a baseline of 3. The description adds clarity by listing the key parameters ('block type, data, and optional position') and providing a concrete example that illustrates usage, which helps the agent understand how to structure the input.

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 adds a single new block without replacing others, using specific verb 'adds' and resource 'block'. It distinguishes from siblings like 'plone_update_single_block' and 'plone_remove_single_block' by emphasizing it adds rather than updates or removes.

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 specifies when to use ('adds a single new block') and provides an example, but does not explicitly mention when not to use or list alternatives. However, the sibling tools context and the nature of the description make the intended usage clear.

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

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

No annotations provided, so description carries full burden. Discloses authentication, session requirement, precedence, and env var fallback. Could mention error behavior but adequate.

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

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

Very concise: 3 sentences plus example. Front-loaded with core purpose. Every sentence 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?

Given no output schema, description adequately covers configuration, authentication, and ordering relative to siblings. Complete for a setup 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?

All parameters have schema descriptions (100% coverage). Description adds meaning: explains alternative auth methods, precedence, env var fallback, and example.

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?

Clearly states it establishes and authenticates connection to Plone CMS, must be called once per session. Specific verb+resource and distinguishes from siblings.

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

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

Explicitly says 'Must be called once per session before other tools' and gives configuration options (args vs env vars) with precedence and example.

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

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

The description discloses that the structure is valid for only 60 seconds, is held in memory, and that the title block is auto-managed. This adds transparency beyond no annotations, though it doesn't explicitly state what happens if not used within 60 seconds (implied by 'valid for 60 seconds').

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

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

The description is relatively concise with three sentences and an example. It front-loads the core purpose and usage, but the example and last sentence could be slightly condensed without losing clarity.

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

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

Given a single parameter and no output schema, the description fully covers what the tool does, how to use it, prerequisites, and limitations. It references sibling tools for deeper context, making it complete for an AI 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?

Although the schema covers all parameters (100% coverage), the description adds significant meaning: it explains the blocks array purpose, references plone_get_block_schemas for required fields, and includes warnings and an example. This goes well 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 tool prepares a block structure in memory for use by plone_create_content or plone_update_content. It distinguishes from siblings like plone_add_single_block by specifying this is for a complete layout, not a single block.

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 advises to call plone_get_block_schemas first for block data requirements, and warns against adding the title in block data. It also indicates that the structure must be used in the next immediate call, providing clear when-to-use 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?

Without annotations, the description carries full burden. It identifies the tool as creating content (mutation) but fails to disclose permissions, side effects, error handling, or return value. The note about block preparation is the only behavioral hint beyond basic action.

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

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

Two concise sentences plus a clear example. No redundant text; every sentence adds value. Front-loaded with action and examples.

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

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

Given no output schema and 8 parameters including nested objects, the description provides basic context but lacks guidance on block structure, error scenarios, or return values. Leaves gaps for complex usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal parameter semantics beyond the schema, only showing an example of typical usage. It does not explain relationships between blocks, blocks_layout, and additionalFields.

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

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

The description clearly states the tool creates new content in Plone, provides examples ('page or news article'), and distinguishes from sibling tools by referencing plone_create_blocks_layout for block-based content. The example further clarifies usage.

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

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

Explicitly recommends using plone_create_blocks_layout before this tool for complex block-based content, guiding when not to use this tool directly. Does not list all alternatives but provides relevant context for common scenarios.

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 requirement and gives an example, but does not detail return behavior, side effects, or error handling. It is adequate 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 two concise sentences plus an example, front-loaded with the core purpose. Every sentence adds necessary information without any waste.

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 creation tool with no output schema and minimal complexity, the description covers the essential aspects: purpose, requirements, and usage example. It could mention the expected return value but is complete enough for an agent to use.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value beyond the schema by providing an example call and noting the default password behavior, which clarifies 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 explicitly states 'Creates a new user in the Plone site', using a specific verb and resource. It differentiates from sibling tools like plone_update_user and plone_delete_content by its clear focus on user creation.

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

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

The description mentions the prerequisite 'Requires Manager role or self-registration to be enabled', which provides clear context for when the tool can be used. However, it does not explicitly state when not to use it or mention alternative 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?

States 'permanently deletes', which is the key behavioral trait, but lacks details on side effects (e.g., recursive deletion for folders), permission requirements, or undo capabilities. No annotations were provided to supplement.

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

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

Two sentences: first explains action and resource, second provides a concrete example. No redundant information; each 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?

For a tool with one parameter and no output schema, the description is mostly complete. However, explicitly stating that deletion is irreversible would improve completeness, especially given the destructive nature.

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

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

Schema coverage is 100% with path described. Description adds an example showing exact usage format, which clarifies the parameter expectation 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?

Description clearly states the verb 'permanently deletes', the resource 'content item', and the method 'using its path'. This distinguishes it from sibling tools like plone_get_content or plone_update_content.

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

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

No guidance on when to use versus alternatives (e.g., workflow transitions instead of deletion) or when not to use. For a destructive operation, prerequisites or cautionary notes are absent.

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

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

The description correctly implies a read-only operation (lists schemas). However, since no annotations are present, the description carries full burden. It does not specify the return format or structure, which is a gap for an agent expecting to use the output.

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

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

Two sentences and an example, front-loaded with the main action. No extraneous information. The bold emphasis on essentiality is helpful and concise.

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

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

Given the tool's simplicity (one optional param, no output schema), the description covers purpose, usage, and importance. It lacks a description of the return format, which would be beneficial but not critical for a straightforward listing tool.

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

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

Schema coverage is 100% (one parameter with enum and description). The description adds minimal value: it restates the optional nature and provides an example usage. Baseline 3 is appropriate.

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

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

The description clearly states it 'Lists all available Volto block types and their required data schemas.' This is a specific verb+resource combination. It distinguishes itself from sibling tools like plone_add_single_block by focusing on schema discovery rather than block manipulation.

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 explicitly positions the tool as 'Essential for understanding how to construct blocks.' It also explains an optional parameter behavior. While it doesn't provide explicit when-not-to-use or alternative comparisons, the context is clear for its intended use.

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

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

No annotations are provided, so the description carries the burden of disclosure. It correctly implies a read-only operation ('Retrieves') and uses 'full JSON data' to convey the response format. However, it does not mention error behavior (e.g., missing path) or permission requirements, but for a simple retrieval, the information is sufficient.

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

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

Two sentences plus an example are extremely concise and front-loaded with the primary purpose. Every word is necessary. No fluff.

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

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

No output schema exists, so the description should offer more detail about the return structure. 'Full JSON data' is vague; agents may need to infer fields. Given the context signals (no output schema, no nested objects), the description is adequate but not complete.

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

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

Schema coverage is 100%, so the description's param info is additive but not critical. The description provides an example call and clarifies that path can be '/' for root, which adds minor value beyond the schema's 'e.g.' examples. Meets baseline for high schema coverage.

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

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

Description clearly states the verb 'Retrieves', the resource 'full JSON data for a single content item', and the mechanism 'using its path'. An example call is provided, making the purpose unmistakable. It effectively distinguishes from sibling tools like plone_search which handles multiple items.

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 retrieving a single content item by path, but it does not explicitly specify when to use it versus alternatives like plone_search or plone_get_site_info. Lacks guidance on exclusions or prerequisites.

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 provided. Description implies read-only behavior but does not disclose any additional behavioral traits (e.g., caching, performance). Adequate for a simple retrieval 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?

Single sentence, front-loaded with action, no extraneous words. Efficiently states purpose and examples.

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

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

Lacks output schema but description gives examples of returned data (languages, version). Sufficient for basic understanding, though structure could be hinted.

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?

No parameters exist, so description adds no parameter info. Baseline 4 for zero-parameter tool.

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

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

Description clearly states the tool retrieves top-level site info, with specific examples (languages, version). It distinguishes from siblings which handle CRUD on content, blocks, users, etc.

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

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

No explicit when-to-use or when-not-to-use, but the tool has no parameters and is the only one for site metadata. Usage is implicitly clear given sibling tool diversity.

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 compensate. It states it 'retrieves' translations, implying a read operation without destructive side effects, but it does not disclose required permissions, potential errors, or the format of the returned data (e.g., list of paths, objects).

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 one sentence plus an example, no wasted words. It front-loads the action and identification method. Very concise, though it could be slightly more informative without length.

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 retrieval tool with one parameter and no output schema, the description covers the essential purpose and parameter. However, it lacks information about the return format or structure, which would help the agent understand what to expect.

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

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

The input schema already describes the single parameter 'path' with an example. The description adds a functional example call, but this largely duplicates the schema's example. The additional value is minimal, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Retrieves' and the resource 'all available translations for a content item', with an explicit identification method (by '@id'/path). It distinguishes from sibling tools like plone_link_translation and plone_unlink_translation by focusing on retrieval.

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?

While the purpose is clear, there is no explicit guidance on when to use this tool versus alternatives (e.g., when to get translations vs link or unlink). The example shows usage but lacks when-not or context for optimal 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 provided, so description carries full burden. Describes the output but does not disclose whether authentication is needed, side effects, or that it is read-only.

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

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

Single sentence with example, front-loaded with action verb, no 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?

Simple tool with no parameters or output schema; description adequately states what is returned, though could mention output format or lack of 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?

No parameters exist; schema coverage is 100%. Description adds no param info, but baseline 4 applies due to zero parameters.

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

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

Description clearly states the tool lists all available content types for creation, with examples ('Document', 'Event'). Distinct from sibling tools like plone_get_type_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?

Description implies usage context (when needing to know creatable types) but does not explicitly exclude alternatives or provide when-not-to-use guidance.

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

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

With no annotations, the description sufficiently discloses that the tool retrieves schema data without side effects. It describes what the schema contains and presents an example call, though it could mention idempotence or error handling for missing types.

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 at two sentences plus an example, front-loading the purpose and key detail. Every part adds value without redundancy.

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

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

Given no output schema, the description adequately explains the return value (full JSON schema with fields, types, etc.). It is complete for a simple read-only tool, though it could specify that unknown types return an error.

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 coverage is 100% for the single 'contentType' parameter, and the description repeats the exact schema description. The example adds minimal extra clarity, so the parameter semantics meet but do not exceed the baseline.

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 retrieves the full JSON schema for a content type, including details like fields, types, and validation rules. It distinguishes itself from sibling tools like plone_get_types or CRUD operations by specifying its schema-getting 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 advises using the tool to understand available fields when creating or updating content, providing a concrete example. While it doesn't explicitly contrast with all sibling tools, the guidance is clear and helpful for appropriate usage.

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

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

The description indicates a read operation (fetch) with no side effects. No annotations are provided, so the description carries the burden. It does not disclose auth requirements or rate limits, but for this tool it is adequate.

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

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

The description is concise, with two sentences and an example. No redundant information, front-loaded with purpose.

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

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

Given the tool's simplicity and full schema coverage, the description is complete. It does not describe return format, but that is not critical for this tool's usage.

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

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

Schema description coverage is 100%, so the schema describes all parameters. The description adds an example usage, but does not add significant new semantics beyond the schema.

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

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

The description clearly states it fetches allowed values for a specific field, using specific verb 'Fetches' and resource 'vocabulary values'. It distinguishes from sibling tools which focus on content 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 clear context: 'Useful for finding valid inputs for content fields'. It does not explicitly mention when not to use or alternatives, but the 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?

No annotations provided, so description carries the burden. It correctly describes a read operation (shows state, transitions) but does not mention permissions, error cases, or side effects. Adequate but not thorough.

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

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

The description is a single sentence plus an example, highly concise with no redundant information. Every sentence 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?

No output schema exists, and the description does not specify the return format beyond mentioning workflow state and transitions. It is somewhat complete for a simple read tool but could elaborate on the structure.

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

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

Schema coverage is 100% and the parameter 'path' is described adequately. The description adds an example usage but does not elaborate on the format or constraints beyond the schema.

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

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

The description clearly states the purpose: 'Shows the current workflow state and available transitions for a content item.' It distinguishes from sibling tools like plone_transition_workflow (which transitions) and plone_get_content (which gets content, not workflow).

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 checking workflow info but does not explicitly state when to use this tool vs alternatives like plone_transition_workflow or plone_get_content. No guidance on prerequisites or when not to 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 provided, so description carries full burden. Mentions prerequisite of existing items but lacks details on effects (e.g., whether linking is bidirectional, impact on existing translations). Adequate but basic.

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 plus a clear example. Information is front-loaded and no unnecessary 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?

With no annotations, output schema, or complex parameters, the description is sufficiently complete. Includes purpose, prerequisites, and example. Minor gap: could clarify if tool is additive (does not replace existing translations).

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

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

Schema covers 100% of parameters with descriptions, but description adds clarification that 'id' is a full URL (example shows URL, schema says path). This resolves potential ambiguity and adds practical 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?

Clearly states the tool links an existing content item as a translation of another. Distinguishes from sibling tools like plone_unlink_translation by using specific verb and resource.

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

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

Provides prerequisite that both items must exist. Includes an example for clarity. Does not explicitly state when not to use, but context is clear.

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

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

No annotations provided, so description carries full burden. It states 'Deletes' but does not disclose consequences (e.g., permanent removal, permission requirements, or impact on layout). While the verb is clear, additional behavioral context is missing.

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

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

Single sentence with example, no wasted words. Information is front-loaded: 'Deletes a single block...' immediately conveys purpose.

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

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

For a simple 2-parameter tool with no output schema, the description is fairly complete: it explains purpose, identifies parameters via schema, and provides an example. Missing only minor behavioral details like permanence.

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?

Input schema has 100% description coverage for both parameters, so the description adds little beyond schema. Example provides a concrete usage but no additional semantics. Baseline of 3 is appropriate.

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

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

Description clearly states 'Deletes a single block from a content item' with verb 'deletes' and resource 'single block'. It distinguishes from sibling tools like 'plone_add_single_block' and 'plone_update_single_block' by specifying deletion behavior.

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

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

No guidance on when to use this tool versus alternatives like deleting entire content or other block operations. Example shows syntax but does not explain context or exclusions.

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

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

With no annotations, description carries full burden but only mentions filters. Fails to disclose pagination (b_size, b_start), sorting behavior, or the fact that results are returned. Limited to 'detailed search' without specifying output or constraints.

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

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

Single sentence plus example is concise and efficient. However, lacks front-loading of key information (purpose first, example later) but overall no 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?

No output schema; description does not explain return values or pagination. Given 8 parameters and complex filtering, missing details on result structure, sorting, and batch handling leaves gaps for effective use.

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

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

Schema covers 100% of parameters with descriptions. Example usage adds practical context (e.g., 'annual report', Document type, published state) beyond schema, aiding understanding of typical combinations.

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

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

Description clearly states the tool performs a detailed search for content items and lists filters (text, content type, path, workflow state). This distinguishes it from sibling tools like plone_get_content (single item retrieval) and other non-search tools.

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

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

No guidance on when to use this tool versus alternatives (e.g., when to use plone_search vs plone_get_content). Does not mention when not to use or provide context for selection among siblings.

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

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

No annotations provided, so description must disclose behavioral traits. It mentions 'changes' but does not explain side effects, error handling (e.g., invalid transition), permission requirements, or whether the operation is reversible.

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

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

Two sentences with a clear example; no filler words. Efficiently conveys purpose and usage.

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

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

Given no output schema and three parameters, the description covers basic purpose but lacks details on return value, errors, or constraints. For a mutation tool, more completeness is warranted.

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

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

Schema coverage is 100%, so schema already describes all parameters. The description adds a usage example but no new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool changes workflow state by executing a transition, with examples like 'publish' or 'submit'. It distinguishes from siblings like plone_get_workflow_info (read) and plone_update_content (direct edit).

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 an example usage but lacks explicit guidance on when to use this versus alternatives, nor does it mention prerequisites like permissions. Implied usage is clear for workflow transitions.

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 fully disclose behavioral traits. It states the action but does not explain effects on the translation content (whether it remains as standalone content), permission requirements, or reversibility. The example is helpful but insufficient for a full transparency.

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

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

The description is very concise with two sentences: one defining the action and one providing an example. Every word is purposeful, no fluff, 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 simple tool with two parameters and no output schema, the description covers the core purpose and usage. However, it could be more complete by mentioning what happens to the unlinked translation item, as this is a common source of confusion.

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

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

Although schema descriptions provide 100% coverage, the tool description adds value by showing an example with concrete values, clarifying how the parameters (path and language) are used together. This goes beyond the schema's individual definitions.

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 verb 'removes' and the resource 'translation link', specifying the scope between a content item and one of its translations by language code. It effectively distinguishes from the sibling tool 'plone_link_translation' which performs the opposite 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 provides an example but lacks explicit guidance on when to use this tool versus alternatives like 'plone_link_translation'. No mention of when not to use it or prerequisites, leaving the agent to infer 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, so description must disclose behavior. It notes the ability to update metadata or block structure and mentions a potential 400 error for preview images. However, it omits authentication requirements, reversibility, or side effects of block replacement.

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

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

Two sentences plus an example, no fluff. Front-loaded with purpose. Every sentence contributes meaning.

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 6 parameters and no output schema, the description covers main use cases and references sibling tools for complex operations. Lacks details on return values but is adequate for an agent with complementary 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?

Schema coverage is 100%, but description adds context: the dual capability of updating metadata or block structure, and a specific example. AdditionalFields gets extra guidance on preview image errors. Adds moderate value beyond 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?

Description clearly states 'Modifies an existing content item in Plone,' specifying a verb and resource. It distinguishes from siblings by recommending alternative tools for different tasks.

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

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

Explicitly tells when to use other tools (e.g., plone_create_blocks_layout for complex block updates, plone_add_single_block and plone_update_single_block for smaller changes) and instructs not to edit block structure directly.

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?

Since no annotations are provided, the description must carry the full burden of behavioral disclosure. It states that the tool modifies data (write operation) but does not disclose potential side effects, permissions required, or whether the operation is reversible. The example shows the input but not the response 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 exceptionally concise: a single sentence stating the purpose immediately followed by a clear example. Every word contributes to understanding. There is no redundancy or unnecessary detail.

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

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

Given the tool's simplicity and the absence of an output schema, the description is moderately complete. It explains what the tool does and provides an example. However, it does not describe the return value or confirm that the tool returns the updated block. With 3 required parameters and a nested object, additional context about the expected format of blockData would improve completeness.

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

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

The input schema has 100% description coverage for all three parameters (path, blockId, blockData). The description provides an example that clarifies the structure, but it does not add significant meaning beyond the schema definitions. The schema already explains each parameter adequately.

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

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

The description clearly states the action ('modifies the data of a single, existing block') and specifies the resource ('within a content item, identified by its block ID'). This distinguishes it from sibling tools like plone_add_single_block and plone_remove_single_block. The example provides concrete parameter usage.

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 such as plone_update_content or plone_add_single_block. The description does not mention prerequisites or conditions for use. While the purpose is clear, the lack of when-to-use or when-not-to-use information limits its helpfulness.

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 explains role permissions and roles format, but doesn't disclose if updates are partial or full replacements, success/error behavior, or if any existing properties are overwritten.

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

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

Three concise sentences plus an example, no wasted words. Front-loaded with purpose and immediately actionable.

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

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

Given no output schema and no annotations, the description could cover return values, error conditions, or behavior for missing optional fields. It's adequate but not complete for a mutation tool with 7 parameters.

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

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

Schema coverage is 100%, so baseline is 3. The description adds an example and clarifies the roles object format, which adds marginal value beyond the schema's description of the same parameter.

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

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

The description specifies the verb 'updates' and the resource 'existing user's properties' clearly. It distinguishes from sibling tools like plone_create_user (creation) and plone_delete_content (deletion).

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 states role requirements (Manager or self-update) and provides an example, offering clear context. However, it doesn't explicitly mention when not to use this tool versus other user management tools.

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