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

No annotations provided. The description discloses that it adds a block without replacing, but lacks details on error handling, permissions, rate limits, or side effects. Example provides minimal behavioral context.

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

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

Two sentences plus an example, front-loaded with core purpose. Every part is useful with 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?

No output schema, so description should explain return behavior, but it does not. It covers input well but omits success/failure outcomes. Acceptable but not thorough.

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 documents parameters. Description adds summary and an example, but no additional semantics beyond what 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 it adds a single block without replacing others, with a specific verb and resource. It distinguishes from siblings like update or remove.

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 when to use (add block, not update or remove) but does not explicitly list alternatives or when-not-to-use. No mention of prerequisites or comparisons.

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 handles behavioral disclosure well, explaining authentication, configuration precedence, and session prerequisite. It lacks explicit mention of side effects or failure handling but is still informative.

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, well-structured, and includes key elements: purpose, prerequisite, configuration options, precedence, and an example. Every sentence is useful with no 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?

Given no output schema or annotations, the description is fairly complete, covering purpose, mandatory call sequence, and configuration methods. It does not mention return values, but for a config tool this is acceptable.

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 fully documents each parameter (100% coverage). The description adds value by explaining environment variable fallback, precedence, and providing usage examples, going beyond schema details.

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 'establishes and authenticates the connection to a Plone CMS', using a specific verb+resource. It distinguishes itself from sibling tools (which focus on content operations) by being a session initialization step.

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 states 'Must be called once per session before other tools can be used', providing clear when-to-use guidance. It also describes configuration via arguments or environment variables with precedence rules and an 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?

No annotations are provided, so the description covers behavioral traits: the structure is valid for 60 seconds (time constraint), and warns against including the title in block data because Plone auto-manages Title blocks. This adds critical context beyond schema.

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 four concise sentences plus an example. Every sentence adds unique information, and the key details are front-loaded. No redundant or superfluous text.

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's complexity (in-memory state, 60-second validity, dependency on subsequent calls) is well addressed. The description explains lifecycle, dependencies, and critical constraint. It does not mention return value, but no output schema is defined, so that gap is expected.

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 value with an example, explicit warning about Title blocks, and reference to plone_get_block_schemas. This enriches parameter understanding beyond the schema's 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 explicitly states that the tool prepares a block structure in memory for 60 seconds, to be used by the next call to plone_create_content or plone_update_content. It distinguishes its purpose from sibling tools like plone_add_single_block and plone_get_block_schemas.

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 clearly indicates when to use: before calling plone_create_content or plone_update_content, and advises using plone_get_block_schemas first. It does not explicitly list when not to use, but the context implies it is for setting up a full layout, not incremental updates.

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 basic creation behavior but lacks details on side effects (e.g., whether it overrides existing content), required permissions, or error scenarios. The mention of preview_image_link suggests some error handling, but overall transparency is minimal.

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: two sentences plus an example. It front-loads the purpose and key usage instruction. It could be slightly more structured but is efficient and free of fluff.

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

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

Given 8 parameters, no output schema, and no annotations, the description covers basic creation and block-based content. It lacks details on return values, error handling, or authentication needs. For a create tool with multiple nested object parameters, it is minimally complete but not rich.

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 all 8 parameters are documented. The description adds a usage example and mentions using blocks and blocks_layout for complex content, but does not provide significant new meaning beyond the schema. 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 explicitly states 'Creates a new content item (e.g., a page or news article) in Plone' and differentiates from the sibling tool plone_create_blocks_layout by indicating it should be used first for block-based content. The verb 'Creates' and resource 'content item' are clear.

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 a clear when-to-use: for adding complex block-based content, first call plone_create_blocks_layout then this tool. An example is given. However, it does not explicitly state when not to use or mention alternatives like update/delete tools, but the context with sibling tools makes it 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 bears full responsibility. It discloses the creation action and permission requirement but omits any side effects, error conditions, or behavior on duplicate usernames, which is a moderate gap.

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

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

The description is two sentences: the first defines purpose and requirement, the second provides a concrete example. It is concise, front-loaded, and each sentence 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?

For a creation tool with no output schema, the description provides essential details: action, prerequisite, and example. It does not mention return value or error handling, but given the simplicity and the presence of sibling tools like plone_update_user, 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?

Schema coverage is 100%, with all parameters described adequately. The description adds an example call that illustrates usage, which is helpful but does not significantly extend beyond the schema definitions. 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 'Creates a new user in the Plone site', which is a specific verb and resource. It distinguishes from sibling tools like plone_update_user by focusing on 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 provides a prerequisite condition: 'Requires Manager role or self-registration to be enabled', which helps the agent assess applicability. It does not explicitly exclude alternatives but gives context for when the tool can be used.

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?

