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

No annotations are provided, so the description carries full burden. It mentions legacy status, required API key, and that streaming is not recommended for MCP. However, it does not disclose rate limits, error behavior, response format, or side effects beyond the method descriptions. This is 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 front-loaded with a clear summary, then enumerates methods, and includes a highlighted important note. It is moderately concise; every sentence serves a purpose, though some details could be tightened.

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 12 parameters, 4 methods, and no output schema or annotations, the description is fairly complete. It explains tool purpose, usage, prerequisites, and the models pre-check. Absence of return value details is a minor gap, but overall adequate for the 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 all parameters described. The description adds context beyond the schema by explaining the methods and providing an important note about the 'models' method. This adds value, raising it above the baseline of 3.

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

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

The description clearly states the tool is a legacy AI Knowledge API for direct LLM completion without RAG. It lists distinct methods (chat, openai, embeddings, models) and contrasts with the newer LLM Gateway, making the purpose and scope immediately 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?

Explicitly directs users to use LLM Gateway for new direct model calls, providing an alternative. Also includes an important usage rule: before changing a model, call with method='models' to verify availability. This gives clear when-to-use and when-not-to-use guidance.

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

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

No annotations are provided, so the description must disclose behavioral traits. It explains the CRUD nature and lists methods, but lacks details on side effects, idempotency, error handling, rate limits, or what happens on mutation operations. For a complex tool with 19 parameters, this 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 well-structured, front-loading the legacy status and alternative recommendation, then listing methods. It is concise yet informative, though the methods list could be slightly more compact. Overall, it earns its 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?

Given the high parameter count, nested objects, and multiple methods, the description provides a general overview but lacks specifics on how each method uses parameters, expected return values, or error scenarios. It is adequate for a high-level understanding but not fully complete for an agent to invoke correctly without additional inference.

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, so baseline is 3. The description reiterates the method parameter and required API key, but adds no new meaning or context for the other 17 parameters. It does not explain parameter interdependencies or usage patterns 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 is a legacy AI Knowledge API for document CRUD operations and lists the available methods. It distinguishes itself from siblings by marking it as legacy and directing to use Storage files/vector_stores APIs for new RAG data, but does not explicitly compare to sibling tools.

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

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

The description implies usage for legacy AI Knowledge document management and mentions the need for a legacy project API key. However, it does not explicitly specify when to use or avoid this tool relative to siblings, nor provide clear alternative recommendations beyond the storage APIs.

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 explains auth requirements and legacy status but does not disclose potential side effects (e.g., deletion irreversibility, update impacts), rate limits, or error conditions. For a tool with multiple methods and parameters, more behavioral context would be beneficial.

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

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

The description is well-structured with clear sections for legacy context, auth methods, and method lists. It is front-loaded with the key message. While it is relatively long, it earns its length by providing necessary differentiation. Minor redundancy could be trimmed, but overall it is 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 complexity (17 params, multiple methods, two auth modes), the description covers auth and method groupings well. However, it lacks details on return values (no output schema), error handling, and specific behavioral outcomes for each method. The 'create' method mentions returning an apiKey, but other methods are less described. Some gaps remain.

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 17 parameters have schema descriptions (100% coverage). The description adds significant value by grouping parameters by auth method (apiKey vs Bearer token) and listing which params are required for each method. It clarifies the method enum and explains the ai nested object. This goes beyond the 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 the tool is for 'Legacy AI Knowledge API: project/agent management' and lists the supported methods. It distinguishes itself from the newer Agent Factory APIs. While the name and sibling tools like ai_knowledge_completion and ai_knowledge_document suggest the domain, the description could more explicitly contrast with these sibling tools, but overall purpose is 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 explicitly separates methods requiring apiKey from those using Bearer token, and specifies when workspaceName is needed. It advises against using this legacy API for new agents, directing to Agent Factory. It does not directly compare with sibling tools, but the operational context (project management vs. completions/documents) is implicitly 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?

Discloses legacy nature, requirement for specific API key, and the two operational modes. Though read-only is implied, it does not explicitly state no side effects, but this is reasonable for a query tool. No annotations to contradict.

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?

Four concise sentences, each providing essential information: purpose, alternatives, method behaviors, and authentication. No redundancy, front-loaded with key distinction.

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?

Covers usage and authentication well, but lacks description of return format or response structure. Given no output schema, this is a gap. Otherwise complete for the core functionality.

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 critical context for 'method' (default and behaviors) and 'apiKey' (source and requirement). Other parameters are well-documented in schema; description reinforces key choices.

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 is a legacy AI Knowledge API for querying projects with RAG or context retrieval. Distinguishes from newer Agent Factory alternatives and differentiates between two methods (query and context).

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 advises against using for new one-product agents, directing to Agent Factory tools. Clearly explains when to use 'query' vs 'context', and notes the requirement for a legacy API key.

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?

