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

With no annotations, the description must carry the burden of behavioral disclosure. It clearly signals a read operation via 'Read' and lists expected data, but it does not explain response shape, error behavior, authentication requirements, or any side-effect-free guarantee beyond the verb.

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, front-loaded sentence with no filler or redundant content. Every phrase contributes meaning by naming the operation and the returned context fields.

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 single-parameter read tool with no output schema or annotations, the description covers the main purpose and return elements sufficiently. It lacks explicit usage guidance and response-format details, but the low complexity makes this 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 schema has one parameter, story_id, with no description coverage. The description's phrase 'one Story identity' relates to story_id, and the parameter name is self-explanatory, but the description does not explicitly define story_id format or semantics beyond that implied connection.

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

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

The description states a specific action ('Read one Story') and the exact resource/scope ('one Story'), while enumerating the returned context: 'identity, authoritative document receipt, current data, revision, and preview URL.' This differentiates it from sibling tools like list_stories or get_story_rules.

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 use when a single Story's full context is needed, but it does not explicitly state when not to use it or name alternatives such as list_stories for multiple stories. No exclusions or competing-tool guidance is provided.

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

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

With no annotations provided, the description alone must convey behavioral traits. It states the file is 'immutable,' implying no modifications and a safe read-only operation, which is helpful. However, it does not disclose what happens if the rule does not exist, the return format, or any potential errors. For a read operation, this is minimal but not misleading.

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

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

The description is a single sentence with zero wasted words. It front-loads the action and resource, making it easy to scan and parse. It is appropriately concise for a simple tool.

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 required parameter, no output schema), the description is adequate but not rich. It does not specify return value structure or error handling. However, for a read-only retrieval of a rule file, this may suffice, especially with sibling tools providing context. It is minimally complete but could benefit from mentioning the output type.

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

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

The schema has a single 'rule' parameter with an enum of 9 values, but the description covers only a subset ('workflow, semantic, Quote, catalog, or producer'). It adds the context that these are rule files, which partially compensates for the 0% schema description coverage. It does not explain each enum value or the difference between 'pipeline' and 'basic,' leaving room for ambiguity.

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

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

The description uses a specific verb ('Read') and clearly identifies the resource as 'one immutable Story workflow, semantic, Quote, catalog, or producer rule file.' This distinguishes it from sibling tools like save_story_content or update_story_image, which imply write operations. The scope is precise and unambiguous.

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

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

The description implies this tool is for reading rule files but does not explicitly state when to use it versus alternatives. No exclusions or context like 'use this instead of get_story_context when you need the raw rule file' is provided. It is clear enough for a simple read operation but lacks explicit guidance.

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

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

No annotations are provided, so the description carries the burden. It states the tool is read-only ('read-only delivery status'), which is a key behavioral trait. However, it does not disclose details like whether it returns all stories or pagination, or any rate limits. The read-only hint is useful but 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 a single, concise sentence that conveys the purpose and key trait (read-only). No wasted words, front-loaded with the action and resource.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is adequate but not rich. It does not mention what the output looks like (e.g., a list of IDs with statuses), but the description implies that. It could benefit from noting that it returns a list, but it's not critical.

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

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

The schema has one optional parameter 'status' with an enum of 'ready' and 'waiting'. The description does not explain the parameter's meaning beyond the schema, but the schema itself is self-explanatory with the enum. Since schema coverage is 0%, the description could have added context, but the parameter is simple and the enum values are clear.

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

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

The description clearly states the tool lists iKAOS Story IDs and their read-only delivery status, which is a specific verb+resource combination. It distinguishes from siblings like update_story_image or save_story_content, which imply mutations, while this is a read-only listing.

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 retrieving story IDs and statuses, but does not explicitly state when to use this tool versus alternatives like get_story_context or get_story_rules. It lacks explicit exclusions or alternative guidance, but the read-only nature 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?

With no annotations, the description carries the behavioral burden. It discloses optimistic revision protection (so a stale expected_revision should be rejected) and immutable fields, but it does not cover side effects, authorization, error behavior on revision conflict, or the result/return value.

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 short sentences with front-loaded purpose: the first sentence states the action and object, and the second adds the key immutability constraint. Every word earns its place; there is no redundancy.

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

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

For a mutation tool with no annotations, output schema, or per-parameter docs, the description provides core context but is incomplete: it does not explain what happens when the revision does not match, whether creation and modification differ in behavior, or what a successful save returns.

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

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