Discloses the permanent deletion action, but lacks additional behavioral details (e.g., effect on child items, required permissions, undo possibility). With no annotations, more context would benefit.

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 no extraneous text. Front-loaded with purpose and includes a concrete example.

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

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

For a simple tool with one parameter and no output schema, the description is adequate. Could mention handling of children or permissions, but overall sufficient.

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 an example usage for the path parameter, which offers slight additional clarity 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?

Clearly states it permanently deletes a content item using its path. Distinguishes from sibling tools like update or create.

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 vs alternatives. Does not mention conditions or constraints such as permissions or irreversibility beyond 'permanently'.

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 describes the output (lists schemas) but does not explicitly state that the tool is read-only or idempotent. The description is functional but lacks explicit behavioral 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 sentences plus an example, with no wasted words. The key information is front-loaded, and the example aids understanding.

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 one optional parameter and no output schema, the description covers the main behavior. It lacks explicit mention of the return format (e.g., JSON structure), but for a simple list tool, 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?

Schema coverage is 100% with a description for blockType. The description adds value by stating the default behavior when the parameter is omitted (returns all), which is not in the schema itself.

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', using a specific verb and resource. It distinguishes from sibling tools that add, remove, or update blocks, and provides an example call.

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

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

The description explains behavior when blockType is omitted ('returns all blocks schemas') and notes it is 'Essential for understanding how to construct blocks'. However, it does not explicitly contrast with sibling tools or state when to use this tool versus others.

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

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

No annotations are present, and the description does not disclose any behavioral traits (e.g., read-only, authentication, rate limits, or side effects). As a 'get' operation, the read-only behavior is implied but not stated.

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

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

One sentence plus an example. No wasted words. The core action is front-loaded, and the example clarifies usage. Slightly improvement could be removing 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?

No output schema; description does not explain return value contents. For a tool with 2 params and no output schema, it is adequate but incomplete. Missing details on what the JSON includes could confuse agents needing specific fields.

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 covers 100% of parameters with descriptions. The description adds a usage example but no additional meaning beyond the schema. Baseline 3 for high coverage, and the example is helpful but not transformative.

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 'Retrieves the full JSON data for a single content item from Plone using its path,' specifying the verb, resource, and scope. Distinguishes from sibling tools like plone_search (lists multiple items) and plone_get_site_info (site-level).

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 or when not to use it. Usage is implied (need full JSON for a single item), but no exclusion criteria or comparison to siblings 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?

No annotations provided; description implies a read operation with 'retrieves', but does not explicitly state it is safe, idempotent, or lacks side effects. Adequate but could be more explicit.

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

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

Single sentence, concise, and front-loaded with the core action and examples. 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?

For a simple retrieval with no parameters and no output schema, the description is complete. It specifies what information is returned with examples.

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

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

There are zero parameters, so no additional param info is needed. The schema coverage is effectively 100%, and the description does not need to compensate. Baseline is 4 for no parameters.

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

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

The description clearly states the tool retrieves top-level site information, with specific examples (languages, Plone version). It distinguishes from sibling tools like plone_get_content or plone_get_types.

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 vs alternatives. The purpose is obvious, but there is no mention of when not to use or comparisons with similar tools like plone_get_types.

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 only states it retrieves translations. Does not disclose behavior like read-only nature, what happens if no translations exist, or authentication requirements. Bare minimum.

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 an inline example. Efficient and front-loaded. Could be more concise but includes necessary 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?

No output schema provided; description does not explain return format (e.g., structure of translations). Adequate for a simple retrieval but incomplete for full understanding.

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 a clear description for 'path'. Description adds an example but no additional meaning beyond schema. 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?

Clearly states it retrieves translations for a content item, with specific verb 'retrieves' and resource 'translations'. Includes an example that distinguishes it from sibling tools focused on content creation, deletion, or updates.

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 plone_link_translation or plone_get_content. Does not mention contexts 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 provided, the description carries the full burden. It indicates a read-only listing operation but lacks detail on authentication, rate limits, or behavior when no types exist. The behavior is simple so 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 a single clear sentence with no unnecessary words, front-loading the purpose effectively.

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 tool with no parameters and no output schema, the description is complete: it states what is returned with examples.

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?

Baseline is 4 due to zero parameters. The description adds no parameter info because none exist; it correctly describes the tool's action.

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 the tool lists all available content types in the Plone site, with examples. It distinguishes from the sibling 'plone_get_type_schema' which gets a specific type's 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?

The description implies usage for discovering available content types, but does not explicitly state when to use versus alternatives like 'plone_get_type_schema' or provide exclusion criteria.

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

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