Beyond the readOnlyHint=false annotation, the description adds critical behavioral context: the token is never exposed to the model, and it details authentication nuances for apiKey, asSession, and withUserBearer. It does not explicitly state that the tool can modify data, but that is implied by the annotation and the ability to use methods like POST.

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, well-structured paragraph with no fluff. Every sentence serves a purpose, front-loading the core purpose and authentication before diving into parameter details. It efficiently handles 9 parameters.

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 could explain return format or error handling, but it does cover projection via 'pick'. For a generic API caller, this is largely sufficient, though a note on response structure would be beneficial.

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?

With 100% schema coverage, the description adds significant value by explaining path base, method defaults, optional leading slash, authentication details (apiKey vs asSession), and the interplay of withUserBearer. It clarifies security and parameter combinations 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 calls any Prisme.ai REST API endpoint, with explicit mention that it's for endpoints not covered by dedicated tools. It distinguishes itself from sibling tools by listing examples like '/orgs' and '/me' that are not covered.

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

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

It explicitly says to use for endpoints not covered by dedicated tools, giving concrete examples. It implies not to use when a dedicated tool exists, providing clear context and alternatives.

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

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

No annotations provided, and the description does not disclose behavioral traits like idempotency, side effects, permissions, or duplicate behavior. Only the basic creation action is stated.

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

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

The description is a single concise sentence that front-loads the action. It could be slightly more informative without becoming verbose, but it is not overly long.

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

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

Given the complexity (nested automation object, multiple workspace identifiers, environment), the description lacks context on prerequisites, return value, and overall workflow. Schema helps but description is insufficient.

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 detailed parameter descriptions, so the description adds no extra semantic value beyond what is in the schema. Baseline 3 applies.

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

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

The description clearly states the verb 'Create' and the resource 'automation in the Prisme.ai workspace', distinguishing it from sibling tools like update_automation or delete_automation.

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 (e.g., validate_automation first, create_workspace if workspace missing). No exclusions or prerequisites mentioned.

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

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

No annotations exist, so the description must disclose behavioral traits. It states 'Create' implying mutation, but does not mention idempotency, permissions, or side effects. Missing important context for a write operation.

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

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

Two efficient sentences with no wasted words. The action and return value are 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 no output schema, the description mentions return value, but lacks behavioral transparency and usage guidelines. The nested input schema is well-documented, but the description does not compensate for missing annotations or provide complete context for a creation 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 baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions; it does not clarify the workspace object structure or environment parameter.

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

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

The description clearly states the action 'Create a new Prisme.ai workspace' and specifies it returns the workspace with its ID, which distinguishes it from sibling tools like push_workspace or search_workspaces.

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 push_workspace or unlock_workspace. The description lacks context for usage decisions.

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 annotation includes destructiveHint: true, which already signals a mutating operation. The description only says 'Delete' without adding details like irreversibility, cascading effects, or required permissions. For a destructive tool, more behavioral context is needed.

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, well-structured sentence that immediately conveys the tool's purpose. No superfluous words or 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?

Given the destructive nature (highlighted by annotation), the description lacks crucial context such as permanence, required permissions, or confirmation steps. No output schema is provided, but the description doesn't set expectations for the result.

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 parameters are fully described in the input schema. The description adds no additional meaning beyond what the schema already provides. 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 action (Delete) and the target (an automation from the prisme.ai workspace). It directly distinguishes the tool from siblings like create_automation, update_automation, and execute_automation.

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 vs alternatives, nor are there any prerequisites or conditions for deletion mentioned. The agent receives no context about when deletion is appropriate or safe.

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?

Annotations already provide destructiveHint=true, indicating the tool is destructive. The description adds no further behavioral context beyond what annotations already communicate, e.g., permissions, cascading effects, or 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 a single, concise sentence with no fluff. However, it is almost too brief and could benefit from additional context without being overly verbose.

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

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

For a destructive action with 4 parameters and no output schema, the description is insufficient. It does not explain return values, permanent effects, or how parameters like environment and workspaceId relate to workspaceName.

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 each parameter already documented. The description does not add extra meaning beyond the schema's parameter descriptions, so 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 action (delete), resource (file), scope (from workspace storage), and method (by id). It effectively distinguishes from sibling tools like get_file, upload_file, list_files.

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

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

The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It lacks context like when deletion is appropriate or irreversible.

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?

Annotations provide only openWorldHint, no behavioral traits. Description does not disclose side effects, idempotency, authorization needs, or rate limits. For an execution tool, this 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?

Single sentence front-loaded with the action and resource. 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?