Schema coverage is 0%, so the description must compensate. 'Story content/layout JSON' semantically maps to the content property and 'optimistic revision protection' gives meaning to expected_revision, but story_id is not described and no parameter is explicitly named with its role.

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

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

The description uses a specific verb phrase ('Create or modify') and identifies the resource and payload ('Story content/layout JSON'). It clearly distinguishes this save-content tool from the image-focused siblings (update_story_image, upload_story_image) and read-only siblings (get_story_context, get_story_rules, list_stories).

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 intended use is implied by 'Create or modify Story content/layout JSON', but the description does not explicitly state when to choose this tool over alternatives or when not to use it. The constraint that fixed docs and source metadata cannot be changed is a partial exclusion, but no sibling tools are referenced.

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

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

With no annotations available, the description carries the full burden of behavioral disclosure. It states it replaces an image, implying a destructive or mutating operation, but does not disclose side effects (e.g., whether old image is deleted), permission requirements, reversibility, or error behavior. For a mutation tool, this minimal detail is insufficient.

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, front-loaded sentence that delivers the core purpose without unnecessary filler. It is efficient, but its brevity comes at the cost of missing crucial context, so it is not exemplary but still appropriately concise relative to the minimal content provided.

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

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

Given the tool's complexity (5 parameters, nested object, no annotations, no output schema), the description is sorely lacking. It does not explain how the parameters relate (story_id, slot_id, image_path), the role of the viewport object, or what happens after replacement. The description is far from complete for an agent to use it correctly.

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

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

The schema provides no descriptions (0% coverage), so the description must compensate. It only clarifies the meaning of image_id (scoped ID from upload_story_image). The other parameters (story_id, slot_id, image_path, viewport) are left unexplained, and the nested viewport object has no documentation. This is a significant gap for a tool with 5 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 action (replace), the resource (Asset Hub image file), and the key input (scoped image ID from upload_story_image). It distinguishes itself from upload_story_image and other sibling tools by specifying an update operation, making the purpose explicit and unambiguous.

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

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

The description mentions the prerequisite of using the image ID from upload_story_image, implying this tool is for replacing existing images after a prior upload. It does not explicitly list when not to use it or name alternative tools, but the context from the sibling list and the verb 'replace' provide adequate guidance for an agent to decide when to invoke 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions verification and upload but does not explain what verification entails, potential side effects (e.g., overwriting), error handling, or authentication requirements. The description is too sparse to inform the agent of safety or side effects.

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, front-loaded sentence that efficiently states the primary action and scope. No redundant or filler content.

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

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

Given the tool's complexity—four parameters including a nested object, no output schema, and no annotations—this description is grossly inadequate. It omits critical information about parameters, verification logic, return values, and errors, making it nearly useless for correct invocation.

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

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

Schema coverage is 0%, so the description must compensate, but it does not explain any of the four parameters (story_id, slot_id, image_path, viewport). It only lists accepted file types, which is unrelated to the parameters. The nested viewport object is completely undocumented, leaving the agent without guidance on its meaning or usage.

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

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

The description clearly states the action (upload) and the target (Asset Hub) with specific file formats (PNG, JPG, JPEG, WebP) and a verification step. It distinguishes from sibling 'update_story_image' by implying an initial upload, but does not explicitly contrast with alternatives like 'save_story_content' or 'update_story_image'.

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 phrase 'after verifying the Story image slot' implies a specific use case for uploading images to slots, but it does not explicitly state when to use this tool versus alternatives, nor when not to use it. There is no mention of prerequisites or 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It states only that it validates, without clarifying side effects, return format, or potential errors. This is a significant gap for a validation tool that might have mutating or blocking behavior.

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

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

The description is a single concise sentence with no redundancy. It immediately states the verb and object, making it appropriately front-loaded and free of 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?

Despite the simple schema, the description is incomplete for an agent to use effectively. It does not explain what validation returns, how it relates to other story tools, or whether it modifies state. This could lead to incorrect invocation expectations.

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

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

Schema description coverage is 0% and the description does not mention 'story_id' or 'mode'. The required 'story_id' is left uninterpretable beyond its name, and 'mode' with const 'static' is entirely unexplained. The description offers no additional meaning than the schema already provides.

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 'Validate' and the resource 'Supabase Story content structure and identity'. It distinguishes from siblings like save_story_content and get_story_context by focusing on validation, which is a distinct operation.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of contexts, prerequisites, or scenarios where validation applies. The description merely states what it does without explaining when it should be called.

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