No annotations are provided, so the description carries full burden. It describes the return value but doesn't explicitly state read-only behavior or potential restrictions. 'Gets' implies nondestructive, but more explicit safety context would improve score.

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 an example. Every sentence adds value, no wasted words. Front-loaded with the main action.

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

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

For a single-parameter schema retrieval tool with no output schema, the description sufficiently explains what the tool returns and gives an example. No gaps given the 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 coverage is 100% with a clear schema description. The description adds value with an example call and reiterates the parameter's purpose, making it more user-friendly.

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 gets the full JSON schema for a specific content type, including fields, types, required status, and validation rules. It distinguishes from siblings like plone_get_types by focusing on the schema of a single type.

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

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

The description explicitly says 'Use this to understand what fields are available when creating or updating content,' providing clear when-to-use guidance. It doesn't contrast with 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 are provided, so the description carries the full burden. It indicates a read operation ('Fetches') and no side effects are implied. The behavior is simple and adequately transparent for this 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 brief: two sentences and an example. It is front-loaded with the core purpose and provides a concrete example, all without extraneous 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 is provided, and the description does not mention the return format. For a simple fetch, this might be acceptable, but completeness is slightly lacking given the absence of return value information.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value by providing an example that demonstrates the usage of the required 'vocabulary' parameter. However, the filter parameters 'title' and 'token' are not further explained.

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

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

The description clearly states it fetches allowed values for a specific field, with an example using a vocabulary name. It distinguishes itself from sibling tools, none of which fetch vocabulary values.

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

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

The description explains it is useful for finding valid inputs for content fields, providing clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives 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?

The description accurately describes the read behavior (no side effects). Without annotations, it carries the burden but does not disclose potential errors (e.g., item without workflow) or authentication needs. No contradiction with annotations (none provided).

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: one functional statement and one example. Every word earns its place; 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?

For a simple tool with one parameter and no output schema, the description is sufficiently complete. It states what is returned (state and transitions). It could mention the structure of transitions, but that is minor.

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% coverage with a description for 'path'. The description adds value with an example showing usage format, though it doesn't elaborate further on 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 explicitly states the tool shows current workflow state and available transitions for a content item, with a concrete example. It clearly distinguishes from sibling tools like plone_transition_workflow that perform actions.

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?

Usage is implied (e.g., before transitioning), but no explicit when-to-use or when-not-to-use guidance is provided. No comparison to alternatives is given.

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

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

No annotations are provided, so the description bears full responsibility. It does not disclose side effects (e.g., creates a relation, no content modification), reversibility, or permission requirements. It also does not clarify the behavior if prerequisites are not met.

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, with no superfluous words. Every sentence adds essential 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 basic purpose and prerequisite, but lacks details on output, order sensitivity (source vs target), and relationship to sibling tools. Given no output schema, more context on expected results would be helpful.

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 baseline 3. The description adds value by clarifying that 'id' can be a full URL ('@id') and provides an example, which enhances understanding beyond the schema's example using a path.

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 links existing content items as translations. It uses a specific verb ('link') and resource ('content item as a translation of another'), but could more explicitly differentiate from sibling tools like 'plone_get_translation' or 'plone_unlink_translation'.

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 a prerequisite ('Both items must already exist') and an example, but does not specify when to use this tool versus siblings like 'plone_unlink_translation' or 'plone_get_translation', or mention when to avoid using it.

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

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

Only states 'Deletes' with no additional behavioral context. No annotations provided, so description must carry burden; missing details on side effects, error handling, or reversible 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?

Extremely concise: one sentence plus an example. No extraneous content, every part serves a 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?