Tool has 5 parameters, 2 required, including nested objects. Description omits parameter relationships (e.g., workspaceName vs workspaceId vs environment), error handling, and output. Lacks completeness for effective selection.

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 parameters are well-described in schema. Description adds minimal value beyond 'optional payload'. Baseline 3 applies.

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

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

Description clearly states verb 'execute/test' and resource 'automation already existing in the Prisme.ai workspace', distinguishing it from create/delete/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 explicit guidance on when to use this tool versus siblings like 'validate_automation' or 'get_automation'. Implies existing automations but lacks context on prerequisites or alternatives.

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

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

Annotations already indicate readOnlyHint=true. The description adds that the tool returns configuration schema and automations, providing behavioral context beyond the annotation.

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 sentences, front-loaded with the core action, and no wasted 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?

For a simple read tool with no output schema, the description sufficiently explains what is returned and why to use it. Could mention that it is read-only, but annotation covers that.

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 both parameters. The description adds minimal extra value, only confirming the case-sensitive nature of appSlug which is already in the schema.

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

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

The description clearly states the tool retrieves an app from the app store with its configuration schema and automations. While it doesn't explicitly differentiate from siblings like 'get_app_instance', the purpose is specific enough.

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 provides a clear use case: 'understand what config an app requires before installing it in the imports folder.' It also notes the appSlug case-sensitivity, giving practical 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?

The readOnlyHint annotation already signals a safe read operation, so the description's lack of additional behavioral context (e.g., permissions, rate limits) is acceptable. The description adds minimal value beyond the annotation.

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 redundancy or extraneous information. Every word contributes to the purpose.

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

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

The description lacks information about what 'details' are returned and does not differentiate from similar tools like get_app_instance_config. Given no output schema, this is a moderate gap.

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

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

The input schema has 100% description coverage; all parameters are already documented. The description only reinforces the 'by its slug' aspect, adding no new semantic meaning beyond the schema.

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

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

The description clearly states the tool retrieves details of an installed app instance using its slug. It distinguishes itself from siblings like list_app_instances (which lists all instances) and get_app_instance_config (which gets configuration only).

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

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

The description provides no guidance on when to use this tool versus alternatives like list_app_instances or get_app. It does not mention prerequisites or conditions for use, 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?

Annotations already mark the tool as readOnlyHint=true, so the description doesn't need to reiterate safety. It adds value by specifying that only the configuration is returned, not other instance details. No contradictions with annotations.

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

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

The description is a single, front-loaded sentence that directly states the tool's purpose. No 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?

For a read-only tool with complete schema annotations and a clear purpose, the description is adequately complete. The return value (configuration) is implied, and no output schema is needed.

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 input schema already documents all parameters comprehensively. The description adds no additional parameter meaning, which is acceptable given full schema coverage.

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

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

The description uses a specific verb 'Get' and clearly identifies the resource 'configuration of an installed app instance'. It distinguishes from sibling tools like get_app_instance (which likely returns full instance) and update_app_instance_config (which modifies config).

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 'only the configuration' implies a subset of functionality compared to get_app_instance, but no explicit when-to-use or when-not-to-use guidelines are provided. Alternatives or prerequisites are not mentioned.

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

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

Annotations already declare readOnlyHint=true, and the description's 'Get' aligns with a read operation. However, the description adds no additional behavioral context beyond the annotation, such as authentication requirements or possible return of null if not found. With annotations present, a score of 3 is appropriate.

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 of 10 words with no redundancy or filler. It front-loads the purpose efficiently.

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

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

Given no output schema, the description should at least mention what is returned (e.g., the automation object). It also lacks any note about conditions like 'automation must exist' or 'requires workspace name as slug'. The tool has 4 parameters but the description omits that environment is optional or that workspaceId is alternative. Completeness is insufficient for a tool with this 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?

All parameters have schema descriptions (100% coverage), so the schema already documents each parameter. The description's mention of 'by its slug' does not add meaning beyond the schema's description of automationSlug. Baseline score 3 is correct.

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 'Get', the resource 'automation', and the identifier 'by its slug' with scope 'from the prisme.ai workspace'. It distinguishes well from sibling tools like list_automations, create_automation, 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?

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, conditions, or when it is appropriate to use this tool instead of list_automations or other related tools.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a File object with specific fields (url, name, mimetype, size, metadata), but does not mention error behaviors, permission requirements, or side effects. Minimal viable 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?

Two concise sentences, front-loaded with the core action. Every word serves a purpose 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?

The description mentions the return object fields, which partially compensates for missing output schema. However, it lacks context on error cases, parameter relationships (e.g., workspaceName vs workspaceId), and environment handling. Adequate for a simple get operation but not comprehensive.

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 describes all parameters. The description adds value by listing return fields but does not enhance parameter understanding (e.g., fileId vs workspaceName usage). 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?