Adequate for a simple two-param tool with no output schema. Covers core action, but lacks preconditions or error scenarios (e.g., what if block ID doesn't exist).

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 covers both parameters with descriptions (100% coverage). The description adds an example usage that clarifies the expected format (leading slash in path, blockId as string), providing practical context 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?

Clearly states the tool deletes a single block from a content item, with specific identification via block ID. Distinguishes from sibling tools like plone_delete_content (whole content) and plone_update_single_block (modify).

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?

Implied usage for deleting a block, but no explicit when-to-use or alternatives. Lacks guidance on when not to use (e.g., when wanting to delete entire content).

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 for behavioral disclosure. It mentions filtering but omits pagination behavior (b_size/b_start), default results when no filters applied, and whether the operation is read-only. This is insufficient transparency for an AI agent.

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 one sentence and an example. It is front-loaded and efficient, though could be slightly more structured (e.g., listing filter options). No 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?

Given 8 parameters, no output schema, and no annotations, the description is incomplete. It lacks details on return format, pagination mechanics, behavior when filters are combined, and edge cases (e.g., empty query). The example helps but does not cover the tool's full complexity.

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 descriptions for all 8 parameters, so baseline is 3. The description adds an example demonstrating usage of query, portal_type, and review_state, but does not elaborate on parameter formatting 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 verb 'Performs a detailed search' and the resource 'content items', listing key filters (text, content type, path, workflow state). It effectively distinguishes from sibling tools that create, update, or delete content, though it does not explicitly differentiate from plone_get_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?

The description provides an example but does not specify when to use this tool versus alternatives like plone_get_content. It lacks explicit guidance on conditions for use or exclusions, leaving the agent to infer suitability.

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

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

No annotations provided; description is minimal. It indicates a mutation (change state) but does not disclose side effects like permission requirements, reversibility, or error behavior if transition is invalid.

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?

Extremely concise: one sentence defining purpose plus an example. No unnecessary text, front-loaded with key 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?

Basic description with example, but lacks return value information (no output schema) and error handling. For a simple tool with 3 parameters, it is adequate but could add more detail on valid transitions or outcomes.

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 descriptions for all 3 parameters. The description adds a concrete example mapping parameters to values, which clarifies usage beyond schema alone.

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 changes workflow state by executing a transition, with specific example of 'publish' or 'submit'. It distinguishes from sibling tools like plone_get_workflow_info which only reads workflow info.

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. Does not mention prerequisites like content having a workflow, nor scenarios where it should not be used (e.g., for content without 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?

No annotations provided, so description must carry full burden. Only states the basic action without disclosing side effects, permissions, or reversibility.

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 an example. 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?

For a simple tool with 2 parameters and no output schema, the description is mostly adequate but lacks usage context and behavioral details.

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

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

Schema coverage is 100% and description adds an example but no further meaning beyond the parameter 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 the action (removes), the resource (translation link), and the identifying criteria (language code). It distinguishes from sibling tools like plone_link_translation.

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., plone_link_translation). No prerequisites or context provided.

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

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

No annotations provided, so description carries full burden. It discloses that the tool can update metadata and replace block structure, and warns against direct block editing. However, it doesn't mention idempotency or workflow side effects. The additionalFields tip adds useful 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?

Two concise sentences plus an example, front-loaded with key information, 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 6 parameters, nested objects, and no output schema, the description covers the main uses and provides practical tips. Lacks return value description but otherwise 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 baseline is 3. Description adds value by referencing plone_create_blocks_layout for blocks and providing a concrete example for additionalFields (preview_image_link with error handling).

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 'Modifies an existing content item in Plone' with specific verbs and resources. It distinguishes from sibling tools like plone_create_blocks_layout and plone_add_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?

Explicitly tells when to use this tool vs alternatives: 'Use plone_create_blocks_layout to prepare complex block updates or use the plone_add_single_block and plone_update_single_block tools for smaller changes.' Also includes a 'DO NOT' instruction and an 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?

With no annotations, the description states 'Modifies the data', indicating a write operation. However, it does not disclose whether the update merges or replaces blockData, authorization needs, or potential side effects. The example provides some clarity but leaves 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 a single sentence plus an example, which is concise and front-loaded. Every element earns its place with 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 mutation nature and absence of output schema or annotations, the description lacks explanation of blockData update behavior (merge vs replace) and does not cover error scenarios or required permissions. It is incomplete for a write 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%, so the baseline is 3. The description adds a concrete example demonstrating parameter usage (path, blockId, blockData), which enhances semantic understanding beyond the schema descriptions alone.

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 the verb 'Modifies', the resource 'data of a single, existing block within a content item', and the identifier 'block ID'. It clearly distinguishes from sibling tools like plone_add_single_block and plone_remove_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?

No guidance is provided on when to use this tool versus alternatives (e.g., plone_update_content). It does not mention prerequisites, limitations, or scenarios where other tools are 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. It explains that roles are specified as an object mapping booleans to add/remove them, which is good. However, it lacks details on side effects (e.g., whether unmentioned properties remain unchanged) and return behavior.

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

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

The description is very concise: two sentences plus a short example. Every sentence serves a purpose, 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?

The description covers the main behavior and role update mechanism, but it lacks information about the return value (e.g., success indication or updated user object). Given no output schema, this is a notable gap.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by providing an example of the 'roles' parameter usage, clarifying the boolean mapping logic for add/remove.

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 'Updates an existing user's properties in Plone.' with a specific verb ('updates') and resource ('existing user's properties'). It distinguishes from sibling tools like plone_create_user (creation) and plone_update_content (content update).

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

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

The description provides a precondition: 'Requires Manager role or the user updating their own account.' It also gives an example call. However, it does not explicitly state when to use this tool versus alternatives 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.