The description clearly states the verb 'Get', the resource 'metadata for a single file', and the input 'by id'. It differentiates from sibling tools like list_files and delete_file by specifying a single file 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?

No explicit guidance on when to use this tool vs alternatives like list_files or delete_file. The description does not mention prerequisites, workspace context, 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?

Annotations already provide readOnlyHint: true, and the description confirms it's a read operation ('Returns'). The description adds value by detailing the sections and their content, but does not disclose any additional behavioral traits beyond what annotations already indicate.

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 starts with a clear instruction, then lists sections with brief descriptions. While the list is lengthy, it is necessary for the tool's purpose. It is well-structured and front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete. It explains the tool's purpose, usage, and all possible parameter values comprehensively.

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% with a clear description for the 'section' parameter. The description adds significant meaning by listing all sections and their descriptions, going beyond the schema's enum list.

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 'Returns Prisme.ai documentation by section', specifying the verb (returns), resource (documentation), and the action (by section). It distinguishes itself from sibling tools, which are primarily operational (create, delete, get app, 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?

The description provides clear usage guidance: 'Call with 'index' first to see available sections.' It also lists all available sections with descriptions, helping the agent choose. However, it does not explicitly mention when not to use or alternatives, but the context makes it 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?

The description aligns with the readOnlyHint annotation and states 'Retrieve' indicating a read operation. No additional behavioral traits are disclosed, but annotations cover the main safety profile.

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

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

The description is a single sentence with no unnecessary words, front-loading the key action and resource. Every word 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?

While the schema covers parameters well, the description lacks information about the return format (e.g., list of reports) or pagination behavior. Given moderate complexity, the description is functional but could be more complete.

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

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

Schema description coverage is 100% with all parameters described. The description does not add extra meaning beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states the verb 'Retrieve' and the resource 'bug reports and feedback' with scope 'submitted about the Prisme.ai MCP tools'. It distinguishes from siblings like report_issue_or_feedback (submit) and update_report (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?

The description implies reading reports but does not explicitly state when to use this tool versus alternatives like report_issue_or_feedback or update_report. Usage context is implied but not guided.

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

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

No annotations are present, so the description must fully disclose behavioral traits. It only states 'Install... into a workspace' without mentioning permissions, side effects, error conditions, or what happens if the app already exists. This is insufficient 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 with no unnecessary words. It is front-loaded with the core action and purpose, and every part earns its place. Maximum efficiency.

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

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

Given the complexity (nested object, 4 parameters, no output schema, no annotations), the description is too minimal. It does not explain what happens on success, return values, error scenarios, or prerequisites beyond the get_app hint. The tool needs more contextual information to be fully usable.

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 mentioning the app's configuration schema, but does not elaborate on parameter semantics 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 action (Install) and the resource (app from Prisme.ai store into a workspace). It distinguishes the tool from siblings like get_app or list_apps, but doesn't explicitly mention that it creates an instance, which would elevate it to 5.

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

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

The description advises to use get_app first to understand the configuration schema, which provides useful context. However, it lacks explicit when-to-use or when-not-to-use guidance, and no alternatives are mentioned, limiting 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?

Annotations already declare `readOnlyHint: true`, so the description does not need to reaffirm safety. It adds value by specifying the exact fields returned (slug, appSlug, appName, disabled), which helps the agent understand the output format.

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

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

Two sentences, each earning its place. The first states purpose and scope, the second provides sibling differentiation. No redundant information.

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

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

For a simple list tool with good schema coverage and annotations, the description is nearly complete. It lacks mention of pagination or ordering, but given the tool's simplicity and the provided return fields, it is sufficiently informative.

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 does not add additional meaning beyond the schema—no guidance on when to use `workspaceName` vs `workspaceId`, or how `environment` relates. This is adequate but not enhanced.

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 installed app instances in a workspace, with a specific verb and resource. It distinguishes itself from `get_app_instance` by noting it returns only summary info, and suggests using the sibling for full details.

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

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

Explicitly states when to use this tool (for a summary list of app instances) and when not to (use `get_app_instance` for full details). This provides clear context for an agent to choose correctly among sibling tools.

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

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

Annotations already declare readOnlyHint=true, so the tool is safe but the description adds no further behavioral context such as pagination, rate limits, or behavior when no results are found. The description does not contradict annotations.

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

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

The description is a single sentence, concise and to the point. It is front-loaded with the essential action. However, it may be too brief for a tool with 7 parameters.

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 7 parameters and no output schema, the description is overly minimal. It does not explain return format, pagination behavior, or how search keywords interact with other filters. The tool likely returns a list, but the agent is left guessing.

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 7 parameters described inline. The description does not add additional meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches apps from the Prisme.ai app store, using a specific verb and resource. It is distinct from sibling tools like get_app (single app) and list_app_instances (instances). However, it could further specify that it lists multiple apps and the search 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?

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or limitations. The single sentence lacks any usage 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?

Annotations already indicate readOnlyHint=true; the description adds no further behavioral context (e.g., pagination, limits). It is consistent but not additive.

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

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

The description is a single sentence that directly conveys the tool's purpose without any 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?

The description adequately covers the tool's basic function for a read-only list operation with one required parameter. However, it could mention expected output (e.g., list of automation IDs/names) for fuller 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 parameters; the tool description adds no additional meaning, 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 action (list) and resource (automations) with scoping (in the Prisme.ai workspace), distinguishing it from siblings like get_automation or list_apps.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives (e.g., get_automation for single item or search tools). Usage is implied but not stated.

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

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

No annotations are provided, so the description carries the full burden. It discloses pagination, sorting, and filtering behavior but does not mention read-only nature, permissions, rate limits, or side effects. Adequate for a simple list operation but lacks depth.

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

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

The description is a single sentence that front-loads the primary action ('List files in the Prisme.ai workspace') and lists supported features. No wasted words, appropriately 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?

With no output schema, the description could mention return format (e.g., list of file objects). It does not. However, the core action (listing files) is clear, and the required parameter is implicit from the schema. Completeness is adequate 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 baseline is 3. The description adds 'Elasticsearch-style filtering' context for the query parameter, clarifying its format beyond the schema's generic 'filter object'. This adds meaningful value. Other parameters are not elaborated, but the key parameter benefits.

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 files in a workspace and mentions key capabilities (pagination, sorting, filtering). It differentiates from sibling tools like delete_file or get_file, but could explicitly contrast with other list tools (e.g., list_automations).

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not include when-not-to-use conditions, prerequisites, or exclusions. Only capabilities are stated.

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

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

With no annotations, the description is the sole source for behavioral disclosure. It reveals that first publish creates an app and later publishes update it, but does not clarify whether it creates a new version or overwrites, or what privileges are required.

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 concisely convey the core functionality and key conditional behavior. No extraneous 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 7 parameters and no output schema, the description is brief. It lacks details about return values, side effects on existing app versions, and permission requirements that would help the agent fully understand 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?

All 7 parameters have schema descriptions (100% coverage). The tool description adds value by explaining the slug parameter's conditional requirement (first publish). This contextual detail slightly exceeds the baseline of 3.

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

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

The description clearly states the tool publishes a workspace as a new app version in the Prisme.ai app store. It differentiates first publish (requires slug) from updates, but does not explicitly contrast with sibling tools like push_workspace or push_workspace_version, leaving potential ambiguity.

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

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

The description implies when to use this tool (publishing to app store) and mentions the slug requirement for first publish, but offers no explicit guidance on when not to use it or what alternatives exist 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?

Discloses that files will be overwritten, which is critical. However, no annotations exist, so description should also mention auth requirements or failure modes, which it does not.

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: two sentences, front-loaded with action, second adds critical behavior. 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?

Description covers main purpose and overwrite behavior, but lacks details on parameter usage, return value, and error handling. With no output schema, more context is needed.

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%, baseline 3. Description adds no additional meaning beyond schema; does not explain parameter relationships or tradeoffs.

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 downloads and extracts a workspace. It is specific with verb and resource, but does not differentiate from sibling 'pull_workspace_version'.

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 'pull_workspace_version' or 'push_workspace'. Lacks context for usage conditions.

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

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

Annotations mark it as destructive, and the description confirms by mentioning rollback/import. Adds detail about selector validation (returns available repos on incorrect guess). However, it doesn't specify what exactly gets destroyed or overwritten, but annotations already signal destructiveness.

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?

Well-structured with bold warnings and bullet-like instructions. Front-loaded with main purpose. Could be slightly more concise, but the extra detail is justified for clarity. No redundant sentences.

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

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

Despite lacking an output schema, the description explains the meaningful return field (pulledFromGit) and error handling (returns list of platform repos). It covers the main use cases and retry logic. Could mention the full response structure, but for a 6-param tool with 2 required, it's fairly 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 parameters are already documented. The description adds value by explaining mutual exclusivity of gitPlatform and repositoryId, the retry mechanism, and preference for gitPlatform. This goes beyond the schema descriptions.

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

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

The description clearly states two distinct actions: pulling from git or rolling back/importing an existing version. It uses specific verbs (pull, roll back, import) and the resource (workspace version). This differentiates it from sibling tools like push_workspace_version or pull_workspace.

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?

Explicit instructions on when to use gitPlatform vs repositoryId, warning that omitting both is only valid for rollback. Includes retry guidance if gitPlatform is unknown. Clearly states when not to call (without selectors) and alternatives (retry with gitPlatform).

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?

Annotations already indicate destructiveHint=true. The description adds value by mentioning the backup creation behavior and the version name constraints (max 15 chars, allowed characters). However, it does not disclose default behavior of the prune parameter (which deletes remote files) or other side effects, leaving gaps in 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 composed of two sentences, with the primary action in the first sentence and a key constraint in the second. It is concise, front-loaded, and contains 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 tool with 6 parameters (3 required), a destructive hint, and no output schema, the description is incomplete. It omits details about the prune parameter's default (true), guidance on choosing between workspaceName and workspaceId, the environment parameter, and return value information. These gaps make it insufficient for fully informed 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 description coverage is 100%, so each parameter is already documented. The description reinforces the constraint on 'message' (max 15 chars, specific characters) but does not add meaning to other parameters beyond their schema descriptions. Overall, it provides marginal additional value.

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

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

The description clearly states the verb 'Upload' and the resource 'local workspace directory to Prisme.ai', and adds the distinctive action 'Creates a backup version before importing'. This distinguishes it from sibling tools like pull_workspace.

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

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

The description implies usage when uploading local workspace content to Prisme.ai, but it does not explicitly state when to use this tool versus alternatives like push_workspace_version or pull_workspace. No exclusion criteria or alternative suggestions 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?

Beyond the 'destructiveHint: true' annotation, the description discloses that a successful push holds a ~30 min write lock and how to release it with unlock_workspace. It also explains the response flag 'pushedToGit: true|false' and retry logic, adding valuable behavioral context not present in annotations.

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

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

The description is well-organized with clear sections (general instruction, selector choice, response, common errors, post-behavior). It is thorough without being overly verbose; a few sentences could be tightened, but overall it efficiently conveys critical information.

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

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

Given the tool's complexity (7 parameters, destructive action, no output schema), the description covers all essential aspects: mandatory selectors, error recovery, write lock duration, and response interpretation. It leaves no significant gaps for correct 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?

With 100% schema coverage, baseline is 3. The description adds meaningful context: for gitPlatform it explains preferred use, for description it clarifies it's used as commit message and warns about localized objects causing stringification issues. This goes beyond what the schema alone 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 tool pushes a workspace to a git repository by creating a new version. It distinguishes the action as version-creation plus git push, which differentiates it from sibling tools like 'push_workspace' and 'pull_workspace_version'.

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 explicit guidance on when to use gitPlatform vs repositoryId, including a strong instruction to always pass a selector for git pushes. Also covers common errors (400 'not up-to-date') and post-success behavior (write lock). This enables correct tool selection and invocation.

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

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

The description adds behavioral context beyond the readOnlyHint annotation, such as the timing and scope of use (proactive, mid-task). It does not contradict the annotation. While it doesn't detail all side effects, it provides sufficient guidance for using the tool appropriately.

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 (approx. 130 words) and well-structured. It front-loads the primary purpose, follows with usage guidance, and uses bullet points for clarity. Every sentence contributes meaningful information 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 the tool's simplicity (3 parameters, 2 required, no output schema), the description is thorough. It covers when, why, and how to use the tool, including examples. The optional context field is explained, though a bit more detail on its structure could enhance completeness, but it is still adequate.

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

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

The schema covers all parameters (100% coverage), but the description adds significant value by clarifying the intent of the 'message' parameter with good and bad examples ('GOOD: ... / BAD: ...'). This helps the agent understand the semantic boundary of acceptable input, which is not evident from the 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 the tool's purpose: reporting bugs or feedback about Prisme.ai MCP tools. It uses the specific verb 'report' and identifies the resource ('issue_or_feedback'). It distinguishes itself from sibling tools by being the only tool for this function.

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 instructs proactive use ('Use PROACTIVELY when you encounter issues - even mid-task. Don't wait for task completion.') and lists specific triggers (tool errors, misleading documentation, missing constraint information). It also clearly delineates what to report (guidance improvements) vs. what not to (API behavior changes) with concrete examples.

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?

Annotations already declare readOnlyHint=true; description adds valuable context such as the need to use @timestamp over timestamp and the meaning of SearchError events, enhancing 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?

Well-structured with sections (EVENT STRUCTURE, COMMON QUERIES, etc.), front-loaded with purpose. Slightly long but justified for the complexity.

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 no output schema, the description explains event structure and covers common use cases, parameter usage, and potential issues, making it fully contextually 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 descriptions, yet the description adds extra meaning with examples and common queries, going beyond what the schema 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 it searches for events in a Prisme.ai workspace using Elasticsearch DSL. It provides specific verb-resource and is well-distinguished from sibling tools like search_workspaces or ai_knowledge_query.

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 extensive usage guidance including common queries, sorting tips, and handling of SearchError events. Lacks explicit 'when not to use' but given distinct purpose, it 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?

Annotations already declare read-only, and description adds that it returns workspace IDs and names. Does not contradict annotations, but doesn't mention pagination or other behaviors.

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, no fluff, front-loaded with purpose and immediate use case.

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?

Covers main purpose and use case; pagination and labels details are in schema. Lacks mention of required environment parameter, but schema covers it.

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

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

Schema coverage is 100%, description adds context that search works across name, description, or slug, which is not explicit in 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 searches for workspaces by name, description, or slug, and returns IDs and names. Distinguishes from siblings like create_workspace and pull_workspace.

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 to use when you need a workspaceId from text search. Does not list alternatives or 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?

With no annotations, the description fully covers behavioral traits: it warns that the token travels through the chat and is sent to the LLM provider, explains validation via a probe call, states that persistence is to credentials.json with mode 600, and that invalid tokens persist nothing. This comprehensively sets expectations.

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 longer than minimal but every sentence earns its place: purpose, privacy warning, CLI alternative, parameter usage, and behavioral details are all essential. It front-loads the core action and guidance, making it easy to scan.

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

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

Given the tool has 4 parameters and no output schema, the description provides complete context: explains token validation, persistence details, privacy implications, and precise usage conditions. There are no gaps in understanding how to use the tool safely and effectively.

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

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

Schema coverage is 100%, but the description adds meaningful context beyond the schema. It explains that apiUrl is required for registering a new environment (though not in schema's required list), and that studioUrl is optional for token-creation links. This clarifies parameter roles beyond basic descriptions.

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

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

The description clearly states the tool's purpose: 'Register (or rotate) a user-created Prisme.ai API token for an environment.' This is a specific action on a distinct resource, and no sibling tool performs token registration, making it easily distinguishable.

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 explicit guidance on when to use this tool vs. the alternative: it strongly recommends the out-of-band CLI, explains privacy risks, and states to only use this tool if the user explicitly chooses to paste the token. It also clarifies when to provide apiUrl and studioUrl for new environment registration.

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?

Annotations already declare destructiveHint: true, so the description merely repeats the concept of uninstallation. It does not add beyond annotations, such as whether the action is reversible or what dependencies are affected.

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 no extraneous words. Highly 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 4 parameters, no output schema, and destructive nature, the description is too bare. Missing details on consequences, required permissions, or post-uninstall state. Could mention if it requires admin privileges or cascading 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?

All 4 parameters have schema descriptions, so the description adds no extra meaning. Baseline 3 is appropriate as it does not detract but also does not enhance understanding of parameter 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 verb 'uninstall' and the resource 'app instance from a workspace', differentiating it from siblings like install_app_instance or get_app_instance. However, it lacks specificity about the scope (e.g., permanent removal, impact on data).

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., delete_file or update_app_instance). No conditions, prerequisites, or context for choosing this over similar tools 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?

Annotations already indicate destructiveHint=true. The description adds that the tool removes a write lock, but does not elaborate on side effects, irreversibility, or required permissions. The added behavioral context is limited.

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, 18 words, no fluff. The purpose and use case are front-loaded. Very concise and efficient.

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

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

Given the tool is destructive and has three optional parameters, the description lacks details on how to use the parameters effectively, any prerequisites, or consequences. It is incomplete for safe usage.

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

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

Schema coverage is 100%; all three parameters are documented in the input schema. The description adds no additional meaning or usage guidance for the parameters beyond what the schema 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 verb 'Remove' and the resource 'write lock from a Prisme.ai workspace'. It also provides a specific use case, distinguishing it from sibling tools like pull/push workspace.

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

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

The description gives a usage scenario ('Use this when a workspace is stuck in a locked state') but does not provide when not to use, prerequisites, or alternatives. It is minimal 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 present, so the description must disclose behavioral traits. It fails to mention whether updates are partial or full replacement, permission requirements, idempotency, or side effects. This is a significant gap for a mutation tool.

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

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

The description is a single concise sentence with parenthetical enumeration of fields. It is front-loaded and efficient, though it could be slightly more structured with clear separation of 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?

Given the tool performs an update with nested objects and no output schema, the description should mention return value, error conditions, or confirmation of success. It provides none of this, leaving the agent without essential context.

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

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

Schema description coverage is 100%, so the schema already documents all parameters adequately. The description adds a summary of updatable fields, but no extra semantic detail 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 explicitly states the action ('Update'), the resource ('installed app instance'), and the specific fields ('config, disabled status, labels'). This clearly distinguishes it from sibling tools like update_app_instance_config (config only) or install/uninstall.

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., update_app_instance_config) or prerequisites. The agent receives no context about invocation conditions or exclusions.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states 'Update only the configuration', indicating mutation. However, it omits details on idempotency, side effects, or response behavior. The merge behavior is hinted in the schema for the 'config' parameter but not in the main description, thus failing to add sufficient behavioral context.

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

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

The description is a single concise sentence with no waste. It is front-loaded with the key action and scope. However, for a tool with five parameters and potential behavioral nuance, it could be slightly more informative while remaining 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 complexity (mutation with no output schema, no annotations), the description is insufficiently complete. It does not describe what happens after a successful update, error conditions, or prerequisites like required permissions. The phrase 'only the configuration' adds some context but leaves major gaps.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema; it does not elaborate on any parameter. Each parameter's purpose is adequately described in the schema, so no penalty.

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 'Update' and the resource 'configuration of an installed app instance', with 'only' specifying the scope. This distinguishes it from the sibling tool 'update_app_instance' which likely updates other fields. However, it does not elaborate on what 'configuration' encompasses.

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 only updating configuration (vs. other attributes) but provides no explicit guidance on when to use this tool versus alternatives like 'update_app_instance' or when not to use it. No usage context or prerequisites are given.

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

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

Annotations already provide destructiveHint=true. Description only says 'Update an existing automation', which is redundant with the name. No additional behavioral context like permissions, side effects, or confirmation needed.

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 is concise and includes essential information. Could be front-loaded with the purpose, but still efficient.

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

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

Missing return value description; no output schema. For an update tool with nested objects and 5 params, description should mention what the tool returns or confirms (e.g., updated automation object). Annotations indicate destructive, but behavioral completeness is lacking.

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

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

Schema description coverage is 100% and includes detailed nested property descriptions (e.g., 'name' and 'do' are required even for partial updates). Description adds no extra parameter meaning, so 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?

Description clearly states verb 'Update' and resource 'automation' on 'prisme.ai workspace', distinguishing it from create, delete, get, and execute automation tools.

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

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

No explicit guidance on when to use vs alternatives (e.g., create_automation, delete_automation). The name implies updating existing automation, but no when-not 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. Only says 'update' without mentioning side effects, permissions, reversibility, or response behavior. Minimal 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?

Very concise, two sentences plus bullet list. Front-loaded with action. Slightly repetitive but efficient.

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

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

Schema is fully described, but no output schema exists and description doesn't mention return values. Adequate for basic use, but incomplete for an agent expecting result 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 descriptions cover all parameters 100%. Description adds examples mapping parameters to use cases, but does not provide new semantic detail 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?

The description clearly states 'Update an existing bug report or feedback' with specific verbs and resources. It distinguishes from sibling tools like 'report_issue_or_feedback' (create) and 'get_reports' (read).

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 explicit use cases: cancel, edit message, change type. Implicitly distinguishes from creation via sibling context, but lacks an explicit 'do not use for creation' statement.

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 covers return fields, source fetching behavior, defaults (public, fileName), and best-effort expiration, but lacks details on authentication needs, error handling, file size limits, or what happens if file already exists.

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

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

Single paragraph, front-loaded with main purpose and return fields, then explains source options efficiently with 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, so description compensates by listing return fields and explaining source methods. Covers optional parameters but misses constraints like file size limits or error scenarios; mostly 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%, baseline 3. Description adds value by clarifying mutual exclusivity of source parameters, default fileName logic, and workspace resolution, which goes beyond schema descriptions.

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

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

Description clearly states 'Upload a file to the Prisme.ai workspace's file storage' and lists return fields, distinguishing it from sibling tools like delete_file, get_file, and list_files.

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?

Describes the three mutually exclusive source options (path, url, dataUri) and exactly one must be set, but does not explicitly state when not to use this tool or compare to siblings for file operations.

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

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

Description adds behavior beyond annotations: lists what it checks (schema, expressions, naming), file types, and that it returns warnings alongside errors. Annotations provide readOnlyHint=true, which is consistent. No contradictions.

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-sentence paragraph is fairly concise and front-loaded with main purpose. Could be more structured (e.g., bullet points for checks), but no unnecessary information.

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

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

No output schema, but description explains return values (warnings and errors). Covers main use cases. Could mention if validation is synchronous or requires workspace context, but overall complete for a validation 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 baseline is 3. Description adds value by explaining preference for path over automation, and mentions optional strict mode. However, validateExpressions parameter is not mentioned in description.

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

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

Description clearly states 'Validate Prisme.ai automation(s)' with specific checks (schema compliance, expression syntax, etc.). This distinguishes it from sibling tools like execute_automation or create_automation.

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 clear context on when to use: accepts file path, folder, or automation object. Mentions preference for path over automation object. However, does not explicitly state when not to use or mention alternative tools for execution.

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